s7 is a Scheme implementation intended as an extension language for other applications, primarily Snd, Radium, Common Music, and Max/MSP through the Scheme For Max external. It exists as just two files, s7.c and s7.h, that want only to disappear into someone else's source tree. There are no libraries, no run-time init files, and no configuration scripts. It can be built as a stand-alone interpreter (see below). s7test.scm is a regression test for s7. A tarball is available: s7 tarball. There is an svn repository at sourceforge (the Snd project): Snd, and a git repository (just s7): git@cm-gitlab.stanford.edu:bil/s7.git s7.git. Please ignore all other "s7" github sites. Christos Vagias created a web-assembly site with a repl: https://github.com/actonDev/s7-playground/.
s7 is the default extension language of Snd and sndlib (snd), Rick Taube's Common Music (commonmusic at sourceforge), and Kjetil Matheussen's Radium music editor. There are X, Motif, and openGL bindings in libxm in the Snd tarball, or at ftp://ccrma-ftp.stanford.edu/pub/Lisp/libxm.tar.gz. If you're running s7 in a context that has getenv, file-exists?, and system, you can use s7-slib-init.scm to gain easy access to slib. This init file is named "s7.init" in the slib distribution.
Although it is a descendant of tinyScheme, s7 is closest as a Scheme dialect to Guile 1.8. I believe it is compatible with r5rs and r7rs: you can just ignore all the additions discussed in this file. It has continuations, ratios, complex numbers, macros, keywords, hash-tables, multiprecision arithmetic, generalized set!, unicode, and so on. It does not have syntax-rules or any of its friends, and it does not think there is any such thing as an inexact integer.
This file assumes you know about Scheme and all its problems, and want a quick tour of where s7 is different. (Well, it was quick once upon a time). The main difference: if it's in s7, it's a first-class citizen of s7, and that includes macros, environments, and syntactic values.
I originally used a small font for scholia, but now I have to squint to read that tiny text, so less-than-vital commentaries are shown in the normal font, but indented and on a sort of brownish background.
All numeric types, integers, ratios, reals, and complex numbers are supported. The basic integer and real types are defined in s7.h, defaulting to int64_t and double. A ratio consists of two integers, a complex number two reals. pi is predefined. s7 can be built with multiprecision support for all types, using the gmp, mpfr, and mpc libraries (set WITH_GMP to 1 in s7.c). If multiprecision arithmetic is enabled, the following functions are included: bignum, and bignum?, and the variable (*s7* 'bignum-precision). (*s7* 'bignum-precision) defaults to 128; it sets the number of bits each float takes. pi automatically reflects the current (*s7* 'bignum-precision):
> pi 3.141592653589793238462643383279502884195E0 > (*s7* 'bignum-precision) 128 > (set! (*s7* 'bignum-precision) 256) 256 > pi 3.141592653589793238462643383279502884197169399375105820974944592307816406286198E0
bignum? returns #t if its argument is a big number of some type; I use "bignum" for any big number, not just integers. To create a big number, either include enough digits to overflow the default types, or use the bignum function. Its argument is either a number which it casts to a bignum, or a string representing the desired number:
> (bignum "123456789123456789") 123456789123456789 > (bignum "1.123123123123123123123123123") 1.12312312312312312312312312300000000009E0
For read-time bignums:
(set! *#readers*
(cons (cons #\B (lambda (str)
(bignum (string->number (substring str 1)))))
*#readers*))
and now #B123 is the reader equivalent of (bignum 123).
In the non-gmp case, if s7 is built using doubles (s7_double in s7.h), the float "epsilon" is around (expt 2 -53), or about 1e-16. In the gmp case, it is around (expt 2 (- (*s7* 'bignum-precision))). So in the default case (precision = 128), using gmp:
> (= 1.0 (+ 1.0 (expt 2.0 -128))) #t > (= 1.0 (+ 1.0 (expt 2.0 -127))) #fand in the non-gmp case:
> (= 1.0 (+ 1.0 (expt 2 -53))) #t > (= 1.0 (+ 1.0 (expt 2 -52))) #fIn the gmp case, integers and ratios are limited only by the size of memory, but reals are limited by (*s7* 'bignum-precision). This means, for example, that
> (floor 1e56) ; (*s7* 'bignum-precision) is 128 99999999999999999999999999999999999999927942405962072064 > (set! (*s7* 'bignum-precision) 256) 256 > (floor 1e56) 100000000000000000000000000000000000000000000000000000000The non-gmp case is similar, but it's easy to find the edge cases:
> (floor (+ 0.9999999995 (expt 2.0 23))) 8388609
s7 includes:
The random function can take any numeric argument, including 0. Other math-related differences between s7 and r5rs:
> (exact? 1.0) #f > (rational? 1.5) #f > (floor 1.4) 1 > (remainder 2.4 1) 0.4 > (modulo 1.4 1.0) 0.4 > (lcm 3/4 1/6) 3/2 > (log 8 2) 3 > (number->string 0.5 2) "0.1" > (string->number "0.1" 2) 0.5 > (rationalize 1.5) 3/2 > (complex 1/2 0) 1/2 > (logbit? 6 1) ; argument order, (logbit? int index), follows gmp, not CL #t
See cload and libgsl.scm for easy access to GSL, and similarly libm.scm for the C math library.
The exponent itself is always in base 10; this follows gmp usage. Scheme normally uses "@" for its useless polar notation, but that means
(string->number "1e1" 16)is ambiguous — is the "e" a digit or an exponent marker? In s7, "@" is an exponent marker.> (string->number "1e9" 2) ; (expt 2 9) 512.0 > (string->number "1e1" 12) ; "e" is not a digit in base 12 #f > (string->number "1e1" 16) ; (+ (* 1 16 16) (* 14 16) 1) 481 > (string->number "1.2e1" 3); (* 3 (+ 1 2/3)) 5.0What is
(/ 1.0 0.0)? s7 gives a "division by zero" error here, and also in(/ 1 0). Guile returns +inf.0 in the first case, which seems reasonable, but a "numerical overflow" error in the second. Slightly weirder is(expt 0.0 0+i). Currently s7 returns 0.0, Guile returns +nan.0+nan.0i, Clisp and sbcl throw an error. Everybody agrees that(expt 0 0)is 1, and Guile thinks that(expt 0.0 0.0)is 1.0. But(expt 0 0.0)and(expt 0.0 0)return different results in Guile (1 and 1.0), both are 0.0 in s7, the first is an error in Clisp, but the second returns 1, and so on — what a mess! This mess was made a lot worse than it needs to be when the IEEE decreed that 0.0 equals -0.0, so we can't tell them apart, but that they produce different results in nearly every use!scheme@(guile-user)> (= -0.0 0.0) #t scheme@(guile-user)> (negative? -0.0) #f scheme@(guile-user)> (= (/ 1.0 0.0) (/ 1.0 -0.0)) #f scheme@(guile-user)> (< (/ 1.0 -0.0) -1e100 1e100 (/ 1.0 0.0)) #tHow can they be equal? In s7, the sign of -0.0 is ignored, and they really are equal. One other oddity: two floats can satisfy eq? and yet not be eqv?:
(eq? +nan.0 +nan.0)might be #t (it is unspecified), but(eqv? +nan.0 +nan.0)is #f. The same problem afflicts memq and assq.The random function takes a range and an optional state, and returns a number between zero and the range, of the same type as the range. It is perfectly reasonable to use a range of 0, in which case random returns 0. random-state creates a new random state from a seed. If no state is passed, random uses some default state initialized from the current time. random-state? returns #t if passed a random state object.
> (random 0) 0 > (random 1.0) 0.86331198514245 > (random 3/4) 654/1129 > (random 1+i) 0.86300308872748+0.83601002730848i > (random -1.0) -0.037691127513267 > (define r0 (random-state 1234)) r0 > (random 100 r0) 94 > (random 100 r0) 19 > (define r1 (random-state 1234)) r1 > (random 100 r1) 94 > (random 100 r1) 19copy the random-state to save a spot in a random number sequence, or save the random-state as a list via random-state->list, then to restart from that point, apply random-state to that list.
I can't find the right tone for this section; this is the 400-th revision; I wish I were a better writer!
In some Schemes, "rational" means "could possibly be expressed equally well as a ratio: floats are approximations". In s7 it's: "is actually expressed (at the scheme level) as a ratio (or an integer of course)"; otherwise "rational?" is the same as "real?":
(not-s7)> (rational? (sqrt 2)) #tThat 1.0 is represented at the IEEE-float level as a sort of ratio does not mean it has to be a scheme ratio; the two notions are independent.
But that confusion is trivial compared to the completely nutty "inexact integer". As I understand it, "inexact" originally meant "floating point", and "exact" meant integer or ratio of integers. But words have a life of their own. 0.0 somehow became an "inexact" integer (although it can be represented exactly in floating point). +inf.0 must be an integer — its fractional part is explicitly zero! But +nan.0... And then there's:
(not-s7)> (integer? 9007199254740993.1) #tWhen does this matter? I often need to index into a vector, but the index is a float (a "real" in Scheme-speak: its fractional part can be non-zero). In one Scheme:
(not-s7)> (vector-ref #(0) (floor 0.1)) ERROR: Wrong type (expecting exact integer): 0.0 ; [why? "it's probably a programmer mistake"!]Not to worry, I'll use inexact->exact:
(not-s7)> (inexact->exact 0.1) 3602879701896397/36028797018963968 ; [why? "floats are ratios"!]So I end up using the verbose
(floor (inexact->exact ...))everywhere, and even then I have no guarantee that I'll get a legal vector index. I have never seen any use made of the exact/inexact distinction — just wild flailing to try get around it. I think the whole idea is confused and useless, and leads to verbose and buggy code. If we discard it, we can maintain backwards compatibility via:(define exact? rational?) (define (inexact? x) (not (rational? x))) (define inexact->exact rationalize) ; or floor (define (exact->inexact x) (* x 1.0))Standard Scheme's #i and #e are also useless because you can have any number after, for example, #b:
> #b1.1 1.5 > #b1e2 4.0 > #o17.5+i 15.625+1i(But s7 uses #i for int-vector and does not implement #e). Speaking of #b and friends, what should
(string->number "#xffff" 2)return?
define* and lambda* are extensions of define and lambda that make it easier to deal with optional, keyword, and rest arguments. The syntax is very simple: every argument to define* has a default value and is automatically available as a keyword argument. The default value is either #f if unspecified, or given in a list whose first member is the argument name. The last argument can be preceded by :rest or a dot to indicate that all other trailing arguments should be packaged as a list under that argument's name. A trailing or rest argument's default value is () and can't be specified in the declaration. The rest argument is not available as a keyword argument.
(define* (hi a (b 32) (c "hi")) (list a b c))
Here the argument "a" defaults to #f, "b" to 32, etc. When the function is called, the argument names are set from the values passed the function, then any unset arguments are bound to their default values, evaluated in left-to-right order. As the current argument list is scanned, any name that occurs as a keyword, :arg for example where the parameter name is arg, sets that argument's new value. Otherwise, as values occur, they are plugged into the actual argument list based on their position, counting a keyword/value pair as one argument. This is called an optional-key list in CLM. So, taking the function above as an example:
> (hi 1) (1 32 "hi") > (hi :b 2 :a 3) (3 2 "hi") > (hi 3 2 1) (3 2 1)
See s7test.scm for many examples. (s7's define* is very close to srfi-89's define*). To mark an argument as required, set its default value to a call on the error function:
> (define* (f a (b (error 'unset-arg "f's b parameter not set"))) (list a b)) f > (f 1 2) (1 2) > (f 1) error: f's b parameter not set
The combination of optional and keyword arguments is viewed with disfavor in the Lisp community, but the problem is in CL's implementation of the idea, not the idea itself. I've used the s7 style since around 1976, and have never found it confusing. The mistake in CL is to require the optional arguments if a keyword argument occurs, and to consider them as distinct from the keyword arguments. So everyone forgets and puts a keyword where CL expects a required-optional argument. CL then does something ridiculous, and the programmer stomps around shouting about keywords, but the fault lies with CL. If s7's way is considered too loose, one way to tighten it might be to insist that once a keyword is used, only keyword argument pairs can follow.
A natural companion of lambda* is named let*. In named let, the implicit function's arguments have initial values, but thereafter, each call requires the full set of arguments. Why not treat the initial values as default values?
> (let* func ((i 1) (j 2)) (+ i j (if (> i 0) (func (- i 1)) 0))) 5 > (letrec ((func (lambda* ((i 1) (j 2)) (+ i j (if (> i 0) (func (- i 1)) 0))))) (func)) 5This is consistent with the lambda* arguments because their defaults are already set in left-to-right order, and as each parameter is set to its default value, the binding is added to the default value expression environment (just as if it were a let*). The let* name itself (the implicit function) is not defined until after the bindings have been evaluated (as in named let).
In CL, keyword default values are handled in the same way:
> (defun foo (&key (a 0) (b (+ a 4)) (c (+ a 7))) (list a b c)) FOO > (foo :b 2 :a 60) (60 2 67)In s7, we'd use:
(define* (foo (a 0) (b (+ a 4)) (c (+ a 7))) (list a b c))Also CL and s7 handle keywords as values in the same way:
> (defun foo (&key a) a) FOO > (defvar x :a) X > (foo x 1) 1> (define* (foo a) a) foo > (define x :a) :a > (foo x 1) 1To try to catch what I believe are usually mistakes, I added two error checks. One is triggered if you set the same parameter twice in the same call, and the other if an unknown keyword is encountered in the key position. To turn off these errors, add :allow-other-keys at the end of the parameter list. These problems arise in a case such as
(define* (f (a 1) (b 2)) (list a b))You could do any of the following by accident:
(f 1 :a 2) ; what is a? (f :b 1 2) ; what is b? (f :c 3) ; did you really want a to be :c and b to be 3?In the last case, to pass a keyword deliberately, either include the argument keyword:
(f :a :c), or make the default value a keyword:(define* (f (a :c) ...)), or set(*s7* 'accept-all-keyword-arguments)to some true value. See s7test.scm for many examples.What if two functions share a keyword argument, and one wants to call the other, passing both arguments to the wrapper?
(define* (f1 a) a) ; the wrappee (define* (f2 a :rest b :allow-other-keys) ; the wrapper (+ a (apply f1 b))) (f2 :a 3 :a 4) ; 7, b='(:a 4) (let ((c :a)) (f2 c 3 c 4)) ; also 7Since named let* is a form of lambda*, the prohibition of repeated variable names makes it different from let*:
(let* ((a 1) (a 2)) a)is 2, but(let* loop ((a 1) (a 2)) a)is an error. If let* and named let* agreed in this, we'd have an inconsistency with lambda*. If all three allowed repeated variables, the decision as to which parameter is intended becomes messy:((lambda* (a a) a) 2 :a 3), or(let* loop ((a 1) (a 2)) (loop 2 :a 3)). CL and standard scheme accept repeated variables in let*, so I think the current choice is the least surprising.s7's lambda* arglist handling is not the same as CL's lambda-list. First, you can have more than one :rest parameter:
> ((lambda* (:rest a :rest b) (map + a b)) 1 2 3 4 5) '(3 5 7 9)and second, the rest parameter, if any, takes up an argument slot just like any other argument:
> ((lambda* ((b 3) :rest x (c 1)) (list b c x)) 32) (32 1 ()) > ((lambda* ((b 3) :rest x (c 1)) (list b c x)) 1 2 3 4 5) (1 3 (2 3 4 5))CL would agree with the first case if we used &key for 'c', but would give an error in the second. Of course, the major difference is that s7 keyword arguments don't insist that the key be present. The :rest argument is needed in cases like these because we can't use an expression such as:
> ((lambda* ((a 3) . b c) (list a b c)) 1 2 3 4 5) error: stray dot? > ((lambda* (a . (b 1)) b) 1 2) ; the reader turns the arglist into (a b 1) error: lambda* parameter '1 is a constantYet another nit: the :rest argument is not considered a keyword argument, so
> (define* (f :rest a) a) f > (f :a 1) (:a 1)
define-macro, define-macro*, define-bacro, define-nacro*, macroexpand, gensym, gensym?, and macro? implement the standard old-time macros. The anonymous versions (analogous to lambda and lambda*) are macro, macro*, bacro, and bacro*. See s7test.scm for many examples of macros including such perennial favorites as loop, dotimes, do*, enum, pushnew, and defstruct.
> (define-macro (and-let* vars . body)
`(let ()
(and ,@(map (lambda (v)
`(define ,@v))
vars)
(begin ,@body))))
macroexpand can help debug a macro. I always forget that it wants an expression:
> (define-macro (add-1 arg) `(+ 1 ,arg)) add-1 > (macroexpand (add-1 32)) (+ 1 32)
gensym returns a symbol that is guaranteed to be unused. It takes an optional string argument giving the new symbol name's prefix. gensym? returns #t if its argument is a symbol created by gensym.
(define-macro (pop! sym)
(let ((v (gensym)))
`(let ((,v (car ,sym)))
(set! ,sym (cdr ,sym))
,v)))
As in define*, the starred forms give optional and keyword arguments:
> (define-macro* (add-2 a (b 2)) `(+ ,a ,b)) add-2 > (add-2 1 3) 4 > (add-2 1) 3 > (add-2 :b 3 :a 1) 4
A macro is a first-class citizen of s7. You can pass it as a function argument, apply it to a list, return it from a function, call it recursively, and assign it to a variable. You can even set its setter!
> (define-macro (hi a) `(+ ,a 1)) hi > (apply hi '(4)) 5 > (define (fmac mac) (apply mac '(4))) fmac > (fmac hi) 5 > (define (fmac mac) (mac 4)) fmac > (fmac hi) 5 > (define (make-mac) (define-macro (hi a) `(+ ,a 1))) make-mac > (let ((x (make-mac))) (x 2)) 3 > (define-macro (ref v i) `(vector-ref ,v ,i)) ref > (define-macro (set v i x) `(vector-set! ,v ,i ,x)) set > (set! (setter ref) set) set > (let ((v (vector 1 2 3))) (set! (ref v 0) 32) v) #(32 2 3)To expand all the macros in a piece of code:
(define-macro (fully-macroexpand form) (list 'quote (let expand ((form form)) (cond ((not (pair? form)) form) ((and (symbol? (car form)) (macro? (symbol->value (car form)))) (expand (apply macroexpand (list form)))) ((and (eq? (car form) 'set!) ; look for (set! (mac ...) ...) and use mac's setter (pair? (cdr form)) (pair? (cadr form)) (macro? (symbol->value (caadr form)))) (expand (apply macroexpand (list (cons (setter (symbol->value (caadr form))) (append (cdadr form) (copy (cddr form)))))))) (else (cons (expand (car form)) (expand (cdr form))))))))This does not always handle bacros correctly because their expansion can depend on the run-time state.
A bacro is a macro that expands its body and evaluates the result in the calling environment.
(define setf (let ((args (gensym)) (name (gensym))) (apply define-bacro `((,name . ,args) (unless (null? ,args) (apply set! (car ,args) (cadr ,args) ()) (apply setf (cddr ,args)))))))The setf argument is a gensym (created when setf is defined) so that its name does not shadow any existing variable. Bacros expand in the calling environment, and a normal argument name might shadow something in that environment while the bacro is being expanded. Similarly, if you introduce bindings in the bacro expansion code, you need to keep track of which environment you want things to happen in. Use with-let and gensym liberally. stuff.scm has bacro-shaker which can find inadvertent name collisions, but it is flighty and easily confused. The calling environment itself is (outlet (curlet)) from within a bacro, so
(define-bacro (holler) `(format *stderr* "(~S~{ ~S ~S~^~})~%" (let ((f (*function*))) (if (pair? f) (car f) f)) (map (lambda (slot) (values (symbol->keyword (car slot)) (cdr slot))) (reverse (map values ,(outlet (curlet))))))) (define (f1 a b) (holler) (+ a b)) (f1 2 3) ; prints out "(f1 :a 2 :b 3)" and returns 5Since a bacro (normally) sheds its define-time environment:
(define call-bac (let ((x 2)) (define-bacro (m a) `(+ ,a ,x)))) > (call-bac 1) error: x: unbound variableA macro here returns 3. But don't be hasty! The bacro can get its define-time environment (its closure) via funclet, so in fact, define-macro is a special case of define-bacro! We can define macros that work in all four ways: the expansion can happen in either the definition or calling environment, as can the evaluation of that expansion. In a bacro, both happen in the calling environment if we take no other action, and in a normal macro (define-macro), the expansion happens in the definition environment, and the evaluation in the calling environment. Here's a brief example of all four:
(let ((x 1) (y 2)) (define-bacro (bac1 a) `(+ ,x y ,a)) ; expand and eval in calling env (let ((x 32) (y 64)) (bac1 3))) ; (with-let (inlet 'x 32 'y 64) (+ 32 y 3)) -> 99 ; with-let and inlet refer to environments (let ((x 1) (y 2)) ; this is like define-macro (define-bacro (bac2 a) (with-let (sublet (funclet bac2) :a a) `(+ ,x y ,a))) ; expand in definition env, eval in calling env (let ((x 32) (y 64)) (bac2 3))) ; (with-let (inlet 'x 32 'y 64) (+ 1 y 3)) -> 68 (let ((x 1) (y 2)) (define-bacro (bac3 a) (let ((e (with-let (sublet (funclet bac3) :a a) `(+ ,x y ,a)))) `(with-let ,(sublet (funclet bac3) :a a) ,e))) ; expand and eval in definition env (let ((x 32) (y 64)) (bac3 3))) ; (with-let (inlet 'x 1 'y 2) (+ 1 y 3)) -> 6 (let ((x 1) (y 2)) (define-bacro (bac4 a) (let ((e `(+ ,x y ,a))) `(with-let ,(sublet (funclet bac4) :a a) ,e))) ; expand in calling env, eval in definition env (let ((x 32) (y 64)) (bac4 3))) ; (with-let (inlet 'x 1 'y 2) (+ 32 y 3)) -> 37Backquote (quasiquote) in s7 is almost trivial. Constants are unchanged, symbols are quoted, ",arg" becomes "arg", and ",@arg" becomes "(apply values arg)" — hooray for real multiple values! It's almost as easy to write the actual macro body as the backquoted version of it.
> (define-macro (hi a) `(+ 1 ,a)) hi > (procedure-source hi) (lambda (a) (list-values '+ 1 a)) > (define-macro (hi a) `(+ 1 ,@a)) hi > (procedure-source hi) (lambda (a) (list-values '+ 1 (apply-values a)))list-values and apply-values are quasiquote helper functions described below. There is no unquote-splicing macro in s7; ",@(...)" becomes "(unquote (apply-values ...))" at read-time. There shouldn't be any unquote either. In Scheme the reader turns ,x into (unquote x), so:
> (let (,'a) unquote) a > (let (, (lambda (x) (+ x 1))) ,,,,'3) 7comma becomes a sort of symbol macro! I think I'll remove unquote; ,x and ,@x will still work as expected, but there will not be any "unquote" or "unquote-splicing" in the resultant source code. Just to make life difficult:
> (let (' 1) quote) 1but that translation is so ingrained in lisp that I'm reluctant to change it. The two unquote names, on the other hand, seem unnecessary.
s7 macros are not hygienic. For example,
> (define-macro (mac b)
`(let ((a 12))
(+ a ,b)))
mac
> (let ((a 1) (+ *)) (mac a))
144
This returns 144 because '+' has turned into '*', and 'a' is the internal 'a',
not the argument 'a'. We get (* 12 12) where we might have expected
(+ 12 1).
Starting with the '+' problem,
as long as the redefinition of '+' is local (that is, it happens after the macro definition), we can unquote the +:
> (define-macro (mac b)
`(let ((a 12))
(,+ a ,b))) ; ,+ picks up the definition-time +
mac
> (let ((a 1) (+ *)) (mac a))
24 ; (+ a a) where a is 12
But the unquote trick won't work if we have previously loaded some file that redefined '+' at the top-level (so at macro definition time, + is *, but we want the built-in +). Although this example is silly, the problem is real in Scheme because Scheme has no reserved words and only one name space.
> (define + *) + > (define (add a b) (+ a b)) add > (add 2 3) 6 > (define (divide a b) (/ a b)) divide > (divide 2 3) 2/3 > (set! / -) ; a bad idea — this turns off s7's optimizer - > (divide 2 3) -1
Obviously macros are not the problem here. Since we might be loading code written by others, it's sometimes hard to tell what names that code depends on or redefines. We need a way to get the pristine (start-up, built-in) value of '+'. One long-winded way in s7 uses unlet:
> (define + *) + > (define (add a b) (with-let (unlet) (+ a b))) add > (add 2 3) 5
But this is hard to read, and we might want all three
values of a symbol, the start-up value, the definition-time value, and the
current value. The latter can be accessed with the bare symbol, the definition-time
value with unquote (','), and the start-up value with either unlet
or #_<name>. That is, #_+ is a reader macro for (with-let (unlet) +).
> (define-macro (mac b)
`(#_let ((a 12))
(#_+ a ,b))) ; #_+ and #_let are start-up values
mac
> (let ((a 1) (+ *)) (mac a))
24 ; (+ a a) where a is 12 and + is the start-up +
;;; make + generic (there's a similar C-based example below)
> (define (+ . args)
(if (null? args) 0
(apply (if (number? (car args)) #_+ #_string-append) args)))
+
> (+ 1 2)
3
> (+ "hi" "ho")
"hiho"
Conceptually, #_<name> could be implemented via *#readers*:
(set! *#readers* (cons (cons #\_ (lambda (str) (with-let (unlet) (string->symbol (substring str 1))))) *#readers*))but s7 doesn't let you change the meaning of #\_; otherwise:
(set! *#readers* (list (cons #\_ (lambda (str) (string->symbol (substring str 1))))))and now #_ provides no protection:
> (let ((+ -)) (#_+ 1 2)) -1#t and #f (along with their stupid r7rs cousins #true and #false) are also not settable.
So, now we have only the variable capture problem ('a' has been captured in the preceding examples). This is the only thing that the gigantic "hygienic macro" systems actually deal with: a microscopic problem that you'd think, from the hype, was up there with malaria and the national debt. gensym is the standard approach:
> (define-macro (mac b)
(let ((var (gensym)))
`(#_let ((,var 12))
(#_+ ,var ,b))))
mac
> (let ((a 1) (+ *)) (mac a))
13
;; or use lambda:
> (define-macro (mac b)
`((lambda (b) (let ((a 12)) (#_+ a b))) ,b))
mac
> (let ((a 1) (+ *)) (mac a))
13
I think syntax-rules and its friends try to conjure up gensyms automatically, but the real problem is not name collisions, but unspecified environments. In s7 we have first-class environments, so you have complete control over the environment at any point:
(define-macro (mac b)
`(with-let (inlet 'b ,b)
(let ((a 12))
(+ a b))))
> (let ((a 1) (+ *)) (mac a))
13
(define-macro (mac1 . b) ; originally `(let ((a 12)) (+ a ,@b ,@b))
`(with-let (inlet 'e (curlet)) ; this 'e will not collide with the calling env
(let ((a 12)) ; nor will 'a (so no gensyms are needed etc)
(+ a (with-let e ,@b) (with-let e ,@b)))))
> (let ((a 1) (e 2)) (mac1 (display a) (+ a e)))
18 ; (and it displays "11")
(define-macro (mac2 x) ; this will use mac2's definition environment for its body
`(with-let (sublet (funclet mac2) :x ,x)
(let ((a 12))
(+ a b x)))) ; a is always 12, b is whatever b happens to be in mac2's env
> (define b 10) ; this is mac2's b
10
> (let ((+ *) (a 1) (b 15)) (mac2 (+ a b)))
37 ; mac2 uses its own a (12), b (10), and + (+)
; but (+ a b) is 15 because at that point + is *: (* 1 15)
Hygienic macros are trivial! Who needs syntax-rules? To avoid the variable capture, avoid local variables in the generated code, or protect them via with-let; to avoid shadowing of functions and syntax, make the environment explicit (via #_ for example). s7's lint.scm will warn you about a problematic macro expansion, so I'd say just write macros as simply as possible, then let lint tell you that it's time to do the with-let shuffle. When that happens, wrap the macro body in a with-let that captures the current environment, and at each use of a macro argument wrap it in a with-let that re-establishes that environment.
(define-macro (swap a b) ; assume a and b are symbols `(with-let (inlet 'e (curlet) 'tmp ,a) (set! (e ',a) (e ',b)) (set! (e ',b) tmp))) > (let ((b 1) (tmp 2)) (swap b tmp) (list b tmp)) (2 1) (define-macro (swap a b) ; here a and b can be any settable expressions `(set! ,b (with-let (inlet 'e (curlet) 'tmp ,a) (with-let e (set! ,a ,b)) tmp))) > (let ((v (vector 1 2))) (swap (v 0) (v 1)) v) #(2 1) > (let ((tmp (cons 1 2))) (swap (car tmp) (cdr tmp)) tmp) (2 . 1) (set! (setter swap) (define-macro (set-swap a b c) `(set! ,b ,c))) > (let ((a 1) (b 2) (c 3) (d 4)) (swap a (swap b (swap c d))) (list a b c d)) (2 3 4 1) ;;; but this is simpler: (define-macro (rotate! . args) `(set! ,(args (- (length args) 1)) (with-let (inlet 'e (curlet) 'tmp ,(car args)) (with-let e ,@(map (lambda (a b) `(set! ,a ,b)) args (cdr args))) tmp))) > (let ((a 1) (b 2) (c 3)) (rotate! a b c) (list a b c)) (2 3 1)
If you want the macro's expanded result to be evaluated in its definition environment:
(let ((a 3))
(define-macro (mac b)
`(with-let (inlet 'b ,b (funclet mac))
(+ a b))) ; definition-time "a", call-time "b"
(define-macro (mac-1 b)
`(+ a ,b)) ; call-time "a" and "b"
(let ((a 32))
(list (mac 1)
(mac-1 1))))
Here are some variations on "unless", inspired by the wikipedia hygienic macro page:
(define-macro (my-unless condition . body) `(with-let (inlet (unlet) :condition ,condition) ; here unlet protects body (format below) (if (not condition) (begin ,@body)))) (let ((not (lambda (x) x)) (begin 32) (if +) (format abs)) (my-unless #t (format #t "This should not be printed!\n")) (my-unless #f (format #t "This should be printed!\n"))) (set! format abs) (let ((not (lambda (x) x))) (my-unless #t (format #t "This should not be printed!\n")) (my-unless #f (format #t "This should be printed!\n"))) (define (user-defined-operator x) (not x)) (define-macro (my-unless-1 condition . body) `(with-let (inlet (unlet) :condition ,condition) (if (user-defined-operator condition) (begin ,@body)))) (let ((user-defined-operator (lambda (x) x))) (my-unless-1 #t (format #t "This should not be printed!\n")) (my-unless-1 #f (format #t "This should be printed!\n"))) (define my-unless-2 (let ((op1 (lambda (x) (not x)))) (define-macro (_ condition . body) `(with-let (inlet (unlet) (funclet my-unless-2) :condition ,condition) ;; funclet above to get my-unless-2's version of op1 (if (op1 condition) (begin ,@body)))))) (let ((op1 (lambda (x) x))) (my-unless-2 #t (format #t "This should not be printed!\n")) (my-unless-2 #f (format #t "This should be printed!\n"))) (define my-unless-3 (let ((op1 (lambda (x) x))) (define-macro (_ condition . body) `(with-let (inlet (unlet) :condition ,condition :local-env (curlet)) ;; curlet to get run-time local version of op1 (if ((with-let local-env op1) condition) (begin ,@body)))))) (let ((op1 (lambda (x) (not x)))) (my-unless-3 #t (format #t "This should not be printed!\n")) (my-unless-3 #f (format #t "This should be printed!\n")))
On the subject of *#readers*, say we have:
(set! *#readers* (list (cons #\o (lambda (str) 42)) ; #o... -> 42 (cons #\x (lambda (str) 3)))) ; #x... -> 3Now we load a file with:
(define (oct) #o123) (let-temporarily ((*#readers* ())) (eval (with-input-from-string "(define (hex) #x123)" read))) (define-constant old-readers *#readers*) (set! *#readers* ()) (define (oct1) #o123) (define (hex1) #x123) (set! *#readers* old-readers) (define (oct2) #o123) (define (hex2) #x123)Now we evaluate these functions, and get:
(oct): 42 ; oct is not read-time hygienic so #o123 -> 42 (oct1): 83 ; oct1 is protected by the top-level set, #o123 -> 83 (oct2): 42 ; same as oct (hex): 291 ; hex is protected by let-temporarily + read (hex1): 291 ; hex1 is like oct1 (hex2): 3 ; hex2 is like oct
Here is Peter Seibel's wonderful once-only macro:
(define-macro (once-only names . body) (let ((gensyms (map (lambda (n) (gensym)) names))) `(let (,@(map (lambda (g) (list g '(gensym))) gensyms)) `(let (,,@(map (lambda (g n) (list list g n)) gensyms names)) ,(let (,@(map list names gensyms)) ,@body)))))From the land of sparkling bacros:
(define once-only (let ((names (gensym)) (body (gensym))) (apply define-bacro `((,(gensym) ,names . ,body) `(let (,@(map (lambda (name) `(,name ,(eval name))) ,names)) ,@,body)))))Sadly, with-let is simpler.
(setter proc) (dilambda proc setter)
There are several kinds of setters, reflecting the many ways that set! can be called. First are the symbol setters:
> (let ((x 1))
(set! (setter 'x) (lambda (name new-value) (* new-value 2)))
(set! x 2)
x)
4
Here the setter is a function that is called before the variable is set.
It can take two or three arguments. In the two argument case shown above,
the first is the variable name (a symbol), and the second is the new-value.
The variable is set to the value returned by the setter function.
When s7 sees (set! x 2) above, it calls the setter which returns 4.
So x is set to 4.
In some cases you need the environment that the variable lives in (to get its current value for example), so you can include that in the setter function parameter list:
> (let ((x 1))
(set! (setter 'x) (lambda (name new-value enviroment) (* new-value 2)))
(set! x 2)
x)
4
(define-macro (watch var) ; notification if 'var is set!
`(set! (setter ',var)
(lambda (s v e)
(format *stderr* "~S set! to ~S~A~%" s v
(let ((func (with-let e (*function*))))
(if (eq? func #<undefined>) "" (format #f ", ~S" func))))
v)))
Since symbol setters are often implementing type restrictions, you can use the built-in type checking functions such as integer? as a short-hand for a setter that insists the new value be an integer:
> (let ((x 1))
(set! (setter 'x) integer?)
(set! x 3.14))
error: set! x: 3.14, is a real but should be an integer
;;; use typed-let from stuff.scm to do the same thing:
> (typed-let ((x 3 integer?))
(set! x 3.14))
error: set! x: 3.14, is a real but should be an integer
C-side symbol setters go through s7_set_setter. There is an example below.
The second case is a function setter. Almost any function or macro can have an associated setter that is invoked when the function is the target of set!. In this case, the setter function does the set! itself (unlike a symbol setter):
> (setter cadr)
#f ; by default cadr has no setter so (set! (cadr p) x) is an error
> (set! (setter cadr) ; add a setter to cadr
(lambda (lst val)
(set! (car (cdr lst)) val)))
#<lambda (lst val)>
> (procedure-source (setter cadr))
(lambda (lst val) (set! (car (cdr lst)) val))
> (let ((lst (list 1 2 3)))
(set! (cadr lst) 4)
lst)
(1 4 3)
In some cases, the setter needs to be a macro:
> (set! (setter logbit?)
(define-macro (m var index on) ; here we want to set "var", so we need a macro
`(if ,on
(set! ,var (logior ,var (ash 1 ,index)))
(set! ,var (logand ,var (lognot (ash 1 ,index)))))))
m
> (define (mingle a b)
(let ((r 0))
(do ((i 0 (+ i 1)))
((= i 31) r)
(set! (logbit? r (* 2 i)) (logbit? a i))
(set! (logbit? r (+ (* 2 i) 1)) (logbit? b i)))))
mingle
> (mingle 6 3) ; the INTERCAL mingle operator?
30
dilambda defines a function (or macro) and its setter without having to set! the setter by hand:
> (define f (let ((x 123))
(dilambda (lambda ()
x)
(lambda (new-value)
(set! x new-value)))))
f
> (f)
123 ; x = 123
> (set! (f) 32)
32 ; now x = 32
> (f)
32
Here is a pretty example of dilambda:
(define-macro (c?r path)
;; "path" is a list and "X" marks the spot in it that we are trying to access
;; (a (b ((c X)))) — anything after the X is ignored, other symbols are just placeholders
;; c?r returns a dilambda that gets/sets X
(define (X-marks-the-spot accessor tree)
(if (eq? tree 'X)
accessor
(and (pair? tree)
(or (X-marks-the-spot (cons 'car accessor) (car tree))
(X-marks-the-spot (cons 'cdr accessor) (cdr tree))))))
(let ((body 'lst))
(for-each
(lambda (f)
(set! body (list f body)))
(reverse (X-marks-the-spot () path)))
`(dilambda
(lambda (lst)
,body)
(lambda (lst val)
(set! ,body val)))))
> ((c?r (a b (X))) '(1 2 (3 4) 5))
3
> (let ((lst (list 1 2 (list 3 4) 5)))
(set! ((c?r (a b (X))) lst) 32)
lst)
(1 2 (32 4) 5)
> (procedure-source (c?r (a b (X))))
(lambda (lst) (car (car (cdr (cdr lst)))))
> ((c?r (a b . X)) '(1 2 (3 4) 5))
((3 4) 5)
> (let ((lst (list 1 2 (list 3 4) 5)))
(set! ((c?r (a b . X)) lst) '(32))
lst)
(1 2 32)
> (procedure-source (c?r (a b . X)))
(lambda (lst) (cdr (cdr lst)))
> ((c?r (((((a (b (c (d (e X)))))))))) '(((((1 (2 (3 (4 (5 6))))))))))
6
> (let ((lst '(((((1 (2 (3 (4 (5 6)))))))))))
(set! ((c?r (((((a (b (c (d (e X)))))))))) lst) 32)
lst)
(((((1 (2 (3 (4 (5 32)))))))))
> (procedure-source (c?r (((((a (b (c (d (e X)))))))))))
(lambda (lst) (car (cdr (car (cdr (car (cdr (car (cdr (car (cdr (car (car (car (car lst)))))))))))))))
I may remove dilambda and dilambda? someday; they are trivial:
(define (dilambda get set) (set! (setter get) set) get) (define dilambda? setter)
When a function setter is called, (set! (func ...) val) is
evaluated by s7 as ((setter func) ... val), so the setter function
needs to handle both the inner arguments to the function and the new value.
(let ((x 123)) (define (f a b) (+ x a b)) (set! (setter f) (lambda (a b val) (set! x val))) (display (f 1 2)) (newline) ; "126" (set! (f 1 2) 32) (display (f 1 2)) (newline)) ; "35"
A third type of setter handles vector element type and hash-table key and value types. These are described under typed vectors and typed hash-tables.
Speaking of INTERCAL, COME-FROM:
(define-macro (define-with-goto-and-come-from name-and-args . body) (let ((labels ()) (gotos ()) (come-froms ())) (let collect-jumps ((tree body)) (when (pair? tree) (when (pair? (car tree)) (case (caar tree) ((label) (set! labels (cons tree labels))) ((goto) (set! gotos (cons tree gotos))) ((come-from) (set! come-froms (cons tree come-froms))) (else (collect-jumps (car tree))))) (collect-jumps (cdr tree)))) (for-each (lambda (goto) (let* ((name (cadr (cadar goto))) (label (member name labels (lambda (a b) (eq? a (cadr (cadar b))))))) (if label (set-cdr! goto (car label)) (error 'bad-goto "can't find label: ~S" name)))) gotos) (for-each (lambda (from) (let* ((name (cadr (cadar from))) (label (member name labels (lambda (a b) (eq? a (cadr (cadar b))))))) (if label (set-cdr! (car label) from) (error 'bad-come-from "can't find label: ~S" name)))) come-froms) `(define ,name-and-args (let ((label (lambda (name) #f)) (goto (lambda (name) #f)) (come-from (lambda (name) #f))) ,@body))))
A procedure with a setter can be viewed as one generalization of set!. Another treats objects as having predefined get and set functions. In s7 lists, strings, vectors, hash-tables, environments, and any cooperating C or Scheme-defined objects are both applicable and settable. newLisp calls this implicit indexing, Kawa has it, Gauche implements it via object-apply, Guile via procedure-with-setter; CL's funcallable instance might be the same idea.
In (vector-ref #(1 2) 0), for example, vector-ref is just a type
declaration. But in Scheme, type declarations are unnecessary, so we get exactly
the same result from (#(1 2) 0). Similarly, (lst 1) is the
same as (list-ref lst 1), and (set! (lst 1) 2) is the same
as (list-set! lst 1 2).
I like this syntax: the less noise, the better!
Well, maybe applicable strings look weird:
("hi" 1)is #\i, but worse, so is(cond (1 => "hi"))! Even though a string, list, or vector is "applicable", it is not currently considered to be a procedure, so(procedure? "hi")is #f. map and for-each, however, accept anything that apply can handle, so(map #(0 1) '(1 0))is '(1 0). (On the first call to map in this case, you get the result of(#(0 1) 1)and so on). string->list, vector->list, and let->list are(map values object). Their inverses are (and always have been) equally trivial.The applicable object syntax makes it easy to write generic functions. For example, s7test.scm has implementations of Common Lisp's sequence functions. length, copy, reverse, fill!, iterate, map and for-each are generic in this sense (map always returns a list).
> (map (lambda (a b) (- a b)) (list 1 2) (vector 3 4)) (5 -3 9) > (length "hi") 2Here's a generic FFT:
(define* (cfft data n (dir 1)) ; complex data (unless n (set! n (length data))) (do ((i 0 (+ i 1)) (j 0)) ((= i n)) (if (> j i) (let ((temp (data j))) (set! (data j) (data i)) (set! (data i) temp))) (do ((m (/ n 2) (/ m 2))) ((not (<= 2 m j)) (set! j (+ j m))) (set! j (- j m)))) (do ((ipow (floor (log n 2))) (prev 1) (lg 0 (+ lg 1)) (mmax 2 (* mmax 2)) (pow (/ n 2) (/ pow 2)) (theta (complex 0.0 (* pi dir)) (* theta 0.5))) ((= lg ipow)) (do ((wpc (exp theta)) (wc 1.0) (ii 0 (+ ii 1))) ((= ii prev) (set! prev mmax)) (do ((jj 0 (+ jj 1)) (i ii (+ i mmax)) (j (+ ii prev) (+ j mmax))) ((>= jj pow) (set! wc (* wc wpc))) (let ((tc (* wc (data j)))) (set! (data j) (- (data i) tc)) (set! (data i) (+ (data i) tc)))))) data) > (cfft (list 0.0 1+i 0.0 0.0)) (1+1i -1+1i -1-1i 1-1i) > (cfft (vector 0.0 1+i 0.0 0.0)) #(1+1i -1+1i -1-1i 1-1i)And a generic function that copies one sequence's elements into another sequence:
(define (copy-into source dest) ; this is equivalent to (copy source dest) (do ((i 0 (+ i 1))) ((= i (min (length source) (length dest))) dest) (set! (dest i) (source i))))but that is already built-in as the two-argument version of the copy function.
There is one place where list-set! and friends are not the same as set!: the former evaluate their first argument, but set! does not (with a quibble; see below):
> (let ((str "hi")) (string-set! (let () str) 1 #\a) str) "ha" > (let ((str "hi")) (set! (let () str) 1 #\a) str) ;((let () str) 1 #\a): too many arguments to set! > (let ((str "hi")) (set! ((let () str) 1) #\a) str) "ha" > (let ((str "hi")) (set! (str 1) #\a) str) "ha"set! looks at its first argument to decide what to set. If it's a symbol, no problem. If it's a pair, set! looks at its car to see if it is some object that has a setter. If the car is itself a list, set! evaluates the internal expression, and tries again. So the second case above is the only one that won't work. And of course:
> (let ((x (list 1 2))) (set! ((((lambda () (list x))) 0) 0) 3) x) (3 2)By my count, around 20 of the Scheme built-in functions are already generic in the sense that they accept arguments of many types (leaving aside the numeric and type checking functions, take for example equal?, display, member, assoc, apply, eval, quasiquote, and values). s7 extends that list with map, for-each, reverse, and length, and adds a few others such as copy, fill!, sort!, object->string, object->let, and append. newLisp takes a more radical approach than s7: it extends operators such as '>' to compare strings and lists, as well as numbers. In map and for-each, however, you can mix the argument types, so I'm not as attracted to making '>' generic; you can't, for example,
(> "hi" 32.1), or even(> 1 0+i).
The somewhat non-standard generic sequence functions in s7 are:
(sort! sequence less?) (reverse! sequence) and (reverse sequence) (fill! sequence value (start 0) end) (copy obj) and (copy source destination (start 0) end) (object->string obj) (object->let obj) (length obj) (append . sequences) (map func . sequences) and (for-each func . sequences) (equivalent? obj1 obj2)
copy returns a (shallow) copy of its argument. If a destination is provided, it need not match the source in size or type. The start and end indices refer to the source.
> (copy '(1 2 3 4) (make-list 2)) (1 2) > (copy #(1 2 3 4) (make-list 5) 1) ; start at 1 in the source (2 3 4 #f #f) > (copy "1234" (make-vector 2)) #(#\1 #\2) > (define lst (list 1 2 3 4 5)) (1 2 3 4 5) > (copy #(8 9) (cddr lst)) (8 9 5) > lst (1 2 8 9 5)
reverse! is an in-place version of reverse. That is,
it modifies the sequence passed to it in the process of reversing its contents.
If the sequence is a list, remember to use set!:
(set! p (reverse! p)). This is somewhat inconsistent with other cases,
but historically, lisp programmers have treated the in-place reverse as the fast
version, so s7 follows suit.
> (define lst (list 1 2 3)) (1 2 3) > (reverse! lst) (3 2 1) > lst (1)
Leaving aside the weird list case, append returns a sequence of the same type as its first argument.
> (append #(1 2) '(3 4)) #(1 2 3 4) > (append (float-vector) '(1 2) (byte-vector 3 4)) (float-vector 1.0 2.0 3.0 4.0)
sort! sorts a sequence using the function passed as its second argument:
> (sort! (list 3 4 8 2 0 1 5 9 7 6) <) (0 1 2 3 4 5 6 7 8 9)
Underlying some of these functions are generic iterators, also built-into s7:
(make-iterator sequence) (iterator? obj) (iterate iterator) (iterator-sequence iterator) (iterator-at-end? iterator)
make-iterator takes a sequence argument and returns an iterator object that traverses
that sequence as it is called. The iterator itself can be treated as a function of no arguments,
or (for code clarity) it can be the argument to iterate, which does the same thing.
That is (iter) is the same as (iterate iter). The sequence that an iterator is traversing
is iterator-sequence.
If the sequence is a hash-table or let, the iterator normally returns a cons of the key and value. There are many cases where this overhead is objectionable, so make-iterator takes a third optional argument, the cons to use (changing its car and cdr directly on each call).
When an iterator reaches the end of its sequence, it returns #<eof>. It used to return nil; I can't decide whether this change is an improvement. If an iterator over a list notices that its list is circular, it returns #<eof>. map and for-each use iterators, so if you pass a circular list to either, it will stop eventually. (An arcane consequence for method writers: specialize make-iterator, not map or for-each).
(define (find-if f sequence)
(let ((iter (make-iterator sequence)))
(do ((x (iter) (iter)))
((or (eof-object? x) (f x))
(and (not (eof-object? x)) x)))))
But of course a sequence might contain #<eof>! So to be really safe, use iterator-at-end? instead of eof-object?.
The argument to make-iterator can also be a function or macro. There should be a variable named '+iterator+ with a non-#f value in the closure's environment:
(define (make-circular-iterator obj)
(let ((iter (make-iterator obj)))
(make-iterator
(let ((+iterator+ #t))
(lambda ()
(case (iter)
((#<eof>) ((set! iter (make-iterator obj))))
(else)))))))
The 'iterator? variable is similar to the '+documentation+ variable used by documentation. It gives make-iterator some hope of catching inadvertent bogus function arguments that would otherwise cause an infinite loop.
s7 supports vectors with any number of dimensions. It is here, in particular, that generalized set! shines. make-vector's second argument can be a list of dimensions, rather than an integer as in the one dimensional case:
(make-vector (list 2 3 4)) (make-vector '(2 3) 1.0) (vector-dimensions (make-vector '(2 3 4))) -> (2 3 4)
The second example includes the optional initial element.
(vect i ...) or (vector-ref vect i ...) return the given
element, and (set! (vect i ...) value) and (vector-set! vect i ... value)
set it. vector-length (or just length) returns the total number of elements.
vector-dimensions returns a list of the dimensions; vector-rank returns the length of this list,
and vector-dimension returns the nth member of the list (the size of the nth dimension).
> (define v (make-vector '(2 3) 1.0)) #2d((1.0 1.0 1.0) (1.0 1.0 1.0)) > (set! (v 0 1) 2.0) #2d((1.0 2.0 1.0) (1.0 1.0 1.0)) > (v 0 1) 2.0 > (vector-length v) 6
This function initializes each element of a multidimensional vector:
(define (make-array dims . inits) (subvector (apply vector (flatten inits)) 0 (apply * dims) dims)) > (make-array '(3 3) '(1 1 1) '(2 2 2) '(3 3 3)) #2d((1 1 1) (2 2 2) (3 3 3))
make-int-vector, make-float-vector, and make-byte-vector produce homogeneous vectors holding s7_ints, s7_doubles, or unsigned bytes.
(make-vector length-or-list-of-dimensions initial-value element-type-function) (vector-dimensions vect) (vector-dimension vect n) (vector-rank obj) (float-vector? obj) (float-vector . args) (make-float-vector len (init 0.0)) (float-vector-ref obj . indices) (float-vector-set! obj indices[...] value) (int-vector? obj) (int-vector . args) (make-int-vector len (init 0)) (int-vector-ref obj . indices) (int-vector-set! obj indices[...] value) (byte-vector? obj) (byte-vector . args) (make-byte-vector len (init 0)) (byte-vector-ref obj . indices) (byte-vector-set! obj indices[...] byte) (byte? obj) (string->byte-vector str) (byte-vector->string str) (subvector vector start end dimensions) (subvector? obj) (subvector-vector obj) (subvector-position obj)
In addition to the dimension list mentioned above, make-vector accepts optional arguments giving the initial element and the element type. If the type is given, every attempt to set an element of the vector first calls the type function on the new value. If the type function is omitted (or set to #t), no type checking is performed. If the type function is a closure (rather than a C-defined or built-in function), its name must be accessible; it can't be an anonymous lambda (the signature and error handlers need this name).
> (define v (make-vector 3 'x symbol?)) ; initial element: 'x, elements must be symbols #(x x x) > (vector-set! v 0 123) error: vector-set! argument 3, 123, is an integer but should be a symbol? > (define (10|12? val) (memv val '(10 12))) 10|12? > (define v1 (make-vector 3 10 10|12?)) ; only allow values 10 or 12 (initially 10) #(10 10 10) > (set! (v1 0) 12) 12 > v1 #(12 10 10) > (set! (v1 1) 32) error: vector-set! argument 3, 32, is an integer but should be a 10|12?
To access a vector's elements with different dimensions than the original had, use
(subvector original-vector 0 (length original-vector) new-dimensions):
> (let ((v1 #2d((1 2 3) (4 5 6))))
(let ((v2 (subvector v1))) ; flatten the original (1D is the default)
v2))
#(1 2 3 4 5 6)
> (let ((v1 #(1 2 3 4 5 6)))
(let ((v2 (subvector v1 0 6 '(3 2))))
v2))
#2d((1 2) (3 4) (5 6))
A subvector is a window onto some other vector's data. The data is not copied, just accessed differently. The new-dimensions parameter is a list giving the lengths of the dimensions. The start and end parameters refer to positions in the original vector. subvector-vector returns the underlying vector, and subvector-position returns the starting point of the subvector in the underlying data.
subvector's parameter list changed 8-Jul-2020. It was (subvector vect new-length-or-dimension-list start),
but that conflicts with substring, and is confusing (the start position follows the length). To translate from
the old subvector to the new:
(define* (old-subvector vect len (offset 0))
(if (pair? len)
(subvector vect offset (+ offset (apply * len)) len)
(if (not len)
(subvector vect offset (length vect))
(subvector vect offset (+ offset len)))))
matrix multiplication:
(define (matrix-multiply A B) ;; assume square matrices and so on for simplicity (let ((size (car (vector-dimensions A)))) (do ((C (make-vector (list size size) 0)) (i 0 (+ i 1))) ((= i size) C) (do ((j 0 (+ j 1))) ((= j size)) (do ((sum 0) (k 0 (+ k 1))) ((= k size) (set! (C i j) sum)) (set! sum (+ sum (* (A i k) (B k j)))))))))Conway's game of Life:
(define* (life (width 40) (height 40)) (let ((state0 (make-vector (list width height) 0)) (state1 (make-vector (list width height) 0))) ;; initialize with some random pattern (do ((x 0 (+ x 1))) ((= x width)) (do ((y 0 (+ y 1))) ((= y height)) (set! (state0 x y) (if (< (random 100) 15) 1 0)))) (do () () ;; show current state (using terminal escape sequences, borrowed from the Rosetta C code) (format *stderr* "~C[H" #\escape) ; ESC H = tab set (do ((y 0 (+ y 1))) ((= y height)) (do ((x 0 (+ x 1))) ((= x width)) (format *stderr* (if (zero? (state0 x y)) " " ; ESC 07m below = inverse (values "~C[07m ~C[m" #\escape #\escape)))) (format *stderr* "~C[E" #\escape)) ; ESC E = next line ;; get the next state (do ((x 1 (+ x 1))) ((= x (- width 1))) (do ((y 1 (+ y 1))) ((= y (- height 1))) (let ((n (+ (state0 (- x 1) (- y 1)) (state0 x (- y 1)) (state0 (+ x 1) (- y 1)) (state0 (- x 1) y) (state0 (+ x 1) y) (state0 (- x 1) (+ y 1)) (state0 x (+ y 1)) (state0 (+ x 1) (+ y 1))))) (set! (state1 x y) (if (or (= n 3) (and (= n 2) (not (zero? (state0 x y))))) 1 0))))) (copy state1 state0))))Multidimensional vector constant syntax is modelled after CL: #nd(...) signals that the lists specify the elements of an 'n' dimensional vector:
#2d((1 2 3) (4 5 6))int-vector constants use #i, float-vectors use #r. I wanted to use #f, but that is already taken. Append the "nd" business after the type indication:#i2d((1 2) (3 4)). This syntax collides with the r7rs byte-vector notation "#u8"; s7 uses "#u" for byte-vectors. "#u2d(...)" is a two-dimensional byte-vector. For backwards compatibility, you can use "#u8" for one-dimensional byte-vectors.> (vector-ref #2d((1 2 3) (4 5 6)) 1 2) 6 > (matrix-multiply #2d((-1 0) (0 -1)) #2d((2 0) (-2 2))) #2d((-2 0) (2 -2)) > (int-vector 1 2 3) #i(1 2 3) > (make-float-vector '(2 3) 1.0) #r2d((1.0 1.0 1.0) (1.0 1.0 1.0)) > (vector (vector 1 2) (int-vector 1 2) (float-vector 1 2)) #(#(1 2) #i(1 2) #r(1.0 2.0))If any dimension has 0 length, you get an n-dimensional empty vector. It is not equal to a 1-dimensional empty vector.
> (make-vector '(10 0 3)) #3d() > (equal? #() #3d()) #fTo save on costly parentheses, and make it easier to write generic multidimensional sequence functions, you can use this same syntax with lists.
> (let ((L '((1 2 3) (4 5 6)))) (L 1 0)) ; same as (list-ref (list-ref L 1) 0) or ((L 1) 0) 4 > (let ((L '(((1 2 3) (4 5 6)) ((7 8 9) (10 11 12))))) (set! (L 1 0 2) 32) ; same as (list-set! (list-ref (list-ref L 1) 0) 2 32) which is unreadable! L) (((1 2 3) (4 5 6)) ((7 8 32) (10 11 12)))Or with vectors of vectors, of course:
> (let ((V #(#(1 2 3) #(4 5 6)))) (V 1 2)) ; same as (vector-ref (vector-ref V 1) 2) or ((V 1) 2) 6 > (let ((V #2d((1 2 3) (4 5 6)))) (V 0)) #(1 2 3)There's one difference between a vector-of-vectors and a multidimensional vector: in the latter case, you can't clobber one of the inner vectors.
> (let ((V #(#(1 2 3) #(4 5 6)))) (set! (V 1) 32) V) #(#(1 2 3) 32) > (let ((V #2d((1 2 3) (4 5 6)))) (set! (V 1) 32) V) ;not enough arguments for vector-set!: (#2d((1 2 3) (4 5 6)) 1 32)Using lists to display the inner vectors may not be optimal, especially when the elements are also lists:
#2d(((0) (0) ((0))) ((0) 0 ((0))))The "#()" notation is no better (the elements can be vectors), and I'm not a fan of "[]" parentheses. Perhaps we could use different colors? Or different size parentheses?
#2D(((0) (0) ((0))) ((0) 0 ((0)))) #2D(((0) (0) ((0))) ((0) 0 ((0))))I'm not sure how to handle vector->list and list->vector in the multidimensional case. Currently, vector->list flattens the vector, and list->vector always returns a one dimensional vector, so the two are not inverses.
> (vector->list #2d((1 2) (3 4))) (1 2 3 4) ; should this be '((1 2) (3 4)) or '(#(1 2) #(3 4))? > (list->vector '(#(1 2) #(3 4))) ; what about '((1 2) (3 4))? #(#(1 2) #(3 4))This also affects format and sort!:
> (format #f "~{~A~^ ~}" #2d((1 2) (3 4))) "1 2 3 4" > (sort! #2d((1 4) (3 2)) >) #2d((4 3) (2 1))Perhaps subvector can help:
>(subvector (list->vector '(1 2 3 4)) 0 4 '(2 2)) #2d((1 2) (3 4)) > (let ((a #2d((1 2) (3 4))) (b #2d((5 6) (7 8)))) (list (subvector (append a b) 0 8 '(2 4)) (subvector (append a b) 0 8 '(4 2)) (subvector (append (a 0) (b 0) (a 1) (b 1)) 0 8 '(2 4)) (subvector (append (a 0) (b 0) (a 1) (b 1)) 0 8 '(4 2)))) (#2d((1 2 3 4) (5 6 7 8)) #2d((1 2) (3 4) (5 6) (7 8)) #2d((1 2 5 6) (3 4 7 8)) #2d((1 2) (5 6) (3 4) (7 8)))Another question: should we accept the multi-index syntax in a case such as
(#("abc" "def") 0 2)? My first thought was that the indices should all refer to the same type of object, so s7 would complain in a mixed case like that. If we can nest any applicable objects and apply the whole thing to an arbitrary list of indices, ambiguities arise:((lambda (x) x) "hi" 0) ((lambda (x) (lambda (y) (+ x y))) 1 2)I think these should complain that the function got too many arguments, but from the implicit indexing point of view, they could be interpreted as:
(string-ref ((lambda (x) x) "hi") 0) ; i.e. (((lambda (x) x) "hi") 0) (((lambda (x) (lambda (y) (+ x y))) 1) 2)Add optional and rest arguments, and you can't tell who is supposed to take which arguments. Currently, you can mix types with implicit indices, but a function grabs all remaining indices. To insist that all objects are of the same type, use an explicit getter:
> (list-ref (list 1 (list 2 3)) 1 0) ; same as ((list 1 (list 2 3)) 1 0) 2 > ((list 1 (vector 2 3)) 1 0) 2 > (list-ref (list 1 (vector 2 3)) 1 0) error: list-ref argument 1, #(2 3), is a vector but should be a proper list
Each hash-table keeps track of the keys it contains, optimizing the search wherever possible.
Any s7 object can be the key or the key's value.
If you pass a table size that is not a power of 2, make-hash-table rounds it up to the next power of 2.
The table grows as needed. length returns the current size.
If a key is not in the table, hash-table-ref returns #f. To remove a key,
set its value to #f; to remove all keys, (fill! table #f).
> (let ((ht (make-hash-table)))
(set! (ht "hi") 123)
(ht "hi"))
123
hash-table (the function) parallels the functions vector, list, and string.
Its arguments are
the keys and values: (hash-table 'a 1 'b 2).
Implicit indexing gives multilevel hashes:
> (let ((h (hash-table 'a (hash-table 'b 2 'c 3)))) (h 'a 'b)) 2 > (let ((h (hash-table 'a (hash-table 'b 2 'c 3)))) (set! (h 'a 'b) 4) (h 'a 'b)) 4
hash-code is like Common Lisp's sxhash. It returns an integer that can be associated with an s7 object when implementing your own hash-tables. s7test.scm has an example using vectors. The eqfunc argument is currently ignored (hash-code assumes equal? is in use).
Since hash-tables accept the same applicable-object syntax that vectors use, we can treat a hash-table as, for example, a sparse array:
> (define make-sparse-array make-hash-table) make-sparse-array > (let ((arr (make-sparse-array))) (set! (arr 1032) "1032") (set! (arr -23) "-23") (list (arr 1032) (arr -23))) ("1032" "-23")map and for-each accept hash-table arguments. On each iteration, the map or for-each function is passed an entry,
'(key . value), in whatever order the entries are encountered in the table.(define (hash-table->alist table) (map values table))reverse of a hash-table returns a new table with the keys and values reversed. fill! sets all the values. Two hash-tables are equal if they have the same keys with the same values. This is independent of the table sizes, or the order in which the key/value pairs were added.
The second argument to make-hash-table (eq-func) is slightly complicated. If it is omitted, s7 chooses the hashing equality and mapping functions based on the keys in the hash-table. There are times when you know in advance what equality function you want. If it's one of the built-in s7 equality functions, eq?, eqv?, equal?, equivalent?, =, string=?, string-ci=?, char=?, or char-ci=?, you can pass that function as the second argument. In any other case, you need to give s7 both the equality function and the mapping function. The latter takes any object and returns the hash-table location for it (an integer). The problem here is that for the arbitrary equality function to work, objects that are equal according to that function have to be mapped to the same hash-table location. There's no way for s7 to intuit what this mapping should be except in the built-in cases. So to specify some arbitrary function, the second argument is a cons: '(equality-checker mapper).
Here's a brief example. In CLM, we have c-objects of type mus-generator (from s7's point of view), and we want to hash them using equal? (which will call the generator-specific equality function). But s7 doesn't realize that the mus-generator type covers 40 or 50 internal types, so as the mapper we pass mus-type:
(make-hash-table 64 (cons equal? mus-type)).If the hash key is a float (a non-rational number), hash-table-ref uses equivalent?. Otherwise, for example, you could use NaN as a key, but then never be able to access it!
To implement read-time hash-tables using #h(...):
(set! *#readers* (cons (cons #\h (lambda (str) (and (string=? str "h") ; #h(...) (apply hash-table (read))))) *#readers*)) (display #h(:a 1)) (newline) (display #h(:a 1 :b "str")) (newline)These can be made immutable by
(immutable! (apply...)), or even better,(let ((h (apply hash-table (read)))) (if (> (*s7* 'safety) 1) (immutable! h) h))(define-macro (define-memoized name&arg . body) (let ((arg (cadr name&arg)) (memo (gensym "memo"))) `(define ,(car name&arg) (let ((,memo (make-hash-table))) (lambda (,arg) (or (,memo ,arg) ; check for saved value (set! (,memo ,arg) (begin ,@body)))))))) ; set! returns the new value > (define (fib n) (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2))))) fib > (define-memoized (memo-fib n) (if (< n 2) n (+ (memo-fib (- n 1)) (memo-fib (- n 2))))) memo-fib > (time (fib 34)) ; un-memoized time 1.168 ; 0.70 on ccrma's i7-3930 machines > (time (memo-fib 34)) ; memoized time 3.200e-05 > (outlet (funclet memo-fib)) (inlet '{memo}-18 (hash-table '(0 . 0) '(1 . 1) '(2 . 1) '(3 . 2) '(4 . 3) '(5 . 5) '(6 . 8) '(7 . 13) '(8 . 21) '(9 . 34) '(10 . 55) '(11 . 89) '(12 . 144) '(13 . 233) '(14 . 377) '(15 . 610) '(16 . 987) '(17 . 1597) '(18 . 2584) '(19 . 4181) '(20 . 6765) '(21 . 10946) '(22 . 17711) '(23 . 28657) '(24 . 46368) '(25 . 75025) '(26 . 121393) '(27 . 196418) '(28 . 317811) '(29 . 514229) '(30 . 832040) '(31 . 1346269) '(32 . 2178309) '(33 . 3524578) '(34 . 5702887)))but the tail recursive version of fib is simpler and almost as fast as the memoized version, and the iterative version beats both.
The third argument, typers, sets type checkers for the keys and values in the table, much like the third argument to make-vector. It is a cons of the type functions,
(cons symbol? integer?)for example. This says that all the keys must be symbols and all the values integers.> (define (10|12? val) (memv val '(10 12))) 10|12? > (define hash (make-hash-table 8 #f (cons #t 10|12?))) ; any key is ok, but all values must be 10 or 12 (hash-table) > (set! (hash 'a) 10) 10 > hash (hash-table 'a 10) > (set! (hash 'b) 32) error: hash-table-set! value argument 3, 32, is an integer but should be a 10|12?
An environment holds symbols and their values. The global environment, for example, holds all the variables that are defined at the top level. Environments are first class (and applicable) objects in s7.
(rootlet) the top-level (global) environment (curlet) the current (innermost) environment (funclet proc) the environment at the time when proc was defined (funclet? env) #t if env is a funclet (owlet) the environment at the point of the last error (unlet) a let with any built-in functions that do not have their original value (let-ref env sym) get value of sym in env, same as (env sym) (let-set! env sym val) set value of sym in env to val, same as (set! (env sym) val) (inlet . bindings) make a new environment with the given bindings (sublet env . bindings) same as inlet, but the new environment is local to env (varlet env . bindings) add new bindings directly to env (cutlet env . fields) remove bindings from env (let? obj) #t if obj is an environment (with-let env . body) evaluate body in the environment env (outlet env) the environment that encloses the environment env (settable) (let->list env) return the environment bindings as a list of (symbol . value) cons's (openlet env) mark env as open (see below) (openlet? env) #t is env is open (coverlet env) mark env as closed (undo an earlier openlet) (object->let obj) return an environment containing information about obj (let-temporarily vars . body)
> (inlet 'a 1 'b 2) (inlet 'a 1 'b 2) > (let ((a 1) (b 2)) (curlet)) (inlet 'a 1 'b 2) > (let ((x (inlet :a 1 :b 2))) (x 'a)) 1 > (with-let (inlet 'a 1 'b 2) (+ a b)) 3 > (let ((x (inlet :a 1 :b 2))) (set! (x 'a) 4) x) (inlet 'a 4 'b 2) > (let ((x (inlet))) (varlet x 'a 1) x) (inlet 'a 1) > (let ((a 1)) (let ((b 2)) (outlet (curlet)))) (inlet 'a 1) > (let ((e (inlet 'a (inlet 'b 1 'c 2)))) (e 'a 'b)) ; in C terms, e->a->b 1 > (let ((e (inlet 'a (inlet 'b 1 'c 2)))) (set! (e 'a 'b) 3) (e 'a 'b)) 3 > (define* (make-let (a 1) (b 2)) (sublet (rootlet) (curlet))) make-let > (make-let :b 32) (inlet 'a 1 'b 32)
As the names suggest, in s7 an environment is viewed as a disembodied let. Environments are equal if they contain the same symbols with the same values leaving aside shadowing, and taking into account the environment chain up to the rootlet. That is, two environments are equal if any local variable of either has the same value in both.
let-ref and let-set! return #<undefined> if the first argument is not defined in the environment or its parents. To search just the given environment (ignoring its outlet chain), use defined? with the third argument #t before calling let-ref or let-set!:
> (defined? 'car (inlet 'a 1) #t) #f > (defined? 'car (inlet 'a 1)) #t
This matters in let-set!: (let-set! (inlet 'a 1) 'car #f)
is the same as (set! car #f)!
with-let evaluates its body in the given environment, so
(with-let e . body) is equivalent to
(eval `(begin ,@body) e), but probably faster.
Similarly, (let bindings . body) is equivalent to
(eval `(begin ,@body) (apply inlet (flatten bindings))),
ignoring the outer (enclosing) environment (the default outer environment
of inlet is rootlet).
Or better,
(define-macro (with-environs e . body) `(apply let (map (lambda (a) (list (car a) (cdr a))) ,e) '(,@body)))
Or turning it around,
(define-macro (Let vars . body)
`(with-let (sublet (curlet)
,@(map (lambda (var)
(values (symbol->keyword (car var)) (cadr var)))
vars))
,@body))
(Let ((c 4))
(Let ((a 2)
(b (+ c 2)))
(+ a b c)))
It is faster to use (biglet 'a-function) than (with-let biglet a-function).
let-temporarily (now built-into s7) is somewhat similar to fluid-let in other Schemes. Its syntax looks like let, but it first saves the current value, then sets the variable to the new value (via set!), calls the body, and finally restores the original value. It can handle anything settable:
(let-temporarily (((*s7* 'print-length) 8)) (display x))
This sets s7's print-length variable to 8 while displaying x, then puts it back to its original value.
> (define ourlet
(let ((x 1))
(define (a-func) x)
(define b-func (let ((y 1))
(lambda ()
(+ x y))))
(curlet)))
(inlet 'x 1 'a-func a-func 'b-func b-func)
> (ourlet 'x)
1
> (let-temporarily (((ourlet 'x) 2))
((ourlet 'a-func)))
2
> ((funclet (ourlet 'b-func)) 'y)
1
> (let-temporarily ((((funclet (ourlet 'b-func)) 'y) 3))
((ourlet 'b-func)))
4
Despite the name, no new environment is created by let-temporarily:
(let () (let-temporarily () (define x 2)) (+ x 1)) is 3.
sublet adds bindings (symbols with associated values) to an environment.
It does not change the environment passed to it, but
just prepends the new bindings, shadowing any old ones,
as if you had called "let".
To add the bindings directly to the environment,
use varlet. Both of these functions accept nil as the
'env' argument as shorthand for (rootlet).
Both also accept other environments as well as individual bindings,
adding all the argument's bindings to the new environment.
inlet is very similar, but normally omits the environment argument.
The arguments to sublet and inlet can be passed as
symbol/value pairs, as a cons, or using keywords as if in define*.
inlet can also be used to copy an environment without accidentally invoking
that environment's copy method.
Here's an example: we want to define two functions that share a local variable:
(varlet (curlet) ; import f1 and f2 into the current environment
(let ((x 1)) ; x is our local variable
(define (f1 a) (+ a x))
(define (f2 b) (* b x))
(inlet 'f1 f1 'f2 f2))) ; export f1 and f2
One way to add reader and writer functions to an individual environment slot is:
(define e (inlet
'x (let ((local-x 3)) ; x's initial value
(dilambda
(lambda () local-x)
(lambda (val) (set! local-x (max 0 (min val 100))))))))
> ((e 'x))
3
> (set! ((e 'x)) 123)
100
funclet returns a function's local environment. Here's an example that keeps a circular buffer of the calls to that function:
(define func (let ((history (let ((lst (make-list 8 #f))) (set-cdr! (list-tail lst 7) lst)))) (lambda (x y) (let ((result (+ x y))) (set-car! history (list result x y)) (set! history (cdr history)) result)))) > (func 1 2) 3 > (func 3 4) 7 > ((funclet func) 'history) #1=(#f #f #f #f #f #f (3 1 2) (7 3 4) . #1#)
It is possible in Scheme to redefine built-in functions such as car.
To ensure that some code sees the original built-in function definitions,
wrap it in (with-let (unlet) ...):
> (let ((caar 123))
(+ caar (with-let (unlet)
(caar '((2) 3)))))
125
Or perhaps better, to keep the current environment intact except for the changed built-ins:
> (let ((x 1)
(display 3))
(with-let (sublet (curlet) (unlet)) ; (curlet) picks up 'x, (unlet) the original 'display
(display x)))
1
with-let and unlet are constants, so you can use them in any context without worrying about whether they've been redefined. As mentioned in the macro section, #_<name> is a built-in reader macro for
(with-let (unlet) <name>), so for example, #_+ is the built-in + function, no matter what. (The environment of built-in functions that unlet accesses is not accessible from scheme code, so there's no way that those values can be clobbered).I think these functions can implement the notions of libraries, separate namespaces, or modules. Here's one way: first the library writer just writes his library. The normal user simply loads it. The abnormal user worries about everything, so first he loads the library in a local let to make sure no bindings escape to pollute his code, and then he uses unlet to make sure that none of his bindings pollute the library code:
(let () (with-let (unlet) (load "any-library.scm" (curlet)) ;; by default load puts stuff in the global environment ...))Now Abnormal User can do what he wants with the library entities. Say he wants to use "lognor" under the name "bitwise-not-or", and all the other functions are of no interest:
(varlet (curlet) 'bitwise-not-or (with-let (unlet) (load "any-library.scm" (curlet)) lognor)) ; lognor is presumably defined in "any-library.scm"Say he wants to make sure the library is cleanly loaded, but all its top-level bindings are imported into the current environment:
(varlet (curlet) (with-let (unlet) (let () (load "any-library.scm" (curlet)) (curlet)))) ; these are the bindings introduced by loading the libraryTo do the same thing, but prepend "library:" to each name:
(apply varlet (curlet) (with-let (unlet) (let () (load "any-library.scm" (curlet)) (map (lambda (binding) (cons (symbol "library:" (symbol->string (car binding))) (cdr binding))) (curlet)))))That's all there is to it! Here is the same idea as a macro:
(define-macro (let! init end . body) ;; syntax mimics 'do: (let! (vars&values) ((exported-names) result) body) ;; (let! ((a 1)) ((hiho)) (define (hiho x) (+ a x))) `(let ,init ,@body (varlet (outlet (curlet)) ,@(map (lambda (export) `(cons ',export ,export)) (car end))) ,@(cdr end)))Well, almost, darn it. If the loaded library file sets (via set!) a global value such as abs, we need to put it back to its original form:
(define (safe-load file) (let ((e (with-let (unlet) ; save the environment before loading (let->list (curlet))))) (load file (curlet)) (let ((new-e (with-let (unlet) ; get the environment after loading (let->list (curlet))))) (for-each ; see if any built-in functions were stepped on (lambda (sym) (unless (assoc (car sym) e) (format () "~S clobbered ~A~%" file (car sym)) (apply set! (car sym) (list (cdr sym))))) new-e)))) ;; say libtest.scm has the line (set! abs odd?) > (safe-load "libtest.scm") "libtest.scm" clobbered abs > (abs -2) 2
openlet marks its argument, either an environment, a closure, a c-object, or a c-pointer as open; coverlet as closed. I need better terminology here! An open object is one that the built-in s7 functions handle specially. If they encounter one in their argument list, they look in the object for their own name, and call that function if it exists. A bare-bones example:
> (abs (openlet (inlet 'abs (lambda (x) 47)))) 47 > (define* (f1 (a 1)) (if (real? a) (abs a) ((a 'f1) a))) f1 > (f1 :a (openlet (inlet 'f1 (lambda (e) 47)))) 47
In CLOS, we'd declare a class and a method, and call make-instance, and then discover that it wouldn't work anyway. Here we have, in effect, an anonymous instance of an anonymous class. I think this is called a "prototype system"; javascript is apparently similar. A slightly more complex example:
(let* ((e1 (openlet
(inlet
'x 3
'* (lambda args
(apply * (if (number? (car args))
(values (car args) ((cadr args) 'x) (cddr args))
(values ((car args) 'x) (cdr args))))))))
(e2 (copy e1)))
(set! (e2 'x) 4)
(* 2 e1 e2)) ; (* 2 3 4) => 24
Perhaps these names would be better: openlet -> with-methods, coverlet -> without-methods, and openlet? -> methods?.
let-ref and let-set! are problematic as methods. It is very easy to get into an infinite loop, especially with let-ref since any reference to the let within the method body probably calls let-ref, which calls the let-ref method. We used to recommend coverlet here, but even that is not enough, so not let-ref and let-set! are immutable; they can't be used as methods. Use let-ref-fallback and let-set-fallback instead, if possible.
object->let returns an environment (more of a dictionary really) that contains details about its argument. It is intended as a debugging aid, underlying a debugger's "inspect" for example.
> (let ((iter (make-iterator "1234")))
(iter)
(iter)
(object->let iter))
(inlet 'value #<iterator: string> 'type iterator? 'at-end #f 'sequence "1234" 'length 4 'position 2)
A c-object (in the sense of s7_make_c_type), can add its own info to this namespace via an object->let
method in its local environment. snd-marks.c has a simple example using a class-wide environment (g_mark_methods),
holding as the value of its 'object->let field the function s7_mark_to_let. The latter uses s7_varlet to
add information to the namespace created by (object->let mark).
(define-macro (value->symbol expr)
`(let ((val ,expr)
(e1 (curlet)))
(call-with-exit
(lambda (return)
(do ((e e1 (outlet e))) ()
(for-each
(lambda (slot)
(if (equal? val (cdr slot))
(return (car slot))))
e)
(if (eq? e (rootlet))
(return #f)))))))
> (let ((a 1) (b "hi"))
(value->symbol "hi"))
b
openlet alerts the rest of s7 that the environment has methods.
(begin
(define fvector? #f)
(define make-fvector #f)
(let ((type (gensym))
(->float (lambda (x)
(if (real? x)
(* x 1.0)
(error 'wrong-type-arg "fvector new value is not a real: ~A" x)))))
(set! make-fvector
(lambda* (len (init 0.0))
(openlet
(inlet :v (make-vector len (->float init))
:type type
:length (lambda (f) len)
:object->string (lambda (f . args) "#<fvector>")
:let-set! (lambda (fv i val) (#_vector-set! (fv 'v) i (->float val)))
:let-ref-fallback (lambda (fv i) (#_vector-ref (fv 'v) i))))))
(set! fvector? (lambda (p)
(and (let? p)
(eq? (p 'type) type))))))
> (define fv (make-fvector 32))
fv
> fv
#<fvector>
> (length fv)
32
> (set! (fv 0) 123)
123.0
> (fv 0)
123.0
If an s7 function ignores the type of an argument, as in cons or vector for example, then that argument won't be treated as having any methods.
Since outlet is settable, there are two ways an environment can
become circular. One is to include the current environment as the value of one of its variables.
The other is: (let () (set! (outlet (curlet)) (curlet))).
If you want to hide an environment's fields from any part of s7 that does not know the field names in advance,
(openlet ; make it appear to be empty to the rest of s7
(inlet 'object->string (lambda args "#<let>")
'map (lambda args ())
'for-each (lambda args #<unspecified>)
'let->list (lambda args ())
'length (lambda args 0)
'copy (lambda args (inlet))
'open #t
'coverlet (lambda (e) (set! (e 'open) #f) e)
'openlet (lambda (e) (set! (e 'open) #t) e)
'openlet? (lambda (e) (e 'open))
;; your secret data here
))
(There are still at least two ways to tell that something is fishy).
Here's one way to add a method to a closure:
(define sf (let ((object->string (lambda (obj . arg) "#<secret function!>"))) (openlet (lambda (x) (+ x 1))))) > sf #<secret function!>
In s7, multiple values are spliced directly into the caller's argument list.
> (+ (values 1 2 3) 4)
10
> (string-ref ((lambda () (values "abcd" 2))))
#\c
> ((lambda (a b) (+ a b)) ((lambda () (values 1 2))))
3
> (+ (call/cc (lambda (ret) (ret 1 2 3))) 4) ; call/cc has an implicit "values"
10
> ((lambda* ((a 1) (b 2)) (list a b)) (values :a 3))
(3 2)
(define-macro (call-with-values producer consumer)
`(,consumer (,producer)))
(define-macro (multiple-value-bind vars expr . body)
`((lambda ,vars ,@body) ,expr))
(define-macro (define-values vars expression)
`(if (not (null? ',vars))
(varlet (curlet) ((lambda ,vars (curlet)) ,expression))))
(define (curry function . args)
(if (null? args)
function
(lambda more-args
(if (null? more-args)
(apply function args)
(function (apply values args) (apply values more-args))))))
multiple-values are useful in a several situations. For example,
(if test (+ a b c) (+ a b d e))can be written(+ a b (if test c (values d e))). There are a few special uses of multiple-values. First, you can use the values function to return any number of values, including 0, from map's function application:> (map (lambda (x) (if (odd? x) (values x (* x 20)) (values))) (list 1 2 3)) (1 20 3 60) > (map values (list 1 2 3) (list 4 5 6)) (1 4 2 5 3 6) (define (remove-if func lst) (map (lambda (x) (if (func x) (values) x)) lst)) (define (pick-mappings func lst) (map (lambda (x) (or (func x) (values))) lst)) (define (shuffle . args) (apply map values args)) > (shuffle '(1 2 3) #(4 5 6) '(7 8 9)) (1 4 7 2 5 8 3 6 9) (define (concatenate . args) (apply append (map (lambda (arg) (map values arg)) args)))Second, a macro can return multiple values; these are evaluated and spliced, exactly like a normal macro, so you can use
(values '(define a 1) '(define b 2))to splice multiple definitions at the macro invocation point. If an expansion returns (values), nothing is spliced in. This is mostly useful in reader-cond and the #; reader.> (define-expansion (comment str) (values)) comment > (+ 1 (comment "one") 2 (comment "two")) 3At the top-level (in the REPL), since there's nothing to splice into, you simply get your values back:
> (values 1 (list 1 2) (+ 3 4 5)) (values 1 (1 2) 12)But this printout is just trying to be informative. There is no multiple-values object in s7. You can't
(set! x (values 1 2)), for example. The values function tells s7 that its arguments should be handled in a special way, and the multiple-value indication goes away as soon as the arguments are spliced into some caller's arguments.There are two helper functions for multiple values, apply-values and list-values, both intended primarily for quasiquote where (apply-values ...) implements what other schemes call unquote-splicing (",@..."). (apply-values lst) is like (apply values lst), and (list-values ...) is like (list ...) except in one special case. It is common in writing macros to create some piece of code to be spliced into the output, but if that code is nil, the resulting macro code should contain nothing (not nil). apply-values and list-values cooperate with quasiquote to implement this. As an example:
> (list-values 1 2 (apply-values) 3) (1 2 3) > (define (supply . args) (apply-values args)) supply > (define (consume f . args) (apply f (apply list-values args))) consume > (consume + (supply 1 2) (supply 3 4 5) (supply)) 15 > (consume + (supply)) 0It might seem simpler to return "nothing" from (values), rather than #<unspecified>, but that has drawbacks. First,
(abs -1 (values)), or worse(abs (f x) (f y))is no longer an error at the level of the program text; you lose the ability to see at a glance that a normal function has the right number of arguments. Second, a lot of code currently assumes that (values) returns #<unspecified>, and that implies that(apply values ())does as well. But it would be nice if((lambda* ((x 1)) x) (values))returned 1!Since set! does not evaluate its first argument, and there is no setter for "values",
(set! (values x) ...)is not the same as(set! x ...).(string-set! (values string) ...)works because string-set! does evaluate its first argument.((values + 1 2) (values 3 4) 5)is 15, as anyone would expect.One problem with this way of handling multiple values involves cases where you can't tell whether an expression will return multiple values. Then you have, for example,
(let ((val (expr)))...)and need to accept either a normal single value fromexpr, or one member of the possible set of multiple values. In lint.scm, I'm currently handling this with lambda:(let ((val ((lambda args (car args)) (expr))))...), but this feels kludgey. CL has nth-value which appears to do "the right thing" in this context; perhaps s7 needs it too.A similar difficulty arises in
(if (expr) ...)where(expr)might return multiple values. CL (or sbcl anyway) treats this as if it were wrapped in(nth-value 0 (expr)). Splicing the values in, on the other hand, could lead to disaster: there would be no way to tell from the code that the if statement was valid, or which branch would be taken! So, in those cases where a syntactic form evaluates an argument, s7 follows CL, and uses only the first of the values (this affects if, when, unless, cond, and case).
call-with-exit is call/cc without the ability to jump back into the original context, similar to "return" in C. This is cleaner than call/cc, and much faster.
(define-macro (block . body)
;; borrowed loosely from CL — predefine "return" as an escape
`(call-with-exit (lambda (return) ,@body)))
(define-macro (while test . body) ; while loop with predefined break and continue
`(call-with-exit
(lambda (break)
(let continue ()
(if (let () ,test)
(begin
(let () ,@body)
(continue))
(break))))))
(define-macro (switch selector . clauses) ; C-style case (branches fall through unless break called)
`(call-with-exit
(lambda (break)
(case ,selector
,@(do ((clause clauses (cdr clause))
(new-clauses ()))
((null? clause) (reverse new-clauses))
(set! new-clauses (cons `(,(caar clause)
,@(cdar clause)
,@(map (lambda (nc)
(apply values (cdr nc))) ; doubly spliced!
(if (pair? clause) (cdr clause) ())))
new-clauses)))))))
(define (and-for-each func . args)
;; apply func to the first member of each arg, stopping if it returns #f
(call-with-exit
(lambda (quit)
(apply for-each (lambda arglist
(if (not (apply func arglist))
(quit #<unspecified>)))
args))))
(define (find-if f . args) ; generic position-if is very similar
(call-with-exit
(lambda (return)
(apply for-each (lambda main-args
(if (apply f main-args)
(apply return main-args)))
args))))
> (find-if even? #(1 3 5 2))
2
> (* (find-if > #(1 3 5 2) '(2 2 2 3)))
6
The call-with-exit function's argument (the "continuation") is only valid within the call-with-exit function. In call/cc, you can save it, then call it later to jump back, but if you try that with call-with-exit (from outside the call-with-exit function's body), you'll get an error. This is similar to trying to read from a closed input port.
The other side, so to speak, of call-with-exit, is with-baffle. Sometimes we need a normal call/cc, but want to make sure it is active only within a given block of code. Normally, if a continuation gets away, there's no telling when it might wreak havoc on us. with-baffle blocks that — no continuation can jump into its body:
(let ((what's-for-breakfast ())
(bad-dog 'fido)) ; bad-dog wonders what's for breakfast?
(with-baffle ; the syntax is (with-baffle . body)
(set! what's-for-breakfast
(call/cc
(lambda (biscuit?)
(set! bad-dog biscuit?) ; bad-dog smells a biscuit!
'biscuit!))))
(if (eq? what's-for-breakfast 'biscuit!)
(bad-dog 'biscuit!)) ; now, outside the baffled block, bad-dog wants that biscuit!
what's-for-breakfast) ; but s7 says "No!": baffled! ("continuation can't jump into with-baffle")
continuation? returns #t if its argument is a continuation, as opposed to a normal procedure. I don't know why Scheme hasn't had this function from the very beginning, but it's needed if you want to write a continuable error handler. Here is a sketch of the situation:
(catch #t
(lambda ()
(let ((res (call/cc
(lambda (ok)
(error 'cerror "an error" ok)))))
(display res) (newline)))
(lambda args
(when (and (eq? (car args) 'cerror)
(continuation? (cadadr args)))
(display "continuing...")
((cadadr args) 2))
(display "oops")))
In a more general case, the error handler is separate from the catch body, and needs a way to distinguish a real continuation from a simple procedure.
(define (continuable-error . args)
(call/cc
(lambda (continue)
(apply error args))))
(define (continue-from-error)
(if (continuation? ((owlet) 'continue)) ; might be #<undefined> or a function as in the while macro
(((owlet) 'continue))
'bummer))
object->string returns the string representation of its argument. Its optional second argument can be #f or :display (use display), #t or :write (the default, use write), or :readable. In the latter case, object->string tries to produce a string that can be evaluated via eval-string to return an object equal to the original. The optional third argument sets the maximum desired string length; if object->string notices it has exceeded this limit, it returns the partial string.
> (object->string "hiho") "\"hiho\"" > (format #f "~S" "hiho") "\"hiho\""
s7's format function is very close to that in srfi-48.
> (format #f "~A ~D ~F" 'hi 123 3.14) "hi 123 3.140000"
The format directives (tilde chars) are:
~% insert newline
~& insert newline if preceding char was not newline
~~ insert tilde
~\n (tilde followed by newline): trim white space
~{ begin iteration (take arguments from a list, string, vector, or any other applicable object)
~} end iteration
~^ ~| jump out of iteration
~* ignore the current argument
~C print character (numeric argument = how many times to print it)
~P insert 's' if current argument is not 1 or 1.0 (use ~@P for "ies" or "y")
~A object->string as in display
~S object->string as in write
~B number->string in base 2
~O number->string in base 8
~D number->string in base 10 (~:D for ordinal)
~X number->string in base 16
~E float to string, (format #f "~E" 100.1) -> "1.001000e+02", (%e in C)
~F float to string, (format #f "~F" 100.1) -> "100.100000", (%f in C)
~G float to string, (format #f "~G" 100.1) -> "100.1", (%g in C)
~T insert spaces (padding)
~N get numeric argument from argument list (similar to ~V in CL)
~W object->string with :readable (write readably: "serialization"; s7 is the intended reader)
The eight directives before ~W take the usual numeric arguments to specify field width and precision. These can also be ~N or ~n in which case the numeric argument is read from the list of arguments:
(format #f "~ND" 20 1234) ; => (format "~20D" 1234) " 1234"
(format #f ...) simply returns the formatted string; (format #t ...)
also sends the string to the current-output-port. (format () ...) sends the output to
the current-output-port without returning the string (this mimics the other IO routines
such as display and newline). Other built-in port choices are *stdout* and *stderr*.
Floats can occur in any base, so:
> #xf.c 15.75This also affects format. In most Schemes,
(format #f "~X" 1.25)is an error. In CL, it is equivalent to using ~A which is perverse. But> (number->string 1.25 16) "1.4"and there's no obvious way to get the same effect from format unless we accept floats in the "~X" case. So in s7,
> (format #f "~X" 21) "15" > (format #f "~X" 1.25) "1.4" > (format #f "~X" 1.25+i) "1.4+1.0i" > (format #f "~X" 21/4) "15/4"That is, the output choice matches the argument. A case that came up in the Guile mailing lists is:
(format #f "~F" 1/3). s7 currently returns "1/3", but Clisp returns "0.33333334".
The curly bracket directive applies to anything you can map over, not just lists:
> (format #f "~{~C~^ ~}" "hiho") "h i h o" > (format #f "~{~{~C~^ ~}~^...~}" (list "hiho" "test")) "h i h o...t e s t" > (with-input-from-string (format #f "(~{~C~^ ~})" (format #f "~B" 1367)) read) ; integer->list (1 0 1 0 1 0 1 0 1 1 1)
Since any sequence can be passed to ~{~}, we need a way to truncate output and represent the rest of the sequence with "...", but ~^ only stops at the end of the sequence. ~| is like ~^ but it also stops after it handles (*s7* 'print-length) elements and prints "...". So,
(format #f "~{~A~| ~}" #(0 1 2 3 4))returns "0 1 2 ..." if (*s7* 'print-length) is 3.
I added object->string to s7 before deciding to include format. format excites a vague disquiet — why do we need this ancient unlispy thing? We can almost replace it with:
(define (objects->string . objects) (apply string-append (map (lambda (obj) (object->string obj #f)) objects)))But how to handle lists (~{...~} in format), or columnized output (~T)? I wonder whether formatted string output still matters outside a REPL. Even in that context, a modern GUI leaves formatting decisions to a text or table widget.
(define-macro (string->objects str . objs) `(with-input-from-string ,str (lambda () ,@(map (lambda (obj) `(set! ,obj (eval (read)))) objs))))format is a mess. It is trying to cram two different choices into its first ("port") argument. Perhaps it should be split into format->string and format->port. format->string has no port argument and returns a string. format->port writes to its port argument (which must be an output port, not a boolean), and returns #f or maybe <unspecified>. Then:
(format #f ...) -> (format->string ...) (format () ...) -> (format->port (current-output-port) ...) (format #t ...) -> (display (format->string ...)) (format port ...) -> (display (format->string ...) port)and the currently unavailable choice, format to port without creating a string:
(format->port port ...).
(make-hook . fields) ; make a new hook (hook-functions hook) ; the hook's list of 'body' functions
A hook is a function created by make-hook, and called (normally from C) when something interesting happens. In GUI toolkits hooks are called callback-lists, in CL conditions, in other contexts watchpoints or signals. s7 itself has several hooks: *error-hook*, *read-error-hook*, *unbound-variable-hook*, *missing-close-paren-hook*, *rootlet-redefinition-hook*, *load-hook*, and *autoload-hook*. make-hook is:
(define (make-hook . args)
(let ((body ()))
(apply lambda* args
'(let ((result #<unspecified>))
(let ((e (curlet)))
(for-each (lambda (f) (f e)) body)
result))
())))
So the result of calling make-hook is a function (the lambda* that is applied to args above) that contains a list of functions, 'body. Each function in that list takes one argument, the hook. Each time the hook itself is called, each of the body functions is called, and the value of 'result is returned. That variable, and each of the hook's arguments are accessible to the hook's internal functions by going through the environment passed to the internal functions. This is a bit circuitous; here's a sketch:
> (define h (make-hook '(a 32) 'b)) ; h is a function: (lambda* ((a 32) b) ...)
h
> (set! (hook-functions h) ; this sets ((funclet h) 'body)
(list (lambda (hook) ; each hook internal function takes one argument, the environment
(set! (hook 'result) ; this is the "result" variable above
(format #f "a: ~S, b: ~S" (hook 'a) (hook 'b))))))
(#<lambda (hook)>)
> (h 1 2) ; this calls the hook's internal functions (just one in this case)
"a: 1, b: 2" ; we set "result" to this string, so it is returned as the hook application result
> (h)
"a: 32, b: #f"
In C, to make a hook:
hook = s7_eval_c_string("(make-hook '(a 32) 'b)");
s7_gc_protect(s7, hook);
And call it:
result = s7_call(s7, hook, s7_list(s7, 2, s7_make_integer(s7, 1), s7_make_integer(s7, 2)));
(define-macro (hook . body) ; return a new hook with "body" as its body, setting "result"
`(let ((h (make-hook)))
(set! (hook-functions h) (list (lambda (h) (set! (h 'result) (begin ,@body)))))
h))
(documentation obj) ; old name: (procedure-documentation obj) (signature obj) ; old: (procedure-signature obj) (setter obj) ; old: (procedure-setter obj) (arity obj) ; very old: (procedure-arity obj) (aritable? obj num-args) (funclet proc) (procedure-source proc)
funclet returns a procedure's environment.
> (funclet (let ((b 32)) (lambda (a) (+ a b)))) (inlet 'b 32) > (funclet abs) (rootlet)
setter returns or sets the set function associated with a procedure (set-car! with car, for example).
procedure-source returns the procedure source (a list):
(define (procedure-arglist f) (cadr (procedure-source f)))
documentation returns the documentation string associated with a procedure. This used to be the initial string in the function's body (as in CL), but now it is the value of the '+documentation+ variable, if any, in the procedure's local environment:
(define func
(let ((+documentation+ "helpful info"))
(lambda (a) a)))
> (documentation func)
"helpful info"
Since documentation is a method, a function's documentation can be computed at run-time:
(define func
(let ((documentation (lambda (f) (format #f "this is func's funclet: ~S" (funclet f)))))
(lambda (x)
(+ x 1))))
> (documentation func)
"this is func's funclet: (inlet 'x ())"
arity takes any object and returns either #f if it is not applicable, or a cons containing the minimum and maximum number of arguments acceptable. If the maximum reported is a really big number, that means any number of arguments is ok. aritable? takes two arguments, an object and an integer, and returns #t if the object can be applied to that many arguments.
> (define* (add-2 a (b 32)) (+ a b)) add-2 > (procedure-source add-2) (lambda* (a (b 32)) (+ a b)) > (arity add-2) (0 . 2) > (aritable? add-2 1) #t
signature is a list describing the argument types and returned value type of the function. The first entry in the list is the return type, and the rest are argument types. #t means any type is possible, and 'values means the function returns multiple values.
> (signature round) (integer? real?) ; round takes a real argument, returns an integer > (signature vector-ref) (#t vector? . #1=(integer? . #1#)) ; trailing args are all integers (indices)
If an entry is a list, any of the listed types can occur:
> (signature char-position) ((boolean? integer?) (char? string?) string? integer?)
which says that the first argument to char-position can be a string or a character,
and the return type can be either boolean or an integer. If we know a function returns
multiple values, the return type (first element of the signature) can contain a list
describing each such value: (define (f x) (values (floor x) (ceiling x)))
could be (((integer?) (integer?)) real?).
If the function is defined in scheme, its signature is the value of the '+signature+ variable in its closure:
> (define f1 (let ((+documentation+ "helpful info")
(+signature+ '(boolean? real?)))
(lambda (x)
(positive? x))))
f1
> (documentation f1)
"helpful info"
> (signature f1)
(boolean? real?)
We could do the same thing using methods:
> (define f1 (let ((documentation (lambda (f) "helpful info"))
(signature (lambda (f) '(boolean? real?))))
(openlet ; openlet alerts s7 that f1 has methods
(lambda (x)
(positive? x)))))
> (documentation f1)
"helpful info"
> (signature f1)
(boolean? real?)
signature could also be used to implement CL's 'the:
(define-macro (the value-type form)
`((let ((+signature+ (list ,value-type)))
(lambda ()
,form))))
(display (+ 1 (the integer? (+ 2 3))))
but the optimizer currently doesn't know how to take advantage of this pattern.
You can obviously add your own methods:
(define my-add
(let ((tester (lambda ()
(if (not (= (my-add 2 3) 5))
(format #t "oops: (myadd 2 3) -> ~A~%"
(my-add 2 3))))))
(lambda (x y)
(- x y))))
(define (auto-test) ; scan the symbol table for procedures with testers
(let ((st (symbol-table)))
(for-each (lambda (f)
(let* ((fv (and (defined? f)
(symbol->value f)))
(testf (and (procedure? fv)
((funclet fv) 'tester))))
(when (procedure? testf) ; found one!
(testf))))
st)))
> (auto-test)
oops: (myadd 2 3) -> -1
Even the setter can be set this way:
(define flocals
(let ((x 1))
(let ((+setter+ (lambda (val) (set! x val))))
(lambda ()
x))))
> (flocals)
1
> (setter flocals)
#<lambda (val)>
> (set! (flocals) 32)
32
> (flocals)
32
(define (for-each-subset func args) ;; form each subset of args, apply func to the subsets that fit its arity (let subset ((source args) (dest ()) (len 0)) (if (null? source) (if (aritable? func len) ; does this subset fit? (apply func dest)) (begin (subset (cdr source) (cons (car source) dest) (+ len 1)) (subset (cdr source) dest len)))))
eval evaluates its argument, a list representing a piece of code. It takes an optional second argument, the environment in which the evaluation should take place. eval-string is similar, but its argument is a string.
> (eval '(+ 1 2)) 3 > (eval-string "(+ 1 2)") 3
Leaving aside a few special cases, eval-string could be defined:
(define-macro* (eval-string x e) `(eval (with-input-from-string ,x read) (or ,e (curlet))))
Besides files, ports can also represent strings and functions. The string port functions are:
(with-output-to-string thunk) ; open a string port as current-output-port, call thunk, return string (with-input-from-string string thunk) ; open string as current-input-port, call thunk (call-with-output-string proc) ; open a string port, apply proc to it, return string (call-with-input-string string proc) ; open string as current-input-port, apply proc to it (open-output-string) ; open a string output port (get-output-string port clear) ; return output accumulated in the string output port (open-input-string string) ; open a string input port reading string (open-input-function function) ; open a function input port (open-output-function function) ; open a function output port
> (let ((result #f)
(p (open-output-string)))
(format p "this ~A ~C test ~D" "is" #\a 3)
(set! result (get-output-string p))
(close-output-port p)
result)
"this is a test 3"
In get-output-string, if the optional 'clear' argument is #t, the port is cleared (the default in r7rs I think). Other functions:
Use length to get the length in bytes of an input port's file or string. port-line-number is settable (for fancy *#readers*). port-position is the position in bytes of the reader in the port. It is settable. port-file is intended for use with the *libc* library. It returns a c-pointer containing the FILE* pointer associated with the file port (except in Windows):
(call-with-input-file "s7test.scm"
(lambda (p)
(with-let (sublet *libc* :file (port-file p))
(fseek file 1000 SEEK_SET))))
The variable (*s7* 'print-length) sets the upper limit on how many elements of a sequence are printed by object->string and format. When running s7 behind a GUI, you often want input to come from and output to go to arbitrary widgets. The function ports provide a way to redirect IO in C. See below for an example.
The function ports call a function rather than reading or writing the data to a string or file.
See nrepl.scm and s7test.scm for examples. The function-port function is accessible as
((object->let function-port) 'function). These ports are even more esoteric than
their C-side cousins. An example that traps current-ouput-port output:
(let* ((str ())
(stdout-wrapper (open-output-function
(lambda (c)
(set! str (cons c str))))))
(let-temporarily (((current-output-port) stdout-wrapper))
(write-char #\a)
...))
The end-of-file object is #<eof>. When the read function encounters the constant #<eof> it returns #<eof>. This is neither inconsistent nor unusual: read returns either a form or #<eof>. If read encounters a form that contains #<eof>, it returns a form containing #<eof>, just as with any other constant.
> (with-input-from-string "(or x #<eof>)" read) (or x #<eof>) > (eof-object? (with-input-from-string "'#<eof>" read)) #fIf read hits the end of the input while reading a form, it raises an error (e.g. "missing close paren"). If it encounters #<eof> all by itself at the top level (this never happens), it returns that #<eof>. But this is specific to read, not (for example) load:
;; say we have "t234.scm" with: (display "line 1") (newline) #<eof> (display "line 2") (newline) ;; end of t234.scm > (load "t234.scm") line 1 line 2 (with-input-from-file "t234.scm" (lambda () (do ((c (read) (read))) ((eof-object? c)) (eval c)))) line 1Built-in #<eof> has lots of uses, and as far as I can see, no drawbacks. For example, it is common to call read (or one of its friends) in a loop which first checks for #<eof>, then falls into a case statement. In s7, we can dispense with the extra if (and let), and include the #<eof> in the case statement:
(case (read-char) ((#<eof>) (quit-reading)) ((#\a)...)). Another example:(or (eof-object? x) (eqv x 24)...)can be instead:(memv x '(#<eof> 24 ...).The default IO ports are *stdin*, *stdout*, and *stderr*. *stderr* is useful if you want to make sure output is flushed out immediately. The default output port is *stdout* which buffers output until a newline is seen.
An environment can be treated as an IO port, providing what Guile calls a "soft port":
(define (call-with-input-vector v proc) (let ((i -1)) (proc (openlet (inlet 'read (lambda (p) (v (set! i (+ i 1)))))))))Here the IO port is an open environment that redefines the "read" function so that it returns the next element of a vector. See stuff.scm for call-with-output-vector. The "proc" argument above can also be a macro, giving you a kludgey way to get around the dumb "lambda". Here are more useful examples:
(openlet ; a soft port for format that sends its output to *stderr* and returns the string (inlet 'format (lambda (port str . args) (apply format *stderr* str args)))) (define (open-output-log name) ;; return a soft output port that does not hold its output file open (define (logit name str) (let ((p (open-output-file name "a"))) (display str p) (close-output-port p))) (openlet (inlet :name name :format (lambda (p str . args) (logit (p 'name) (apply format #f str args))))))) :write (lambda (obj p) (logit (p 'name) (object->string obj #t))) :display (lambda (obj p) (logit (p 'name) (object->string obj #f))) :write-string (lambda (str p) (logit (p 'name) str)) :write-char (lambda (ch p) (logit (p 'name) (string ch))) :newline (lambda (p) (logit (p 'name) (string #\newline))) :output-port? (lambda (p) #t) :close-output-port (lambda (p) #f) :flush-output-port (lambda (p) #f) (let ((p (open-output-log "logit.data"))) (format p "this is a test~%") (format p "line: ~A~%" 2))binary-io.scm in the Snd package has functions that read and write integers and floats in both endian choices in a variety of sizes.
If the compile time switch WITH_SYSTEM_EXTRAS is 1, several additional OS-related and file-related functions are built-in. This is work in progress; currently this switch adds:
(directory? str) ; return #t if str is the name of a directory (file-exists? str) ; return #t if str names an existing file (delete-file str) ; try to delete the file, return 0 is successful, else -1 (getenv var) ; return the value of an environment variable: (getenv "HOME") (directory->list dir) ; return contents of directory as a list of strings (if HAVE_DIRENT_H) (system command) ; execute command
But maybe this is not needed; see cload.scm below for a more direct approach.
(error tag . info) ; signal an error of type tag with addition information (catch tag body err) ; if error of type tag signalled in body (a thunk), call err with tag and info (throw tag . info) ; jump to corresponding catch
s7's error handling mimics that of Guile. An error is signalled via the error function, and can be trapped and dealt with via catch.
> (catch 'wrong-number-of-args
(lambda () ; code protected by the catch
(abs 1 2))
(lambda args ; the error handler
(apply format #t (cadr args))))
"abs: too many arguments: (1 2)"
> (catch 'division-by-zero
(lambda () (/ 1.0 0.0))
(lambda args (string->number "+inf.0")))
+inf.0
(define-macro (catch-all . body)
`(catch #t (lambda () ,@body) (lambda args args)))
catch has 3 arguments: a tag indicating what error to catch (#t = anything), the code, a thunk, that the catch is protecting, and the function to call if a matching error occurs during the evaluation of the thunk. The error handler takes a rest argument which will hold whatever the error function chooses to pass it. The error function itself takes at least 2 arguments, the error type, a symbol, and the error message. There may also be other arguments describing the error. The default action, in the absence of any catch, is to treat the message as a format control string, apply format to it and the other arguments, and send that info to the current-error-port:
(catch #t
(lambda ()
(error 'oops))
(lambda args
(format (current-error-port) "~A: ~A~%~A[~A]:~%~A~%"
(car args) ; the error type
(apply format #f (cadr args)) ; the error info
(port-filename) (port-line-number); error file location
(stacktrace)))) ; and a stacktrace
Normally when reading a file, we have to check for #<eof>, but we can let s7 do that:
(define (copy-file infile outfile) (call-with-input-file infile (lambda (in) (call-with-output-file outfile (lambda (out) (catch 'wrong-type-arg ; s7 raises this error if write-char gets #<eof> (lambda () (do () () ; read/write until #<eof> (write-char (read-char in) out))) (lambda err outfile)))))))catch is not limited to error handling:
(define (map-with-exit func . args) ;; map, but if early exit taken, return the accumulated partial result ;; func takes escape thunk, then args (let* ((result ()) (escape-tag (gensym)) (escape (lambda () (throw escape-tag)))) (catch escape-tag (lambda () (let ((len (apply max (map length args)))) (do ((ctr 0 (+ ctr 1))) ((= ctr len) (reverse result)) ; return the full result if no throw (let ((val (apply func escape (map (lambda (x) (x ctr)) args)))) (set! result (cons val result)))))) (lambda args (reverse result))))) ; if we catch escape-tag, return the partial result (define (truncate-if func lst) (map-with-exit (lambda (escape x) (if (func x) (escape) x)) lst)) > (truncate-if even? #(1 3 5 -1 4 6 7 8)) (1 3 5 -1)But this is less useful than map (it can't map over a hash-table for example), and is mostly reimplementing built-in code. Perhaps s7 should have an extension of map (and more usefully, for-each) that is patterned after dynamic-wind:
(dynamic-for-each init-func main-func end-func . args)where init-func is called with one argument, the length of the shortest sequence argument (for-each and map know this in advance); main-func takes n arguments where n matches the number of sequences passed; and end-func is called even if a jump out of main-func occurs (like dynamic-wind in this regard). In the dynamic-map case, the end-func takes one argument, the current, possibly partial, result list. dynamic-for-each then could easily (but maybe not efficiently) implement generic functions such as ->list, ->vector, and ->string (converting any sequence into a sequence of some other type). map-with-exit would be(define (map-with-exit func . args) (let ((result ())) (call-with-exit (lambda (quit) (apply dynamic-map #f ; no init-func in this case (lambda main-args (apply func quit main-args)) (lambda (res) (set! result res)) args))) result))With all the lambda boilerplate, nested catches are hard to read:
(catch #t (lambda () (catch 'division-by-zero (lambda () (catch 'wrong-type-arg (lambda () (abs -1)) (lambda args (format () "got a bad arg~%") -1))) (lambda args 0))) (lambda args 123))Perhaps we need a macro:
(define-macro (catch-case clauses . body) (let ((base (cons 'lambda (cons () body)))) (for-each (lambda (clause) (let ((tag (car clause))) (set! base `(lambda () (catch ',(or (eq? tag 'else) tag) ,base ,@(cdr clause)))))) clauses) (caddr base))) ;;; the code above becomes: (catch-case ((wrong-type-arg (lambda args (format () "got a bad arg~%") -1)) (division-by-zero (lambda args 0)) (else (lambda args 123))) (abs -1))This is similar to r7rs scheme's "guard", but I don't want a pointless thunk for the body of the catch. Along the same lines:
(define (catch-if test func err) (catch #t func (lambda args (apply (if (test (car args)) err throw) args)))) ; if not caught, re-raise the error via throw (define (catch-member lst func err) (catch-if (lambda (tag) (member tag lst)) func err)) (define-macro (catch* clauses . error) ;; try each clause until one evaluates without error, else error: ;; (macroexpand (catch* ((+ 1 2) (- 3 4)) 'error)) ;; (catch #t (lambda () (+ 1 2)) (lambda args (catch #t (lambda () (- 3 4)) (lambda args 'error)))) (define (builder lst) (if (null? lst) (apply values error) `(catch #t (lambda () ,(car lst)) (lambda args ,(builder (cdr lst)))))) (builder clauses))
When an error is encountered, and when s7 is interrupted via begin_hook, (owlet) returns an environment that contains additional info about that error:
The error-history field depends on the compiler flag WITH_HISTORY. See ow! in stuff.scm for one way to display this data. The *s7* field 'history-size sets the size of the buffer.
To find a variable's value at the point of the error:
((owlet) var). To list all the local bindings from the error outward:(do ((e (outlet (owlet)) (outlet e))) ((eq? e (rootlet))) (format () "~{~A ~}~%" e))To see the current s7 stack,
(stacktrace). You'll probably want to use this in conjunction with *error-hook*. To evaluate the error handler in the environment of the error:(let ((x 1)) (catch #t (lambda () (let ((y 2)) (error 'oops))) (lambda args (with-let (sublet (owlet) :args args) ; add the error handler args (list args x y))))) ; we have access to 'y'To limit the maximum size of the stack, set (*s7* 'max-stack-size).
The hook *error-hook* provides a way to specialize error reporting. Its arguments are named 'type and 'data.
(set! (hook-functions *error-hook*)
(list (lambda (hook)
(apply format *stderr* (hook 'data))
(newline *stderr*))))
*read-error-hook* provides two hooks into the reader. A major problem when reading code written for other Schemes is that each Scheme provides a plethora of idiosyncratic #-names (even special character names), and \ escapes in string constants. *read-error-hook* provides a way to handle these weird cases. If a #-name is encountered that s7 can't deal with, *read-error-hook* is called with two arguments, #t and the string representing the constant. If you set (hook 'result), that result is returned to the reader. Otherwise a 'read-error is raised and you drop into the error handler. Similarly, if some bizaare \ use occurs, *read-error-hook* is called with two arguments, #f and the offending character. If you return a character, it is passed to the reader; otherwise you get an error. lint.scm has an example.
*rootlet-redefinition-hook* is called when a top-level variable is redefined (via define and friends, not set!).
(set! (hook-functions *rootlet-redefinition-hook*)
(list (lambda (hook)
(format *stderr* "~A ~A~%" (hook 'name) (hook 'value)))))
will print out the variable's name and the new value.
The s7-built-in catch tags are 'wrong-type-arg, 'syntax-error, 'read-error, 'unbound-variable, 'out-of-memory, 'wrong-number-of-args, 'format-error, 'out-of-range, 'division-by-zero, 'io-error, and 'bignum-error.
If s7 encounters an unbound variable, it first looks to see if it has any autoload information about it. This info can be declared via autoload, a function of two arguments, the symbol that triggers the autoload, and either a filename or a function. If a filename, s7 loads that file; if a function, it is called with one argument, the current (calling) environment.
(autoload 'channel-distance "dsp.scm") ;; now if we subsequently call channel-distance but forget to load "dsp.scm" first, ;; s7 loads "dsp.scm" itself, and uses its definition of channel-distance. ;; The C-side equivalent is s7_autoload. ;; here is the cload.scm case, loading j0 from the math library if it is called: (autoload 'j0 (lambda (e) (unless (provided? 'cload.scm) (load "cload.scm")) (c-define '(double j0 (double)) "" "math.h") (varlet e 'j0 j0)))
The entity (hash-table or environment probably) that holds the autoload info is named *autoload*. If after checking autoload, the symbol is still unbound, s7 calls *unbound-variable-hook*. The offending symbol is named 'variable in the hook environment. If after running *unbound-variable-hook*, the symbol is still unbound, s7 calls the error handler.
The autoloader knows about s7 environments used as libraries, so, for example,
you can (autoload 'j0 "libm.scm"), then use j0 in scheme code. The first
time s7 encounters j0, j0 is undefined, so
s7 loads libm.scm. That load returns the C math library as the environment *libm*.
s7 then automatically looks for j0 in *libm*, and defines it for you.
So the result is the same as if you had defined j0 yourself in C code.
You can use the r7rs library mechanism here, or with-let, or
whatever you want! (In Snd, libc, libm, libdl, and libgdbm are automatically
tied into s7 via autoload, so if you call, for example, frexp, libm.scm
is loaded, and frexp is exported from the *libm* environment, then the
evaluator soldiers on, as if frexp had always been defined in s7).
You can also import all of (say) gsl into the current environment
via (varlet (curlet) *libgsl*).
define-constant defines a symbol whose value is always the same (within the current lexical scope), constant? returns #t if its argument is a constant, immutable! declares a sequence to be immutable (its elements can't be changed), and immutable? returns #t if its argument is immutable.
> (define v (immutable! (vector 1 2 3))) #(1 2 3) > (vector-set! v 0 23) error: can't vector-set! #(1 2 3) (it is immutable) > (immutable? v) #t > (define-constant var 32) var > (set! var 1) ;set!: can't alter immutable object: var > (let ((var 1)) var) ;can't bind or set an immutable object: var, line 1
There is one complication here. (immutable! let) closes the let in the sense
that you can't add locals to or delete locals from the let. You can still set! the locals. To make
the locals themselves immutable:
(define (vars-immutable! L)
(with-let L
(for-each (lambda (f)
(immutable! (car f)))
(curlet)))
L)
Now (vars-immutable! let) makes it an error to set! any of the locals, but you
can add locals to the let.
You can speed up evaluation by doing this because it tells the optimizer that the current entries in the let will not change.
To completely petrify the let, (immutable! (vars-immutable! let)).
To make a function's documentation immutable: (with-let (funclet 'f2) (immutable! '+documentation+)),
and similarly for other function closure entries.
define-constant blocks any attempt to set! or shadow the constant (lexically speaking of course), so local constants behave as you'd expect:
> (let () (define-constant x 3) (let ((x 32)) x)) error: can't bind an immutable object: ((x 32)) > (let ((x 3)) (set! x (let () (define-constant x 32) x))) ; outer x is not a constant 32
But watch out for deferred bindings:
> (define (func a) (let ((cvar (+ a 1))) cvar))
func
> (define-constant cvar 23) ; cvar is now globally constant so it can't be shadowed
23
> (func 1) ; here we're trying to shadow cvar
error: can't bind an immutable object: ((cvar (+ a 1)))
> (let ((x 1))
(define z (let ()
(define-constant x 3)
(lambda (y)
(let ((x y)) ; this x is the inner constant x
x))))
(z 1)) ; so this is an error even though the outer x is not a constant
error: can't bind an immutable object: ((x y))
A function can also be a constant. In some cases, the optimizer can take advantage of this information to speed up function calls.
Constants are very similar to things such as keywords (no set, always return itself as its value), variable trace (informative function upon set or keeping a history of past values), typed variables (restricting a variable's values or doing automatic conversions upon set), and notification upon set (either in Scheme or in C; I wanted this many years ago in Snd). The notification function is especially useful if you have a Scheme variable and want to reflect any change in its value immediately in C (see below). In s7, setter sets this function.
Each environment is a set of symbols and their associated values. setter places a function (or macro) between a symbol and its value in a given environment. The setter function takes two arguments, the symbol and the new value, and returns the value that is actually set. If the setter function accepts a third argument, the current (symbol-relative) environment is also passed (the weird argument order is an historical artifact).
(define e ; save environment for use below
(let ((x 3) ; will always be an integer
(y 3) ; will always keep its initial value
(z 3)) ; will report set!
(set! (setter 'x) (lambda (s v) (if (integer? v) v x)))
(set! (setter 'y) (lambda (s v) y))
(set! (setter 'z) (lambda (s v) (format *stderr* "z ~A -> ~A~%" z v) v))
(set! x 3.3) ; x does not change because 3.3 is not an integer
(set! y 3.3) ; y does not change
(set! z 3.3) ; prints "z 3 -> 3.3"
(curlet)))
> e
(inlet 'x 3 'y 3 'z 3.3)
>(begin (set! (e 'x) 123) (set! (e 'y) #()) (set! (e 'z) #f))
;; prints "z 3.3 -> #f"
> e
(inlet 'x 123 'y 3 'z #f)
> (define-macro (reflective-let vars . body)
`(let ,vars
,@(map (lambda (vr)
`(set! (setter ',(car vr))
(lambda (s v)
(format *stderr* "~S -> ~S~%" s v)
v)))
vars)
,@body))
reflective-let
> (reflective-let ((a 1)) (set! a 2))
2 ; prints "a -> 2"
>(let ((a 0))
(set! (setter 'a)
(let ((history (make-vector 3 0))
(position 0))
(lambda (s v)
(set! (history position) v)
(set! position (+ position 1))
(if (= position 3) (set! position 0))
v)))
(set! a 1)
(set! a 2)
((funclet (setter 'a)) 'history))
#(1 2 0)
See also typed-let in stuff.scm. define-constant is more restrictive than a setter that raises an error: the latter does not block nested (possibly non-constant) bindings of the symbol. The setters are kind of ugly. Here's a macro that lets you put the let variable's setter after the initial value:
(define-macro (let/setter vars . body)
;; (let/setter ((name value [setter])...) ...)
(let ((setters (map (lambda (binding)
(and (pair? (cddr binding))
(caddr binding)))
vars))
(gsetters (gensym)))
`(let ((,gsetters (list ,@setters))
,@(map (lambda (binding)
(list (car binding) (cadr binding)))
vars))
,@(do ((s setters (cdr s))
(var vars (cdr var))
(i 0 (+ i 1))
(result ()))
((null? s)
(reverse result))
(if (car s)
(set! result (cons `(set! (setter (quote ,(caar var))) (list-ref ,gsetters ,i)) result))))
,@body)))
(let ((a 3))
(let/setter ((a 1)
(b 2 (lambda (s v)
(+ v a)))) ; this is the outer "a"
(set! a (+ a 1))
(set! b (+ a b))
(display (list a b)) (newline)))
*load-path* is a list of directories to search when loading a file. *load-hook* is a hook whose functions are called just before a file is loaded. The hook function argument, named 'name, is the filename. While loading, port-filename and port-line-number of the current-input-port can tell you where you are in the file. This data is also available after loading via pair-line-number and pair-filename.
(set! (hook-functions *load-hook*)
(list (lambda (hook)
(format () "loading ~S...~%" (hook 'name)))))
(set! (hook-functions *load-hook*)
(cons (lambda (hook)
(format *stderr* "~A~%"
(system (string-append "./snd lint.scm -e '(begin (lint \"" (hook 'name) "\") (exit))'") #t)))
(hook-functions *load-hook*)))
Here's a *load-hook* function that adds the loaded file's directory to the *load-path* variable so that subsequent loads don't need to specify the directory:
(set! (hook-functions *load-hook*)
(list (lambda (hook)
(let ((pos -1)
(filename (hook 'name)))
(do ((len (length filename))
(i 0 (+ i 1)))
((= i len))
(if (char=? (filename i) #\/)
(set! pos i)))
(if (positive? pos)
(let ((directory-name (substring filename 0 pos)))
(if (not (member directory-name *load-path*))
(set! *load-path* (cons directory-name *load-path*)))))))))
As in Common Lisp, *features* is a list describing what is currently loaded into s7. You can check it with the provided? function, or add something to it with provide. In my version of Snd, at startup *features* is:
> *features* (snd-20.0 snd20 snd audio snd-s7 snd-motif gsl alsa xm clm6 clm sndlib linux autoload dlopen history complex-numbers system-extras overflow-checks ratio s7-8.11 s7) > (provided? 'gsl) #t
The other side of provide is require.
(require . things) finds each thing
(via autoload), and if that thing has not already been loaded,
loads the associated file. (require integrate-envelope)
loads "env.scm", for example; in this case it is equivalent to
simply using integrate-envelope, but if placed at the start of
a file, it documents that you're using that function.
In the more normal use, (require snd-ws.scm)
looks for the file that has (provide 'snd-ws.scm)
and if it hasn't already been loaded, loads it ("ws.scm" in this case).
To add your own files to this mechanism, add the provided symbol via autoload.
Since load can take an environment argument, *features* and its friends follow block structure.
So, for example, (let () (require stuff.scm) ...) loads "stuff.scm" into the local environment,
not globally.
*features* is an odd variable: it is spread out across the chain of environments, and can hold features in an intermediate environment that aren't in subsequent (nested) values. One simple way this can happen is to load a file in a let, but cause the load to happen at the top level. The provided entities get added to the top-level *features* value, not the current let's value, but they are actually accessible locally. So *features* is a merge of all its currently accessible values, vaguely like call-next-method in CLOS. We can mimic this behavior:
(let ((x '(a)))
(let ((x '(b)))
(define (transparent-memq sym var e)
(let ((val (symbol->value var e)))
(or (and (pair? val)
(memq sym val))
(and (not (eq? e (rootlet)))
(transparent-memq sym var (outlet e))))))
(let ((ce (curlet)))
(list (transparent-memq 'a 'x ce)
(transparent-memq 'b 'x ce)
(transparent-memq 'c 'x ce)))))
'((a) (b) #f)
Multi-line and in-line comments can be enclosed in #| and |#.
(+ #| add |# 1 2).
Leaving aside this case and the booleans, #f and #t, you can specify your own handlers for
tokens that start with "#". *#readers* is a list of pairs: (char . func).
"char" refers to the first character after the sharp sign (#). "func" is a function of
one argument, the string that follows the #-sign up to the next delimiter. "func" is called
when #<char> is encountered. If it returns something other than #f, the #-expression
is replaced with that value. Scheme has several predefined #-readers for cases such
as #b1, #\a, and so on, but you can override these if you like. If the string
passed in is not the complete #-expression, the function can use read-char or read to get the
rest. Say we'd like #t<number> to interpret the number in base 12:
(set! *#readers* (cons (cons #\t (lambda (str) (string->number (substring str 1) 12))) *#readers*)) > #tb 11 > #t11.3 13.25
Or have #c(real imag) be read as a complex number:
(set! *#readers* (cons (cons #\c (lambda (str) (apply complex (read)))) *#readers*)) > #c(1 2) 1+2i
Here's a reader macro for read-time evaluation:
(set! *#readers* (cons (cons #\. (lambda (str) (and (string=? str ".") (eval (read))))) *#readers*)) > '(1 2 #.(* 3 4) 5) (1 2 12 5)
And a reader that implements #[...]# for literal hash-tables:
> (set! *#readers*
(list (cons #\[ (lambda (str)
(let ((h (make-hash-table)))
(do ((c (read) (read)))
((eq? c ']#) h) ; ]# is a symbol from the reader's point of view
(set! (h (car c)) (cdr c))))))))
((#\[ . #<lambda (str)>))
> #[(a . 1) (b . #[(c . 3)]#)]#
(hash-table '(b . (hash-table '(c . 3))) '(a . 1))
To return no value from a reader, use (values).
> (set! *#readers* (cons (cons #\; (lambda (str) (if (string=? str ";") (read)) (values))) *#readers*)) ((#\; . #<lambda (str)>)) > (+ 1 #;(* 2 3) 4) 5
Here is CL's #+ reader:
(define (sharp-plus str)
;; str here is "+", we assume either a symbol or an expression involving symbols follows
(let ((e (if (string=? str "+")
(read) ; must be #+(...)
(string->symbol (substring str 1)))) ; #+feature
(expr (read))) ; this is the expression following #+
(if (symbol? e)
(if (provided? e)
expr
(values))
(if (not (pair? e))
(error 'wrong-type-arg "strange #+ chooser: ~S~%" e)
(begin ; evaluate the #+(...) expression as in cond-expand
(define (traverse tree)
(if (pair? tree)
(cons (traverse (car tree))
(case (cdr tree) ((())) (else => traverse)))
(if (memq tree '(and or not)) tree
(and (symbol? tree) (provided? tree)))))
(if (eval (traverse e))
expr
(values)))))))
See also the #n= reader below.
(make-list length (initial-element #f)) returns a list of 'length' elements defaulting to 'initial-element'.
(char-position char-or-string searched-string (start 0)) (string-position substring searched-string (start 0))
char-position and string-position search a string for the occurrence of a character, any of a set of characters, or a string. They return either #f if none is found, or the position within the searched string of the first occurrence. The optional third argument sets where the search starts in the second argument.
If char-position's first argument is a string, it is treated as a set of characters, and char-position looks for the first occurrence of any member of that set. Currently, the strings involved are assumed to be C strings (don't expect embedded nulls to work right in this context).
(call-with-input-file "s7.c" ; report any lines with "static " but no following open paren
(lambda (file)
(let loop ((line (read-line file #t)))
(or (eof-object? line)
(let ((pos (string-position "static " line)))
(if (and pos
(not (char-position #\( (substring line pos))))
(if (> (length line) 80)
(begin (display (substring line 0 80)) (newline))
(display line))))
(loop (read-line file #t)))))))
Keywords exist mainly for define*'s benefit. The keyword functions are: keyword?, string->keyword, symbol->keyword, and keyword->symbol. A keyword is a symbol that starts or ends with a colon. The colon is considered to be a part of the symbol name. A keyword is a constant that evaluates to itself.
(symbol-table) (symbol->value sym (env (curlet))) (symbol->dynamic-value sym) (defined? sym (env (curlet)) ignore-rootlet)
defined? returns #t if the symbol is defined in the environment:
(define-macro (defvar name value)
`(unless (defined? ',name)
(define ,name ,value)))
If ignore-rootlet is #t, the search is confined to the given environment.
symbol->value returns the value (lexically) bound to the symbol, whereas symbol->dynamic-value
returns the value dynamically bound to it.
symbol-table returns a vector containing the symbols currently in the symbol-table.
Here we scan the symbol table looking for any function that doesn't have documentation:
(for-each
(lambda (sym)
(if (defined? sym)
(let ((val (symbol->value sym)))
(if (and (procedure? val)
(string=? "" (documentation val)))
(format *stderr* "~S " sym)))))
(symbol-table))
Or get a list of gensyms:
(map (lambda (sym) (if (gensym? sym) sym (values))) (symbol-table))
An automatic software tester (see also tauto.scm and auto-tester.scm in the tools directory):
(for-each
(lambda (sym)
(if (defined? sym)
(let ((val (symbol->value sym)))
(if (procedure? val)
(let ((max-args (cdr (arity val))))
(if (or (> max-args 4)
(memq sym '(exit abort)))
(format () ";skip ~S for now~%" sym)
(begin
(format () ";whack on ~S...~%" sym)
(let ((constants (list #f #t pi () 1 1.5 3/2 1.5+i)))
(let autotest ((args ()) (args-left max-args))
(catch #t (lambda () (apply func args)) (lambda any #f))
(if (> args-left 0)
(for-each
(lambda (c)
(autotest (cons c args) (- args-left 1)))
constants)))))))))))
(symbol-table))
help tries to find information about its argument.
> (help 'caadar) "(caadar lst) returns (car (car (cdr (car lst)))): (caadar '((1 (2 3)))) -> 2"
gc calls the garbage collector. (gc #f) turns off the GC, and (gc #t) turns it on.
If you get an error complaining about a "free cell", this is usually a sign that the GC freed some object that it should have left alone. In straight scheme code, it's an s7 bug; please send me mail about it! In foreign code, it probably indicates that you need to protect some s7_pointer with s7_gc_protect.
(equivalent? x y)
Say we want to check that two different computations came to the same result, and that result might involve circular structures. Will equal? be our friend?
> (equal? 2 2.0) #f > (let ((x +nan.0)) (equal? x x)) #f > (equal? .1 1/10) #f > (= .1 1/10) #f > (= 0.0 0+1e-300i) #f
No! We need an equality check that ignores epsilonic differences in real and complex numbers, and knows that NaNs are equal for all practical purposes. Leaving aside numbers, closed ports are not equal, yet nothing can be done with them. #() is not equal to #2d(). And two closures are never equal, even if their arguments, environments, and bodies are equal. Since there might be circles, it is not easy to write a replacement for equal? in Scheme. So, in s7, if one thing is basically the same as some other thing, they satisfy the function equivalent?.
> (equivalent? 2 2.0) #t > (equivalent? 1/0 1/0) ; NaN #t > (equivalent? .1 1/10) #t ; floating-point epsilon here is 1.0e-15 or thereabouts > (equivalent? 0.0 1e-300) #t > (equivalent? 0.0 1e-14) #f ; its not always #t! > (equivalent? (lambda () #f) (lambda () #f)) #t
The *s7* field equivalent-float-epsilon sets the floating-point fudge factor. I can't decide how bignums should interact with equivalent?. Currently, if a bignum is involved, either here or in a hash-table, s7 uses equal?. Finally, if either argument is an environment with an 'equivalent? method, that method is invoked.
define-expansion defines a macro that expands at read-time. It has the same syntax as define-macro, and (in normal use) the same result, but it is much faster because it expands only once. Similarly, define-expansion* defines a read-time macro*. (See also define-with-macros in s7test.scm for a way to expand macros in a function body at definition time). Since the reader knows almost nothing about the code it is reading, you need to make sure the expansion is defined at the top level and that its name is unique. The reader does know about global variables, so:
(define *debugging* #t)
(define-expansion (assert assertion)
(if *debugging* ; or maybe better, (eq? (symbol->value '*debugging*) #t)
`(unless ,assertion
(format *stderr* "~A: ~A failed~%" (*function*) ',assertion))
(values)))
Now the assertion code is only present in the function body (or wherever) if *debugging* is #t; otherwise assert expands into nothing. Another very handy use is to embed a source file line number into a message; see for example lint-format in lint.scm. Leaving aside read-time expansion and splicing, the real difference between define-macro and define-expansion is that the expansion's result is not evaluated. I'm no historian, but I believe that means that define-expansion creates a (gasp!) f*xpr. In fact:
(define-macro (define-f*xpr name-and-args . body)
`(define ,(car name-and-args)
(apply define-expansion
(append (list (append (list (gensym)) ',(cdr name-and-args))) ',body))))
> (define-f*xpr (mac a) `(+ ,a 1))
mac
> (mac (* 2 3))
(+ (* 2 3) 1)
You can do something similar with a normal macro, or make the indirection explicit:
> (define-macro (fx x) `'(+ 1 ,x)) ; quote result to avoid evaluation fx > (let ((a 3)) (fx a)) (+ 1 a) > (define-expansion (ex x) `(+ 1 ,x)) ex > (let ((x ex) (a 3)) (x a)) ; avoid read-time splicing (+ 1 a) > (let ((a 3)) (ex a)) ; spliced in at read-time 4
As this example shows, the reader knows nothing about the program context,
so if it does not see a list whose first element is a expansion name, it does
not do anything special. In the (x a) case above, the
expansion happens when the code is evaluated, and the expansion result
is simply returned, unevaluated.
You can also use macroexpand to cancel the evaluation of a macro's expansion:
(define-macro (rmac . args)
(if (null? args)
()
(if (null? (cdr args))
`(display ',(car args))
(list 'begin
`(display ',(car args))
(apply macroexpand (list (cons 'rmac (cdr args))))))))
> (macroexpand (rmac a b c))
(begin (display 'a) (begin (display 'b) (display 'c)))
> (begin (rmac a b c d) (newline))
abcd
The main built-in expansion is reader-cond. The syntax is based on cond: the car of each clause is evaluated (in the read-time context), and if it is not false, the remainder of that clause is spliced into the code as if you had typed it from the start.
> '(1 2 (reader-cond ((> 1 0) 3) (else 4)) 5 6) (1 2 3 5 6) > ((reader-cond ((> 1 0) list 1 2) (else cons)) 5 6) (1 2 5 6)
Whenever (*s7* 'profile) is positive, profiling is turned on. As the program runs, the profiler collects data about each function it can identify. At any time, you can call show-profile to see that data. The first timing is inclusive (it includes the time spent in any nested calls), the second is exclusive (it is the time spent just in the current function). In Linux and *BSD, we use clock_gettime() which is reasonably fast, but there is some profiler overhead. In other systems, we use clock() which is amazingly slow. The optimizer sometimes recasts tail recursion and similar cases as while loops, so the number of calls listed may be less than you'd expect, but the overall time should be correct. To clear out the current data, call clear-profile.
*s7* is a let that gives access to some of s7's internal state:
print-length number of elements to print of a non-string sequence
max-string-length maximum size arg to make-string and read-string
max-format-length maximum size arg to ~N or the width and precision fields for floats in format
max-list-length maximum size arg to make-list
max-port-data-size maximum size of a port data buffer
max-vector-length maximum size arg to make-vector and make-hash-table
max-vector-dimensions make-vector dimensions limit
default-hash-table-length default size for make-hash-table (8, tables resize as needed)
initial-string-port-length 128, initial size of a input string port's buffer
output-port-data-size 2048, size of an output port's buffer
history a circular buffer of recent eval entries stored backwards (use set! to add an entry)
history-size eval history buffer size if s7 built WITH_HISTORY=1
history-enabled is history buffer receiving additions (if WITH_HISTORY=1 as above)
debug determines debugging level (see debug.scm), default=0
profile profile switch (0=default, 1=gather profiling info)
profile-info the current profiling data; see profile.scm
profile-prefix name (a symbol) used to identify the current environment in profile data
default-rationalize-error 1e-12
equivalent-float-epsilon 1e-15
hash-table-float-epsilon 1e-12 (currently limited to less than 1e-3).
bignum-precision bits for bignum floats (128)
float-format-precision digits to print for floats (16)
default-random-state the default arg for random
most-positive-fixnum if not using gmp, the most positive integer ("fixnum" comes from CL)
most-negative-fixnum as above, but negative
safety 0 (see below)
undefined-identifier-warnings #f
undefined-constant-warnings #f
accept-all-keyword-arguments #f
autoloading? #t
openlets #t, whether any let can be open globally (this overrides all openlets)
expansions? #t, whether expansions are handled at read-time
muffle-warnings? #f, if #t s7_warn does not output anything
cpu-time run time so far
file-names currently loaded files (a list)
catches a list of the currently active catch tags
c-types a list of c-object type names (from s7_make_c_type, etc)
stack the current stack entries
stack-top current stack location
stack-size current stack size
max-stack-size maximum stack size
stacktrace-defaults stacktrace formatting info for error handler
rootlet-size the number of globals
heap-size total cells currently available
max-heap-size maximum heap size
free-heap-size the number of currently unused cells
gc-stats 0 (or #f), 1: show GC activity, 2: heap, 4: stack, 8: protected_objects, #t = 1
gc-freed number of cells freed by the last GC pass
gc-total-freed number of cells freed so far by the GC; the total allocated is probably close to
(with-let *s7* (+ (- heap-size free-heap-size) gc-total-freed))
gc-info a list: calls total-time ticks-per-second (see profile.scm)
gc-temps-size number of cells just allocated that are protected from the GC (256)
gc-resize-heap-fraction when to resize the heap (0.8); these two are aimed at GC experiments
gc-resize-heap-by-4-fraction when to get panicky about resizing the heap
gc-protected-objects vector of the objects permanently protected from the GC
memory-usage a description of current memory allocations (sent to current-output-port)
Use the standard environment syntax to access these fields:
(*s7* 'stack-top). stuff.scm has the function
*s7*->list that returns most of these fields in a list.
The compile-time defaults for some of these fields can be set:
heap-size: INITIAL_HEAP_SIZE (64000) stack-size: INITIAL_STACK_SIZE (4096) gc-temps-size: GC_TEMPS_SIZE (256) bignum-precision: DEFAULT_BIGNUM_PRECISION (128) history-size: DEFAULT_HISTORY_SIZE (8) print-length: DEFAULT_PRINT_LENGTH (12) gc-resize-heap-fraction: GC_RESIZE_HEAP_FRACTION (0.8) output-port-data-size: OUTPUT_PORT_DATA_SIZE (2048) See also WITH_WARNINGS, S7_ALIGNED, and GC_TRIGGER_SIZE.
(set! (*s7* 'autoloading) #f) turns off the autoloader.
The 'safety variable is an integer. Currently:
0: default. 1: no remove_from_heap (a GC optimization) infinite loop check in eval, sort! and some iterators immutable object check in reverse!, sort!, and fill! more info in (*s7* 'history) for s7_apply_function, s7_call and s7_eval less aggressive optimization in with-let and lambda warnings about syntax redefinition incoming s7_pointer checks in some FFI functions bignum int to s7_int conversion checks 2: vector, string, and pair constants are immutable (but checks for this are currently sparse)
The debug variable controls where debug.scm is active. If it is (if debug > 0), it inserts
trace calls in functions and so on. It uses dynamic-unwind
to establish a catcher for the return value. (dynamic-unwind function arg) causes
function to be called after the traced function has returned, passing it arg
and the returned value.
(*s7* 'stacktrace-defaults) is a list of four integers and a boolean that tell the error
handler how to format stacktrace information. The four integers are:
how many frames to display,
how many columns are devoted to code display,
how many columns are available for a line of data,
and where to place comments.
The boolean sets whether the entire output should be displayed as a comment.
The defaults are '(3 45 80 45 #t).
This will display s7 memory usage sort of like the top program:
(format *stderr* "~C[~D;~DH" #\escape 0 0) (format *stderr* "~C[J" #\escape) (display (with-output-to-string (lambda() (*s7* 'memory-usage))))
(Ideally we'd only redisplay the changed fields).
The standard time macro:
(define-macro (time expr)
`(let ((start (*s7* 'cpu-time)))
(let ((res (list ,expr))) ; expr might return multiple values
(list (car res)
(- (*s7* 'cpu-time) start)))))
Add automatic log10 recalculation to (*s7* 'bignum-precision):
(define log10 (log (bignum 10))) (define bignum-precision (dilambda (lambda () (*s7* 'bignum-precision)) (lambda (val) (set! (*s7* 'bignum-precision) val) (set! log10 (log (bignum 10))) val)))
The stack, history and gc-protected-objects fields are intended for debugging. Don't keep these hanging around and expect good things to happen!
(c-object? obj) (c-object-type obj) (c-pointer? obj) (c-pointer int type info weak1 weak2) (c-pointer-type obj) (c-pointer-info obj) (c-pointer-weak1 obj) ; also weak2 (c-pointer->list obj)
c-object? returns #t is its argument is a c-object. c-object-type returns the object's type tag (otherwise #f of course). This tag is also the position of the object's type in the (*s7* 'c-types) list. (*s7* 'c-types) returns a list of the types created by s7_make_c_type.
You can wrap up raw C pointers and
pass them around in s7 code. The function c-pointer returns a wrapped pointer,
and c-pointer? returns #t if passed one. (define NULL (c-pointer 0)).
If the type field is a symbol, it is used to check types in s7_c_pointer with_type.
If the 'info field of a c-pointer is a let, that pointer can participate in
the generic functions mechanism, much like a c-object:
> (let ((ptr (c-pointer 1 'abc
(inlet 'object->string
(lambda (obj . args)
(let ((lt (object->let obj)))
(format #f "I am pointer ~A of type '~A!"
(lt 'c-pointer) ; we need c-pointer-type etc
(lt 'c-type))))))))
(openlet ptr)
(object->string ptr))
"I am pointer 1 of type 'abc!"
c-pointer->list returns (list pointer-as-int type info). The "weak1" and "weak2" fields are intended for custom "weak" references. The weak fields values are not marked during the GC sweep, much like a key in a weak-hash-table. If either value is GC'd, that field is set to #f by the GC. The weak fields are ignored by equal? and equivalent? when comparing c-pointers, and by object->string of a c-pointer even if :readable is specified.
There are several tree-oriented functions currently built into s7:
(tree-cyclic? tree) returns #t if tree contains a cycle. (tree-leaves tree) returns the number of leaves in tree. (tree-memq obj tree) returns #t if obj is in tree (using eq?). (tree-set-memq set tree) returns #t if any member of the set (a list of symbols) is in tree. (tree-count obj tree) returns how many times obj is in tree.
s7 originally had Scheme-level multithreading support, but I removed it in August, 2011. It turned out to be less useful than I hoped, mainly because s7 threads shared the heap and therefore had to coordinate all cell allocations. It was faster and simpler to use multiple processes each running a separate s7 interpreter, rather than one s7 running multiple s7 threads. In CLM, there was also contention for access to the output stream. In GUI-related situations, threads were not useful mainly because the GUI toolkits are not thread safe. Last but not least, the effort to make the non-threaded s7 faster messed up parts of the threaded version. Rather than waste a lot of time fixing this, I chose to flush multithreading. s7 is thread-safe:
#include <stdio.h> #include <stdlib.h> #include <pthread.h> #include "s7.h" #define NUM_THREADS 16 static pthread_t threads[NUM_THREADS]; static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER; static void *run_thread(void *obj) { s7_scheme *sc = (s7_scheme *)obj; const char *str; str = s7_object_to_c_string(sc, s7_make_integer(sc, 123)); s7_eval_c_string(sc, "(let () \ (define (f) \ (do ((i 0 (+ i 1))) ((= i 10)) \ (do ((k 0 (+ k 1))) ((= k 1000000))) \ (format *stderr* \"~D \" i))) \ (f))"); pthread_mutex_lock(&lock); fprintf(stderr, "%s\n", str); pthread_mutex_unlock(&lock); } int main(int argc, char **argv) { int32_t i; for (i = 0; i < NUM_THREADS; i++) pthread_create(&threads[i], NULL, run_thread, (void *)s7_init()); for (i = 0; i < NUM_THREADS; i++) pthread_join(threads[i], NULL); exit(0); } /* linux: gcc -o threads threads.c s7.o -Wl,-export-dynamic -pthread -lm -I. -ldl * mac: clang -o threads threads.c s7.o -pthread -lm -I. -ldl */
Some other differences from r5rs:
- no force or delay (see below).
- no syntax-rules or any of its friends.
- no scheme-report-environment, null-environment, or interaction-environment (use curlet).
- no transcript-on or transcript-off.
- begin returns the value of the last form; it can contain both definitions and other statements.
- #<unspecified>, #<eof>, and #<undefined> are first-class objects.
- for-each and map accept different length arguments; the operation stops when any argument reaches its end.
- for-each and map accept any applicable object as the first argument, and any sequence or iterator as a trailing argument.
- letrec*, but without conviction.
- set! and *-set! return the new value (modulo setter), not #<unspecified>.
- define and its friends return the new value.
- port-closed?
- list? means "pair or null", proper-list? is r5rs list?, float? = real and not rational, sequence? = length, byte? = unsigned byte.
- the default IO ports are named *stdin*, *stdout*, and *stderr*.
- #f as an output port means nothing is output (#f is /dev/null, I guess).
- member and assoc accept an optional third argument, the comparison function (equal? is the default).
- case accepts => much like cond (the function argument is the selector).
- if WITH_SYSTEM_EXTRAS is 1, the following are built-in: directory?, file-exists?, delete-file, system, directory->list, getenv.
- s7 is case sensitive.
- when and unless (for r7rs), returning the value of the last form.
- the "d", "f", "s", and "l" exponent markers are not supported by default (use "e", "E", or "@").
- quasiquoted vector constants are not supported (use the normal list expansions wrapped in list->vector).
- type-of returns a type indicator for its argument.
In s7 if a built-in function like gcd is referred to in a function body, the optimizer is free to replace it with #_function. That is,
(gcd ...)can be changed to(#_gcd ...)at s7's whim, if gcd has its original value at the time the optimizer sees the expression using it. A subsequent(set! gcd +)does not affect this optimized call. I think I could wave my hands and mumble about "aggressive lexical scope" or something, but actually the choice here is that speed trumps that ol' hobgoblin consistency. If you want to change gcd to +, do it before loading code that calls gcd. I think most Schemes handle macros this way: the macro call is replaced by its expansion using its current definition, and a later redefinition does not affect earlier uses. Guile behaves like s7:(define (add1 x) (+ x 1)) (set! + -) (display (add1 3))) ; 4 in both s7 and Guile 3.0.4But if a Scheme function is involved, things get messy:
(define (fib n) (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2))))) (define oldfib fib) (set! fib 32) (display (oldfib 10))) ; s7 says 55, Guile says "wrong type to apply: 32"I can't decide which way is correct: s7 looks more consistent, but:
(define (fib n) 32) (set! fib (lambda (n) (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))) (define oldfib fib) (set! fib 32) (display (oldfib 10)) ; "attempt to apply an integer 32 to..."So s7 is inconsistent too! (Actually this was consistent until Jan 2021 when I suddenly thought it was a mistake and "fixed" it; now I'm having second thoughts.
Here are some changes I'd make to s7 if I didn't care about compatibility with other Schemes:
- remove the exact/inexact distinction including #i and #e (done! #i means int-vector constant).
- remove call-with-values and its friends
- remove char-ready?
- change eof-object? to eof? or just omit it (you can use eq? #<eof>)
- change make-rectangular to complex (done!), and remove make-polar.
- remove unquote (the name, not the functionality).
- remove cond-expand.
- remove *-ci functions
- remove #d (done!)
(most of these are removed if you set the compiler flag WITH_PURE_S7), and perhaps:
- remove even? and odd?, gcd and lcm.
- remove string-length and vector-length.
- remove list-ref|set!, string-ref|set!, vector-ref|set!, hash-table-ref|set!, set-car!|cdr!, and set-current-output|input|error-port.
- change file-exists? to file? (or omit it and assume the use of libc.scm — why reinvent the wheel?).
- remove all the conversion and copy functions like vector->list and vector-copy (use copy or map).
- change string->symbol to symbol (what to do with symbol->string in that case?)
- change with-output-to-* and with-input-from-* to omit the pointless lambda.
- remove the with-* IO functions (e.g. with-input-from-string), keeping the call-with-* versions (call-with-input-string).
- remove assq, assv, memq, and memv (these are pointless now that assoc and member can be passed eq? and eqv?).
- move all the "*var*" names to *s7*: *load-hook* becomes (*s7* 'load-hook) for example.
With the move to s7_setter and s7_set_setter (setter in Scheme), dilambda and dilambda? have been reduced to trivial conveniences, so perhaps they can also be removed.
string-copy has 3 extra arguments to allow strings to be copied directly into other strings. In vectors, we can use subvector, but substring returns a new string (copying its argument) unless the optimizer notices that the copy is not needed. Copy almost works, but its start and end arguments refer to the source, not the destination. substring should be like subvector, but that is not backwards compatible.
There are several less-than-ideal names. get-output-string should be current-output-string. write-char behaves like display, not write. provided? should be feature? or *features* should be *provisions*. list-ref, list-set!, and list-tail actually only apply to pairs. let-temporarily should be templet, or maybe set-temporarily. There should not be two names for the same thing: call/cc and call-with-current-continuation: flush the latter! The CL-inspired "log*" names such as logand look very old-fashioned. Standard scheme opts for the name "bitwise*"; why not "integerwise" or "bytevectorwise"? The "wise" business is just noise; are they thinking of The Hobbit?
(define & logand) (define | logior) (define ~ lognot), but ^ for logxor (as in C) is not ideal; ^ should be expt. Finally, I think the notion of a current input or output port is a mistake: the IO functions should always get an explicit port.cond-expand is dumb and its name is dumber. Take libgsl.scm; different versions of the GSL library have different functions. We need to know when we're building the FFI what GSL version we're dealing with. It would be nuts to start pushing and checking dozens of library version symbols when all we actually want is
(> version 23.19). In place of cond-expand, s7 uses reader-cond, so the read-time decision involves normal Scheme evaluation.Then there's the case case: a case clause without a result appears to be an error in r7rs. But the notation used to indicate that is the same as that used for begin, so if we allow
(begin), we should allow case clauses to have no explicit result. In cond, the "implicit progn" (in CL terminology) includes the test expression, so a clause without a result returns the test result (if true of course). In the case case, s7 returns the selector.(case x ((0 1)))is equivalent to(case x ((0 1) => values)), just as(cond (A))is equivalent to(cond (A => values)). One application is method lookup:((case (obj 'abs) ((#<undefined>) abs) (else)) ...); we would otherwise have to save the lookup result or do it twice. This choice has a ripple effect on do: if no result is specified for do, s7 returns the test result. It also affects hash-tables. Currently hash-table-ref returns #f if the key is not in the table, mimicking assoc and aimed at cond with =>, but if we also use case and #<undefined>, it seems more useful and maybe intuitive to mimic let-ref instead. But if hash-table-ref returns #<undefined>, it's harder to use hash-tables as sets. Hmm. In any case, the fall-through value of case should be (and is in s7) #<unspecified>: case is a form of if, so(if #f #f),(cond (#f #f)), and(case #t ((#f) #f))should be equal.Better ideas are always welcome!
Here are the built-in s7 variables:
- *features* ; a list of symbols
- *libraries* ; a list of (filename . let) pairs
- *load-path* ; a list of directories
- *cload-directory* ; directory for cload output
- *autoload* ; autoload info
- *#readers* ; a list of (char . handler) pairs
And the built-in constants:
- pi
- *stdin* *stdout* *stderr*
- *s7*
- +nan.0 -nan.0 +inf.0 -inf.0 (what crappy names! +nan.0 is a positive inexact integer that is not a number?)
- *unbound-variable-hook* *missing-close-paren-hook* *load-hook* *autoload-hook*
- *error-hook* *read-error-hook* *rootlet-redefinition-hook*
Is it odd that the "+" in +nan.0 can't be omitted, but as used in a complex number, someone drops a "+": 1+nan.0i?
(*function*) returns the name (or name and location) of the function currently being called.
(define (example) (*function*))returns'example. Here is an example using a bacro (to access the call-time environment) and an openlet to implement a probe; it reports any operation that the probe participates in, using *function* to get the calling function name:(define (probe-eval val) (let ((all-let (inlet))) (for-each (lambda (sym) (unless (immutable? sym) ; apply-values etc (let ((func (symbol->value sym (rootlet)))) (when (procedure? func) (varlet all-let sym (apply bacro 'args `((let-temporarily (((*s7* 'openlets) #f)) (let ((clean-args (map (lambda (arg) (if (eq? arg probe-eval) (probe-eval 'value) arg)) args))) (format *stderr* "(~S ~{~S~^ ~}) ; ~S~%" ,sym clean-args (*function* (outlet (outlet (curlet))))) (apply ,func clean-args)))))))))) (symbol-table)) (varlet all-let 'value val) (openlet all-let))) (define (call-any x) (+ x 21)) (call-any (probe-eval 42)) ; prints "(+ 42 21) ; call-any", returns 63The second argument to *function* is the let from which to start searching for a function. In the example above, we start the search from the let outside the bacro, since we hope to find the bacro's caller. As a convenience, *function* takes an optional third argument specifying what information you want about the current function. An example:
(*function* (curlet) 'name).namereturns the name (a symbol) of the current function.linereturns the function's definition line number.filereturns the function's definition file. Other possibilities aresignature,documentation,arity,arglist,value, andsource.funcletreturns the current function's funclet.Currently WITH_PURE_S7:
- places 'pure-s7 in *features*
- omits char-ready, char-ci*, string-ci*
- omits string-fill!, vector-fill!, vector-append
- omits list->string, list->vector, string->list, vector->list, let->list
- omits string-length and vector-length
- omits cond-expand, multiple-values-bind|set!, call-with-values
- omits unquote (the name)
- omits d/f/s/l exponents
- omits make-polar and make-rectangular (use complex)
- omits exact?, inexact?, exact->inexact, inexact->exact
- omits set-current-output-port and set-current-input-port
Schemes vary in their treatment of (). s7 considers it a constant that evaluates to itself, so you don't need to quote it.
(eq? () '())is #t. This is consistent with, for example,(eq? #f '#f)which is also #t. The standard says "the empty list is a special object of its own type", so surely either choice is acceptable in that regard (but, sigh, the standard stupidly goes on to deny that () can evaluate to itself). (I'm told that "is an error" means "is not portable" in the standard's weasely abuse of English; if they mean "is not portable" why not say so?). Some of the confusion appears to be caused by the word "list". I would describe the evaluator: "if it gets a constant (and () is a constant) it returns that constant; if a symbol, it returns the value associated with that symbol; if a pair, it looks at the pair's car to decide what to do". It's kinda looney to insist on looking at the car of a list when you know () has no car!Similarly, in s7, vector constants do not have to be quoted. A list constant is quoted to keep it from being evaluated, but #(1 2 3) is as unproblematic as "123" or 123.
These examples bring up another odd corner of scheme: else. In
(cond (else 1))the 'else is evaluated (like any cond test), so its value might be #f; in(case 0 (else 1))it is not evaluated (like any case key), so it's just a symbol. Since setters are local in s7, someone can(let ((else #f)) (cond (else 1)))even if we protect the rootlet 'else. Of course, in scheme this kind of trouble is pervasive, so rather than make 'else a constant I think the best path is to use unlet:(let ((else #f)) (cond (#_else 1))). This is 1 (not ()) because the initial value of 'else can't be changed.s7 handles circular lists and vectors and dotted lists with its customary aplomb. You can pass them to memq, or print them, for example; you can even evaluate them. The print syntax is borrowed from CL:
> (let ((lst (list 1 2 3))) (set! (cdr (cdr (cdr lst))) lst) lst) #1=(1 2 3 . #1#) > (let* ((x (cons 1 2)) (y (cons 3 x))) (list x y)) (#1=(1 . 2) (3 . #1#))But should this syntax be readable as well? I'm inclined to say no because then it is part of the language, and it doesn't look like the rest of the language. (I think it's kind of ugly). Perhaps we could implement it via *#readers*:
(define circular-list-reader (let ((known-vals #f) (top-n -1)) (lambda (str) (define (replace-syms lst) ;; walk through the new list, replacing our special keywords ;; with the associated locations (define (replace-sym tree getter) (if (keyword? (getter tree)) (let ((n (string->number (symbol->string (keyword->symbol (getter tree)))))) (if (integer? n) (let ((lst (assoc n known-vals))) (if lst (set! (getter tree) (cdr lst)) (format *stderr* "#~D# is not defined~%" n))))))) (let walk-tree ((tree (cdr lst))) (if (pair? tree) (begin (if (pair? (car tree)) (walk-tree (car tree)) (replace-sym tree car)) (if (pair? (cdr tree)) (walk-tree (cdr tree)) (replace-sym tree cdr)))) tree)) ;; str is whatever followed the #, first char is a digit (let* ((len (length str)) (last-char (str (- len 1)))) (and (memv last-char '(#\= #\#)) ; is it #n= or #n#? (let ((n (string->number (substring str 0 (- len 1))))) (and (integer? n) (begin (if (not known-vals) ; save n so we know when we're done (begin (set! known-vals ()) (set! top-n n))) (if (char=? last-char #\=) ; #n= (and (eqv? (peek-char) #\() ; eqv? since peek-char can return #<eof> (let ((cur-val (assoc n known-vals))) ;; associate the number and the list it points to ;; if cur-val, perhaps complain? (#n# redefined) (let ((lst (catch #t read (lambda args ; a read error (set! known-vals #f) ; so clear our state (apply throw args))))) ; and pass the error on up (if cur-val (set! (cdr cur-val) lst) (set! known-vals (cons (set! cur-val (cons n lst)) known-vals)))) (if (= n top-n) ; replace our special keywords (let ((result (replace-syms cur-val))) (set! known-vals #f) ; '#1=(#+gsl #1#) -> '(:1)! result) (cdr cur-val)))) ; #n=<not a list>? ;; else it's #n# — set a marker for now since we may not ;; have its associated value yet. We use a symbol name that ;; string->number accepts. (symbol->keyword (symbol (number->string n) (string #\null) " ")))))) ; #n<not an integer>? ))))) ; #n<something else>? (do ((i 0 (+ i 1))) ((= i 10)) ;; load up all the #n cases (set! *#readers* (cons (cons (integer->char (+ i (char->integer #\0))) circular-list-reader) *#readers*))) > '#1=(1 2 . #1#) #1=(1 2 . #1#) > '#1=(1 #2=(2 . #2#) . #1#) #2=(1 #1=(2 . #1#) . #2#)And of course, we can treat these as labels:
(let ((ctr 0)) #1=(begin (format () "~D " ctr) (set! ctr (+ ctr 1)) (if (< ctr 4) #1# (newline))))which prints "0 1 2 3" and a newline.
Length returns +inf.0 if passed a circular list, and returns a negative number if passed a dotted list. In the dotted case, the absolute value of the length is the list length not counting the final cdr.
(define (circular? lst) (infinite? (length lst))).cyclic-sequences returns a list of the cyclic sequences in its argument, or nil.
(define (cyclic? obj) (pair? (cyclic-sequences obj))).Here's an amusing use of circular lists:
(define (for-each-permutation func vals) ;; apply func to every permutation of vals: ;; (for-each-permutation (lambda args (format () "~{~A~^ ~}~%" args)) '(1 2 3)) (define (pinner cur nvals len) (if (= len 1) (apply func (car nvals) cur) (do ((i 0 (+ i 1))) ; I suppose a named let would be more Schemish ((= i len)) (let ((start nvals)) (set! nvals (cdr nvals)) (let ((cur1 (cons (car nvals) cur))) ; add (car nvals) to our arg list (set! (cdr start) (cdr nvals)) ; splice out that element and (pinner cur1 (cdr start) (- len 1)) ; pass a smaller circle on down, "wheels within wheels" (set! (cdr start) nvals)))))) ; restore original circle (let ((len (length vals))) (set-cdr! (list-tail vals (- len 1)) vals) ; make vals into a circle (pinner () vals len) (set-cdr! (list-tail vals (- len 1)) ()))) ; restore its original shapes7 and Snd use "*" in a variable name, *features* for example, to indicate that the variable is predefined. It may occur unprotected in a macro, for example. The "*" doesn't mean that the variable is special in the CL sense of dynamic scope, but some clear marker is needed for a global variable so that the programmer doesn't accidentally step on it.
Although a variable name's first character is more restricted, currently only #\null, #\newline, #\tab, #\space, #\), #\(, #\", and #\; can't occur within the name. I did not originally include double-quote in this set, so wild stuff like
(let ((nam""e 1)) nam""e)would work, but that means that'(1 ."hi")is parsed as a 1 and the symbol."hi", and(string-set! x"hi")is an error. The first character should not be #\#, #\', #\`, #\,, #\:, or any of those mentioned above, and some characters can't occur by themselves. For example, "." is not a legal variable name, but ".." is. These weird symbols have to be printed sometimes:> (list 1 (string->symbol (string #\; #\" #\\)) 2) (1 ;"\ 2) > (list 1 (string->symbol (string #\.)) 2) (1 . 2)which is a mess. Guile prints the first as
(1 #{\;\"\\}# 2). In CL and some Schemes:[1]> (list 1 (intern (coerce (list #\; #\" #\\) 'string)) 2) ; thanks to Rob Warnock (1 |;"\\| 2) [2]> (equalp 'A '|A|) ; in CL case matters here TThis is clean, and has the weight of tradition behind it, but I think I'll use "symbol" instead:
> (list 1 (string->symbol (string #\; #\" #\\)) 2) (1 (symbol ";\"\\") 2)This output is readable, and does not eat up perfectly good characters like vertical bar, but it means we can't easily use variable names like "| e t c |". We could allow a name to contain any characters if it starts and ends with "|", but then one vertical bar is trouble. (The symbol function actually accepts any number of string arguments which it concatenates to form the new symbol name).
These symbols are not just an optimization of string comparison:
> (define-macro (hi a) (let ((funny-name (string->symbol ";"))) `(let ((,funny-name ,a)) (+ 1 ,funny-name)))) hi > (hi 2) 3 > (macroexpand (hi 2)) (let ((; 2)) (+ 1 ;)) ; for a good time, try (string #\") > (define-macro (hi a) (let ((funny-name (string->symbol "| e t c |"))) `(let ((,funny-name ,a)) (+ 1 ,funny-name)))) hi > (hi 2) 3 > (macroexpand (hi 2)) (let ((| e t c | 2)) (+ 1 | e t c |)) > (let ((funny-name (string->symbol "| e t c |"))) ; now use it as a keyword arg to a function (apply define* `((func (,funny-name 32)) (+ ,funny-name 1))) ;; (procedure-source func) is (lambda* ((| e t c | 32)) (+ | e t c | 1)) (apply func (list (symbol->keyword funny-name) 2))) 3I hope that makes you as happy as it makes me!
The built-in syntactic forms, such as "begin", are almost first-class citizens.
> (let ((progn begin)) (progn (define x 1) (set! x 3) (+ x 4))) 7 > (let ((function lambda)) ((function (a b) (list a b)) 3 4)) (3 4) > (apply begin '((define x 3) (+ x 2))) 5 > ((lambda (n) (apply n '(((x 1)) (+ x 2)))) let) 3 (define-macro (symbol-set! var val) ; like CL's set `(apply set! ,var ',val ())) ; trailing nil is just to make apply happy — apply*? (define-macro (progv vars vals . body) `(apply (apply lambda ,vars ',body) ,vals)) > (let ((s '(one two)) (v '(1 2))) (progv s v (+ one two))) 3We can snap together program fragments ("look Ma, no macros!"):
(let* ((x 3) (arg '(x)) (body `((+ ,x x 1)))) ((apply lambda arg body) 12)) ; "legolambda"? (define (engulph form) (let ((body `(let ((L ())) (do ((i 0 (+ i 1))) ((= i 10) (reverse L)) (set! L (cons ,form L)))))) (define function (apply lambda () (list (copy body)))) (function))) (let () (define (hi a) (+ a x)) ((apply let '((x 32)) (list (procedure-source hi))) 12)) ; one function, many closures? (let ((ctr -1)) ; (enum zero one two) but without using a macro (apply begin (map (lambda (symbol) (set! ctr (+ ctr 1)) (list 'define symbol ctr)) ; e.g. '(define zero 0) '(zero one two))) (+ zero one two))But there's a prettier way to implement enum ("transparent-for-each"):
> (define-macro (enum . args) `(for-each define ',args (iota (length ',args)))) enum > (enum a b c) #<unspecified> > b 1Now we notice that
(case 0.0 ((0.0) 1) (else 0))is 1, but how to get pi into a key list?> (apply case 'pi `(((,pi) 1) (else 0))) 1 > (let ((lst '(1 2))) (apply case 'lst `(((,lst) 1) (else 0)))) 1 ; same trick puts a list in the keys > (apply case '+nan.0 `(((,+nan.0) 1) (else 0))) 0 ; (eqv? +nan.0 +nan.0) is #f
(apply define ...)is similar to CL's set.> ((apply define-macro '((m a) `(+ 1 ,a))) 3) 4 > ((apply define '((hi a) (+ a 1))) 3) 4Apply let is very similar to eval:
> (apply let '((a 2) (b 3)) '((+ a b))) 5 > (eval '(+ a b) (inlet 'a 2 'b 3)) 5 > ((apply lambda '(a b) '((+ a b))) 2 3) 5 > (apply let '((a 2) (b 3)) '((list + a b))) ; a -> 2, b -> 3 (+ 2 3)The redundant-looking double lists are for apply's benefit. We could use a trailing null instead (mimicking apply* in some ancient lisps):
> (apply let '((a 2) (b 3)) '(list + a b) ()) (+ 2 3)Scheme claims that it evaluates the car of an expression, then calls the result with the rest of the expression. So
((if x + -) y z)calls either(+ y z)or(- y z)depending on x. But only s7, as far as I know, handles((if x or and) y z).catch, dynamic-wind, and many of the other functions that take function arguments in standard Scheme, accept macros in s7, and dynamic-wind accepts #f as the initial and final entries.
Currently, you can't set! a built-in syntactic keyword to some new value:
(set! if 3). let-temporarily uses set!, so(let-temporarily ((if 3))...)is also unlikely to work.Speaking of speed... It is widely believed that a Scheme with first class everything can't hope to compete with any "real" Scheme. Humph I say. Take this little example (which is not so misleading that I feel guilty about it):
(define (do-loop n) (do ((i 0 (+ i 1))) ((= i n)) (if (zero? (modulo i 1000)) (display "."))) (newline)) (for-each do-loop (list 1000 1000000 10000000))In s7, that takes 0.09 seconds on my home machine. In tinyScheme, from whence we sprang, it takes 85 seconds. In the chicken interpreter, 5.3 seconds, and after compilation (using -O2) of the chicken compiler output, 0.75 seconds. So, s7 is comparable to chicken in speed, even though chicken is compiling to C. I think Guile 2.0.9 takes about 1 second. The equivalent in CL: clisp interpreted 9.3 seconds, compiled 0.85 seconds; sbcl 0.21 seconds. Similarly, s7 computes (fib 40) in 0.8 seconds, approximately the same as sbcl. Guile 2.2.3 takes 7 seconds.
s7's timing tests are in its tools directory. The script valcall.scm runs them through callgrind. The results can be found at the end of s7.c. If you're interested in the standard Scheme benchmarks, it is possible to add s7 to that package. First, s7-prelude.scm and s7-postlude.scm need to be added to the benchmarks src directory. s7-postlude.scm can be empty. My version of s7-prelude.scm is:
(define (this-scheme-implementation-name) "s7") (define exact-integer? integer?) (define (exact-integer-sqrt i) (let ((sq (floor (sqrt i)))) (values sq (- i (* sq sq))))) (define inexact exact->inexact) (define exact inexact->exact) (define (square x) (* x x)) (define (vector-map f v) (copy v)) ; for quicksort.scm (define-macro (import . args) #f) (define (jiffies-per-second) 1000) (define (current-jiffy) (round (* (jiffies-per-second) (*s7* 'cpu-time)))) (define (current-second) (floor (*s7* 'cpu-time)))If you want to run gcbench, add the define-record-type macro from r7rs.scm. Here are the diffs for the bench script:
141a142 > S7=${S7:-"/home/bil/motif-snd/repl"} 187a189 > s7 for s7 406a409,421 > # Definitions specific to s7 > > s7_comp () > { > : > } > > s7_exec () > { > time ${S7} "$1" < "$2" > } > > # ----------------------------------------------------------------------------- 940a957,966 > > s7) NAME='s7' > COMP=s7_comp > EXEC=s7_exec > COMPOPTS="" > EXTENSION="scm" > EXTENSIONCOMP="scm" > COMPCOMMANDS="" > EXECCOMMANDS="" > ;;I call the standalone version of s7 "repl", so its path is /home/bil/motif-snd/repl. To build repl, get s7.tar.gz from https://ccrma.stanford.edu/software/s7/s7.tar.gz; if not using gcc or clang, add the empty file mus-config.h to the tarball's contents, then (in Linux):
gcc s7.c -o repl -DWITH_MAIN -I. -O2 -g -ldl -lm -Wl,-export-dynamic -Wno-stringop-overflowFor timing tests, I add "-fomit-frame-pointer -funroll-loops -march=native". mus-config.h normally has
#define HAVE_COMPLEX_NUMBERS 1 #define HAVE_COMPLEX_TRIG 1but s7.c has defaults, so mus-config.h can be empty, or absent. Finally, go back to the benchmarks directory and
bench s7 allThe benchmark compiler.scm assumes that small integers can be compared with eq? (via assq), which is incorrect. pi.scm and chudnovsky.scm need the gmp version of s7. I ran the bench script on an AMD 3950X machine, and got these results (in seconds): ack: 6.6, array1: 6.4, browse: 11.2, bv2string: 4.1, cat: 0.4, compiler: 16.9, conform: 30.0, cpstak: 42.8, ctak: 16.6, deriv: 9.7, destruc: 8.6, diviter: 3.7, divrec: 4.6, dynamic: 12.6, earley: 25.5, equal: 0.3, fft: 12.5, fib: 6.1, fibc: 8.6, fibfp: 1.1, gcbench: 12.9, grahps: 72.5, lattice: 63.4, matrix: 21.0, maze: 11.4, mazefun: 9.8, mbrot: 12.6, mbrotZ: 8.0, mperm: 18.9, nboyer: 20.1, nqueens: 27.0, ntakl: 8.0, nucleic: 8.3, paraffins: 4.4, parsing: 20.7, peval: 15.2, pnpoly: 9.8, primes: 10.2, puzzle: 10.2, quicksort: 40.0, ray: 8.3, read1: 0.2, sboyer: 19.1, scheme: 29.5, simplex: 26.9, slatex: 4.2, string: 0.8, sum1: 0.2, sum: 4.1, sumfp: 2.2, tail: 0.1, tak: 7.1, takl: 8.1, triangl: 16.4, wc: 4.9. In the gmp case, chudnovsky: 0.017, pi: .01.
In s7, there is only one kind of begin statement, and it can contain both definitions and expressions. These are evaluated in the order in which they occur, and in the environment at the point of the evaluation. I think of it as being a little REPL. begin does not introduce a new frame in the current environment, so defines happen in the enclosing environment. Finally, begin, explicit or otherwise, does not pretend to emulate letrec*.
If we allow defines anywhere, the notion of "lexical scope" becomes problematic. Scheme is already a mess in that regard: take
(let ((x 1)) (do ((y x x) (x 3)) ((> y 1) y)))In
(y x x)the first x is the outer one, and the second is the following do variable, so this returns 3! But sticking to define, in(let ((x 1)) (define y x) (define x 2) y)s7 returns 1 even though technically the second x is in y's environment. Since we treat this as a REPL, y gets its value from the only x defined at the point it is defined. However,
(let ((x 1)) (define y (lambda () x)) (define x 2) (y))returns 2 in s7 because the x in y's function body is not evaluated until after the second x is defined. The define propagates backwards, but:
(list x (define x 0)), or(list x (begin (define x 0) x)).The r7rs compatibility code is in r7rs.scm. I used to include it here, but as r7rs grew, this section got too large. In general, all the conversion routines in r7rs are handled in s7 via generic functions, records are classes, and so on.
"Life", a poem.
(+(*(+))(*)(+(+)(+)(*))) (((((lambda () (lambda () (lambda () (lambda () 1)))))))) (+ (((lambda () values)) 1 2 3)) (map apply (list map) (list map) (list (list *)) '((((1 2)) ((3 4 5))))) (do ((do do do)) (do do do)) (*(*)(*) (+)(+) 1)
s7 exists only to serve as an extension of some other application, so it is primarily a foreign function interface. s7.h has lots of comments about the individual functions. Here I'll collect some complete examples. s7.c depends on the following compile-time flags:
SIZEOF_VOID_P 8 (default) or 4.
WITH_GMP 1 if you want multiprecision arithmetic (requires gmp, mpfr, and mpc, default is 0)
HAVE_COMPLEX_NUMBERS 1 if your compiler supports complex numbers
HAVE_COMPLEX_TRIG 1 if your math library has complex versions of the trig functions
DISABLE_DEPRECATED 1 if you want to make sure you're not using any deprecated s7 stuff (default is 0)
WITH_IMMUTATBLE_UNQUOTE 1 if you want "unquote" omitted (default is 0)
WITH_EXTRA_EXPONENT_MARKERS 1 if you want "d", "f", "l", and "s" in addition to "e" as exponent markers (default is 0)
if someone defends these exponent markers, ask him to read 1l11+11l1i
(in 2 million lines of open-source Scheme, there is not one use of these silly things)
WITH_SYSTEM_EXTRAS 1 if you want some additional OS-related functions built-in (default is 0)
WITH_MAIN 1 if you want s7.c to include a main program section that runs a REPL.
WITH_C_LOADER 1 if you want to be able to load shared object files with load.
See the comment at the start of s7.c for more information about these switches. s7.h defines the two main number types: s7_int and s7_double. The examples that follow show:
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init(); /* initialize the interpreter */
while (1) /* fire up a read-eval-print loop */
{
fprintf(stdout, "\n> "); /* prompt for input */
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{ /* evaluate the input and print the result */
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/* if not using gcc or clang, make mus-config.h (it can be empty), then
*
* gcc -c s7.c -I.
* gcc -o repl repl.c s7.o -lm -I. -ldl
*
* run it:
*
* repl
* > (+ 1 2)
* 3
* > (define (add1 x) (+ 1 x))
* add1
* > (add1 2)
* 3
* > (exit)
*
* for long-term happiness in linux use:
* gcc -o repl repl.c s7.o -Wl,-export-dynamic -lm -I. -ldl
* clang also needs -fPIC I think
* freebsd:
* gcc -o repl repl.c s7.o -Wl,-export-dynamic -lm -I.
* osx:
* gcc -o repl repl.c s7.o -lm -I.
* openbsd:
* gcc -o repl repl.c s7.o -I. -ftrampolines -Wl,-export-dynamic -lm
*/
Since this reads stdin and writes stdout, it can be run as a Scheme subjob of emacs. One (inconvenient) way to do this is to set the emacs variable scheme-program-name to the name of the exectuable created above ("repl"), then call the emacs function run-scheme: M-x eval-expression in emacs, followed by (setq scheme-program-name "repl"), then M-x run-scheme, and you're talking to s7 in emacs. Of course, this connection can be customized indefinitely. See, for example, inf-snd.el in the Snd package.
Here are the not-always-built-in indentations I use in emacs:
(put 'with-let 'scheme-indent-function 1) (put 'with-baffle 'scheme-indent-function 0) (put 'with-sound 'scheme-indent-function 1) (put 'catch 'scheme-indent-function 1) (put 'lambda* 'scheme-indent-function 1) (put 'when 'scheme-indent-function 1) (put 'let-temporarily 'scheme-indent-function 1) (put 'let*-temporarily 'scheme-indent-function 1) (put 'call-with-input-string 'scheme-indent-function 1) (put 'unless 'scheme-indent-function 1) (put 'letrec* 'scheme-indent-function 1) (put 'sublet 'scheme-indent-function 1) (put 'varlet 'scheme-indent-function 1) (put 'case* 'scheme-indent-function 1)
To read stdin while working in a GUI-based program is trickier. In glib, you can use something like this:
static gboolean read_stdin(GIOChannel *source, GIOCondition condition, gpointer data) { /* here read from g_io_channel_unix_get_fd(source) and call s7_eval_string */ return(true); } /* ... during initialization ... */ GIOChannel *channel; channel = g_io_channel_unix_new(STDIN_FILENO); /* watch stdin */ stdin_id = g_io_add_watch_full(channel, /* and call read_stdin above if input is noticed */ G_PRIORITY_DEFAULT, (GIOCondition)(G_IO_IN | G_IO_HUP | G_IO_ERR), read_stdin, NULL, NULL); g_io_channel_unref(channel);
Here's a version that uses libtecla for the line editor:
#include <stdlib.h> #include <stdio.h> #include <string.h> #include <libtecla.h> #include "s7.h" int main(int argc, char **argv) { s7_scheme *s7; char *buffer; char response[1024]; GetLine *gl; /* The tecla line editor */ gl = new_GetLine(500, 5000); s7 = s7_init(); while (1) { buffer = gl_get_line(gl, "> ", NULL, 0); if ((buffer[0] != '\n') || (strlen(buffer) > 1)) { snprintf(response, 1024, "(write %s)", buffer); s7_eval_c_string(s7, response); fprintf(stdout, "\n"); } } gl = del_GetLine(gl); } /* * gcc -c s7.c -I. -O2 -g3 * gcc -o ex1 ex1.c s7.o -lm -I. -ltecla -ldl */
A repl (based on repl.scm or nrepl.scm) is built into s7. Include the compiler flag -DWITH_MAIN:
gcc -o nrepl s7.c -O2 -I. -Wl,-export-dynamic -lm -ldl -DWITH_MAIN -DWITH_NOTCURSES -lnotcurses-core
Common Lisp has something called "evalhook" that makes it possible to insert your own function into the eval loop. In s7, we have a "begin_hook" which sits at the opening of many begin blocks (implicit or explicit). begin_hook is a (C) function; if it sets its bool argument to true, s7 interrupts the current evaluation. Here is a version of the REPL in which begin_hook watches for C-g to interrupt some long computation:
/* terminal-based REPL, * an expansion of the read-eval-print loop program above. * type C-g to interrupt an evaluation. */ #include <stdlib.h> #include <stdio.h> #include <string.h> #include <termios.h> #include <signal.h> #include "s7.h" static struct termios save_buf, buf; static void sigcatch(int n) { /* put things back the way they were */ tcsetattr(fileno(stdin), TCSAFLUSH, &save_buf); exit(0); } static char buffer[512]; static int type_ahead_point = 0; static void watch_for_c_g(s7_scheme *sc, bool *all_done) { char c; /* watch for C-g without blocking, save other chars as type-ahead */ tcsetattr(fileno(stdin), TCSAFLUSH, &buf); if (read(fileno(stdin), &c, 1) == 1) { if (c == 7) /* C-g */ { *all_done = true; type_ahead_point = 0; } else buffer[type_ahead_point++] = c; } tcsetattr(fileno(stdin), TCSAFLUSH, &save_buf); } int main(int argc, char **argv) { s7_scheme *s7; bool use_begin_hook; use_begin_hook = (tcgetattr(fileno(stdin), &save_buf) >= 0); if (use_begin_hook) { buf = save_buf; buf.c_lflag &= ~ICANON; buf.c_cc[VMIN] = 0; buf.c_cc[VTIME] = 0; signal(SIGINT, sigcatch); signal(SIGQUIT, sigcatch); signal(SIGTERM, sigcatch); } s7 = s7_init(); if (argc == 2) { fprintf(stderr, "load %s\n", argv[1]); if (!s7_load(s7, argv[1])) fprintf(stderr, "can't find %s\n", argv[1]); } else { char response[1024]; while (1) { fprintf(stdout, "\n> "); fgets((char *)(buffer + type_ahead_point), 512 - type_ahead_point, stdin); type_ahead_point = 0; if ((buffer[0] != '\n') || (strlen(buffer) > 1)) { snprintf(response, 1024, "(write %s)", buffer); if (use_begin_hook) s7_set_begin_hook(s7, watch_for_c_g); s7_eval_c_string(s7, response); if (use_begin_hook) s7_set_begin_hook(s7, NULL); } } } if (use_begin_hook) tcsetattr(fileno(stdin), TCSAFLUSH, &save_buf); }
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer add1(s7_scheme *sc, s7_pointer args)
{
/* all added functions have this form, args is a list,
* s7_car(args) is the first arg, etc
*/
if (s7_is_integer(s7_car(args)))
return(s7_make_integer(sc, 1 + s7_integer(s7_car(args))));
return(s7_wrong_type_arg_error(sc, "add1", 1, s7_car(args), "an integer"));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_function(s7, "add1", add1, 1, 0, false, "(add1 int) adds 1 to int");
/* add the function "add1" to the interpreter.
* 1, 0, false -> one required arg,
* no optional args,
* no "rest" arg
*/
s7_define_variable(s7, "my-pi", s7_make_real(s7, 3.14159265));
while (1) /* fire up a "repl" */
{
fprintf(stdout, "\n> "); /* prompt for input */
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response); /* evaluate input and write the result */
}
}
}
/* doc7
* > my-pi
* 3.14159265
* > (+ 1 (add1 1))
* 3
* > (exit)
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
int main(int argc, char **argv)
{
s7_scheme *s7;
s7 = s7_init();
s7_define_variable(s7, "an-integer", s7_make_integer(s7, 1));
s7_eval_c_string(s7, "(define (add1 a) (+ a 1))");
fprintf(stderr, "an-integer: %lld\n",
s7_integer(s7_name_to_value(s7, "an-integer")));
s7_symbol_set_value(s7, s7_make_symbol(s7, "an-integer"), s7_make_integer(s7, 32));
fprintf(stderr, "now an-integer: %lld\n",
s7_integer(s7_name_to_value(s7, "an-integer")));
fprintf(stderr, "(add1 2): %lld\n",
s7_integer(s7_call(s7,
s7_name_to_value(s7, "add1"),
s7_cons(s7, s7_make_integer(s7, 2), s7_nil(s7)))));
}
/*
* doc7
* an-integer: 1
* now an-integer: 32
* (add1 2): 3
*/
In more complicated cases, it is probably easier use s7_eval_c_string_with_environment. As an example, say we want to have a C procedure that calls the pretty printer function pp in write.scm, returning a string to C. We need to make sure pp is loaded, and catch any errors that come up. And we need to pass the C-level s7 object to pp. So...
static const char *pp(s7_scheme *sc, s7_pointer obj) /* (pp obj) */
{
return(s7_string(
s7_eval_c_string_with_environment(sc,
"(catch #t \
(lambda () \
(unless (defined? 'pp) \
(load \"write.scm\")) \
(pp obj)) \
(lambda (type info) \
(apply format #f info)))",
s7_inlet(sc, s7_list(sc, 1, s7_cons(sc, s7_make_symbol(sc, "obj"), obj))))));
}
and now when we want a pretty-printed representation of something: pp(sc, obj);
The s7_inlet call is creating a local environment with the object "obj" bound
in scheme to the name "obj" so that (pp obj) will find the "obj" that actually
lives in C. You may need to give the full filename for write.scm, or add its path
to the load-path list. In the latter case, (require write.scm) could
replace (unless (defined?...)).
int main(int argc, const char* argv[])
{
initialiseJuce_NonGUI();
s7_scheme *s7 = s7_init();
if (!s7)
{
std::cout << "Can't start S7!\n";
return -1;
}
s7_pointer val;
std::string str;
while (true)
{
std::cout << "\ns7> ";
std::getline(std::cin, str);
val = s7_eval_c_string(s7, str.c_str());
std::cout << s7_object_to_c_string(s7, val);
}
free(s7);
std::cout << "Bye!\n";
return 0;
}
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
/* assume we've configured and built sndlib, so it has created a mus-config.h file.
* also assume we've built s7 with WITH_SYSTEM_EXTRAS set, so we have file-exists? and delete-file
*/
#include "mus-config.h"
#include "s7.h"
#include "xen.h"
#include "clm.h"
#include "clm2xen.h"
/* we need to redirect clm's mus_error calls to s7_error */
static void mus_error_to_s7(int type, char *msg)
{
s7_error(s7, /* s7 is declared in xen.h, defined in xen.c */
s7_make_symbol(s7, "mus-error"),
s7_cons(s7, s7_make_string(s7, msg), s7_nil(s7)));
}
int main(int argc, char **argv)
{
char buffer[512];
char response[1024];
s7 = s7_init(); /* initialize the interpreter */
s7_xen_initialize(s7); /* initialize the xen stuff (hooks and the xen s7 FFI used by sndlib) */
Init_sndlib(); /* initialize sndlib with all the functions linked into s7 */
mus_error_set_handler(mus_error_to_s7); /* catch low-level errors and pass them to s7-error */
while (1) /* fire up a "repl" */
{
fprintf(stdout, "\n> "); /* prompt for input */
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response); /* evaluate input and write the result */
}
}
}
/* gcc -o doc7 doc7.c -lm -I. /usr/local/lib/libsndlib.a -lasound -ldl
*
* (load "sndlib-ws.scm")
* (with-sound () (outa 10 .1))
* (load "v.scm")
* (with-sound () (fm-violin 0 .1 440 .1))
*
* you might also need -lgsl -lgslcblas -lfftw3
*/
If you built libsndlib.so, it is possible to use it directly in the s7 repl:
repl ; this is a bare s7 running repl.scm via -DWITH_MAIN=1 loading libc_s7.so > (load "/home/bil/test/sndlib/libsndlib.so" (inlet 'init_func 's7_init_sndlib)) #t ; s7_init_sndlib ties all the sndlib functions and variables into s7 > (load "sndlib-ws.scm") tmpnam > (set! *clm-player* (lambda (file) (system (format #f "sndplay ~A" file)))) > (load "v.scm") fm-violin > (with-sound (:play #t) (fm-violin 0 1 440 .1)) "test.snd"
You can use autoload to load libsndlib when needed:
(define (find-library name)
(if (or (file-exists? name)
(char=? (name 0) #\/))
name
(call-with-exit
(lambda (return)
(for-each
(lambda (path)
(let ((new-name (string-append path "/" name)))
(if (file-exists? new-name)
(return new-name))))
*load-path*)
(let ((libs (getenv "LD_LIBRARY_PATH")) ; colon separated directory names
(start 0))
(do ((colon (char-position #\: libs) (char-position #\: libs start)))
((or (not colon)
(let ((new-name (string-append (substring libs start colon) "/" name)))
(and (file-exists? new-name)
(return new-name)))))
(set! start (+ colon 1))))
name))))
(autoload 'clm
(lambda (e)
(load (find-library "libsndlib.so") (inlet '(init_func . s7_init_sndlib)))
(set! *features* (cons 'clm *features*))
(with-let (rootlet) (define clm #t))
(load "sndlib-ws.scm")
(set! *clm-player* (lambda (file) (system (format #f "sndplay ~A" file))))))
and use the repl's vt100 stuff to (for example) post the current begin time as a note list computes:
(define (clm-notehook . args)
;; assume second arg is begin time (first is instrument name)
(when (and (pair? args)
(pair? (cdr args))
(number? (cadr args)))
(with-let (sublet (*repl* 'repl-let) :begin-time (cadr args))
(let ((coords (cursor-coords))
(col (floor (/ last-col 2))))
(let ((str (number->string begin-time)))
(format *stderr* "~C[~D;~DH" #\escape prompt-row col)
(format *stderr* "~C[K~A" #\escape (if (> (length str) col) (substring str 0 (- col 1)) str)))
(format *stderr* "~C[~D;~DH" #\escape (cdr coords) (car coords))))))
(set! *clm-notehook* clm-notehook)
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
/* define *listener-prompt* in scheme, add two accessors for C get/set */
static const char *listener_prompt(s7_scheme *sc)
{
return(s7_string(s7_name_to_value(sc, "*listener-prompt*")));
}
static void set_listener_prompt(s7_scheme *sc, const char *new_prompt)
{
s7_symbol_set_value(sc, s7_make_symbol(sc, "*listener-prompt*"), s7_make_string(sc, new_prompt));
}
/* now add a new type, a struct named "dax" with two fields, a real "x" and a list "data" */
/* since the data field is an s7 object, we'll need to mark it to protect it from the GC */
typedef struct {
s7_double x;
s7_pointer data;
} dax;
static int dax_type_tag = 0;
static s7_pointer dax_to_string(s7_scheme *sc, s7_pointer args)
{
char *data_str, *str;
s7_pointer result;
int data_str_len;
dax *o = (dax *)s7_c_object_value(s7_car(args));
data_str = s7_object_to_c_string(sc, o->data);
data_str_len = strlen(data_str);
str = (char *)calloc(data_str_len + 32, sizeof(char));
snprintf(str, data_str_len + 32, "<dax %.3f %s>", o->x, data_str);
free(data_str);
result = s7_make_string(sc, str);
free(str);
return(result);
}
static s7_pointer free_dax(s7_scheme *sc, s7_pointer obj)
{
free(s7_c_object_value(obj));
return(NULL);
}
static s7_pointer mark_dax(s7_scheme *sc, s7_pointer obj)
{
dax *o;
o = (dax *)s7_c_object_value(obj);
s7_mark(o->data);
return(NULL);
}
static s7_pointer make_dax(s7_scheme *sc, s7_pointer args)
{
dax *o;
o = (dax *)malloc(sizeof(dax));
o->x = s7_real(s7_car(args));
if (s7_cdr(args) != s7_nil(sc))
o->data = s7_cadr(args);
else o->data = s7_nil(sc);
return(s7_make_c_object(sc, dax_type_tag, (void *)o));
}
static s7_pointer is_dax(s7_scheme *sc, s7_pointer args)
{
return(s7_make_boolean(sc,
s7_is_c_object(s7_car(args)) &&
s7_c_object_type(s7_car(args)) == dax_type_tag));
}
static s7_pointer dax_x(s7_scheme *sc, s7_pointer args)
{
dax *o;
o = (dax *)s7_c_object_value(s7_car(args));
return(s7_make_real(sc, o->x));
}
static s7_pointer set_dax_x(s7_scheme *sc, s7_pointer args)
{
dax *o;
o = (dax *)s7_c_object_value(s7_car(args));
o->x = s7_real(s7_cadr(args));
return(s7_cadr(args));
}
static s7_pointer dax_data(s7_scheme *sc, s7_pointer args)
{
dax *o;
o = (dax *)s7_c_object_value(s7_car(args));
return(o->data);
}
static s7_pointer set_dax_data(s7_scheme *sc, s7_pointer args)
{
dax *o;
o = (dax *)s7_c_object_value(s7_car(args));
o->data = s7_cadr(args);
return(o->data);
}
static s7_pointer dax_is_equal(s7_scheme *sc, s7_pointer args)
{
s7_pointer p1, p2;
dax *d1, *d2;
p1 = s7_car(args);
p2 = s7_cadr(args);
if (p1 == p2)
return(s7_t(sc));
if ((!s7_is_c_object(p2)) ||
(s7_c_object_type(p2) != dax_type_tag))
return(s7_f(sc));
d1 = (dax *)s7_c_object_value(p1);
d2 = (dax *)s7_c_object_value(p2);
return(s7_make_boolean(sc,
(d1->x == d2->x) &&
(s7_is_equal(sc, d1->data, d2->data))));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_variable(s7, "*listener-prompt*", s7_make_string(s7, ">"));
dax_type_tag = s7_make_c_type(s7, "dax");
s7_c_type_set_gc_free(s7, dax_type_tag, free_dax);
s7_c_type_set_gc_mark(s7, dax_type_tag, mark_dax);
s7_c_type_set_is_equal(s7, dax_type_tag, dax_is_equal);
s7_c_type_set_to_string(s7, dax_type_tag, dax_to_string);
s7_define_function(s7, "make-dax", make_dax, 2, 0, false, "(make-dax x data) makes a new dax");
s7_define_function(s7, "dax?", is_dax, 1, 0, false, "(dax? anything) returns #t if its argument is a dax object");
s7_define_variable(s7, "dax-x",
s7_dilambda(s7, "dax-x", dax_x, 1, 0, set_dax_x, 2, 0, "dax x field"));
s7_define_variable(s7, "dax-data",
s7_dilambda(s7, "dax-data", dax_data, 1, 0, set_dax_data, 2, 0, "dax data field"));
while (1)
{
fprintf(stdout, "\n%s ", listener_prompt(s7));
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response); /* evaluate input and write the result */
}
}
}
/* (in Linux);
* gcc dax.c -o dax -I. -O2 -g s7.o -ldl -lm -Wl,-export-dynamic -Wno-stringop-overflow
* dax
* > *listener-prompt*
* ">"
* > (set! *listener-prompt* ":")
* ":"
* : (define obj (make-dax 1.0 (list 1 2 3)))
* obj
* : obj
* #<dax 1.000 (1 2 3)>
* : (dax-x obj)
* 1.0
* : (dax-data obj)
* (1 2 3)
* : (set! (dax-x obj) 123.0)
* 123.0
* : obj
* #<dax 123.000 (1 2 3)>
* : (dax? obj)
* #t
* : (exit)
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static void my_print(s7_scheme *sc, uint8_t c, s7_pointer port)
{
fprintf(stderr, "[%c] ", c);
}
static s7_pointer my_read(s7_scheme *sc, s7_read_t peek, s7_pointer port)
{
return(s7_make_character(sc, fgetc(stdin)));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_set_current_output_port(s7, s7_open_output_function(s7, my_print));
s7_define_variable(s7, "io-port", s7_open_input_function(s7, my_read));
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/*
* > (+ 1 2)
* [3]
* > (display "hiho")
* [h] [i] [h] [o] [#] [<] [u] [n] [s] [p] [e] [c] [i] [f] [i] [e] [d] [>]
* > (define (add1 x) (+ 1 x))
* [a] [d] [d] [1]
* > (add1 123)
* [1] [2] [4]
* > (read-char io-port)
* a ; here I typed "a" in the shell
* [#] [\] [a]
*/
In Snd, we want debug.scm (*debug-port*) output to go to the Snd listener text widget. The Snd function listener_append adds a string to that widget's text, so we define:
static void (listener_write)(s7_scheme *sc, uint8_t c, s7_pointer port)
{
char buf[2];
buf[0] = c;
buf[1] = '\0';
listener_append(buf);
}
Then we define a Scheme-side variable, *listener-port*, to be a function port:
s7_define_variable_with_documentation(s7, "*listener-port*", s7_open_output_function(s7, listener_write), "port to write to Snd's listener");
And tie it into *debug-port* via
(set! ((funclet trace-in) '*debug-port*) *listener-port*).
There are several ways to do this. In the first example, we save the original function, and replace it with ours, calling the original whenever possible:
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer old_add; /* the original "+" function for non-string cases */
static s7_pointer old_string_append; /* same, for "string-append" */
static s7_pointer our_add(s7_scheme *sc, s7_pointer args)
{
/* this will replace the built-in "+" operator, extending it to include strings:
* (+ "hi" "ho") -> "hiho" and (+ 3 4) -> 7
*/
if ((s7_is_pair(args)) &&
(s7_is_string(s7_car(args))))
return(s7_apply_function(sc, old_string_append, args));
return(s7_apply_function(sc, old_add, args));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
/* get built-in + and string-append */
old_add = s7_name_to_value(s7, "+");
old_string_append = s7_name_to_value(s7, "string-append");
/* redefine "+" */
s7_define_function(s7, "+", our_add, 0, 0, true, "(+ ...) adds or appends its arguments");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/* > (+ 1 2)
* 3
* > (+ "hi" "ho")
* "hiho"
*/
In the next example, we use the method (inlet) machinery:
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <math.h>
#include "s7.h"
static s7_pointer our_abs(s7_scheme *sc, s7_pointer args)
{
s7_pointer x;
x = s7_car(args);
if (!s7_is_number(x))
{
s7_pointer method;
method = s7_method(sc, x, s7_make_symbol(sc, "abs"));
if (method == s7_undefined(sc)) /* no method found, so raise an error */
s7_wrong_type_arg_error(sc, "abs", 1, x, "a real");
return(s7_apply_function(sc, method, args)); /* else apply the method to the args */
}
return(s7_make_real(sc, (s7_double)fabs(s7_number_to_real(sc, x))));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_function(s7, "our-abs", our_abs, 1, 0, false, "abs replacement");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/* > (our-abs -1)
* 1.0
* > (our-abs (openlet (inlet 'value -3.0 'abs (lambda (x) (abs (x 'value))))))
* 3.0
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer plus(s7_scheme *sc, s7_pointer args)
{
/* (define* (plus (red 32) blue) (+ (* 2 red) blue)) */
return(s7_make_integer(sc, 2 * s7_integer(s7_car(args)) + s7_integer(s7_cadr(args))));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_function_star(s7, "plus", plus, "(red 32) blue", "an example of define* from C");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/*
* > (plus 2 3)
* 7
* > (plus :blue 3)
* 67
* > (plus :blue 1 :red 4)
* 9
* > (plus 2 :blue 3)
* 7
* > (plus :blue 3 :red 1)
* 5
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer plus(s7_scheme *sc, s7_pointer args)
{
/* (define-macro (plus a b) `(+ ,a ,b)) */
s7_pointer a, b;
a = s7_car(args);
b = s7_cadr(args);
return(s7_list(sc, 3, s7_make_symbol(sc, "+"), a, b));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_macro(s7, "plus", plus, 2, 0, false, "plus adds its two arguments");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/*
* > (plus 2 3)
* 5
*/
In scheme, a function becomes generic simply by (apply ((car args) 'func) args).
To accomplish the same thing in C, we use s7_method and s7_apply_function:
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer plus(s7_scheme *sc, s7_pointer args)
{
#define plus_help "(plus obj ...) applies obj's plus method to obj and any trailing arguments."
s7_pointer obj, method;
obj = s7_car(args);
method = s7_method(sc, obj, s7_make_symbol(sc, "plus"));
if (s7_is_procedure(method))
return(s7_apply_function(sc, method, args));
return(s7_f(sc));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
s7 = s7_init();
s7_define_function(s7, "plus", plus, 1, 0, true, plus_help);
while (1)
{
char buffer[512];
char response[1024];
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/* gcc -c s7.c -I.
* gcc -o ex15 ex15.c s7.o -I. -lm -ldl
*
* > (plus 1 2)
* #f
* > (define obj (openlet (inlet 'plus (lambda args (apply + 1 (cdr args))))))
* obj
* > (plus obj 2 3)
* 6
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <signal.h>
#include "s7.h"
static s7_scheme *s7;
struct sigaction new_act, old_act;
static void handle_sigint(int ignored)
{
fprintf(stderr, "interrupted!\n");
s7_symbol_set_value(s7, s7_make_symbol(s7, "*interrupt*"), s7_make_continuation(s7)); /* save where we were interrupted */
sigaction(SIGINT, &new_act, NULL);
s7_quit(s7); /* get out of the eval loop if possible */
}
static s7_pointer our_sleep(s7_scheme *sc, s7_pointer args)
{
/* slow down our infinite loop for demo purposes */
sleep(1);
return(s7_f(sc));
}
int main(int argc, char **argv)
{
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_function(s7, "sleep", our_sleep, 0, 0, false, "(sleep) sleeps");
s7_define_variable(s7, "*interrupt*", s7_f(s7));
/* Scheme variable *interrupt* holds the continuation at the point of the interrupt */
sigaction(SIGINT, NULL, &old_act);
if (old_act.sa_handler != SIG_IGN)
{
memset(&new_act, 0, sizeof(new_act));
new_act.sa_handler = &handle_sigint;
sigaction(SIGINT, &new_act, NULL);
}
while (1)
{
fprintf(stderr, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/*
* > (do ((i 0 (+ i 1))) ((= i -1)) (format () "~D " i) (sleep))
* ;;; now type C-C to break out of this loop
* 0 1 2 ^Cinterrupted!
* ;;; call the continuation to continue from where we were interrupted
* > (*interrupt*)
* 3 4 5 ^Cinterrupted!
* > *interrupt*
* #<continuation>
* > (+ 1 2)
* 3
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer scheme_set_notification(s7_scheme *sc, s7_pointer args)
{
/* this function is called when the Scheme variable is set! */
fprintf(stderr, "%s set to %s\n",
s7_object_to_c_string(sc, s7_car(args)),
s7_object_to_c_string(sc, s7_cadr(args)));
return(s7_cadr(args));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
s7 = s7_init();
s7_define_function(s7, "notify-C", scheme_set_notification, 2, 0, false, "called if notified-var is set!");
s7_define_variable(s7, "notified-var", s7_make_integer(s7, 0));
s7_set_setter(s7, s7_make_symbol(s7, "notified-var"), s7_name_to_value(s7, "notify-C"));
if (argc == 2)
{
fprintf(stderr, "load %s\n", argv[1]);
if (!s7_load(s7, argv[1]))
fprintf(stderr, "can't find %s\n", argv[1]);
}
else
{
char buffer[512];
char response[1024];
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
}
/* > notified-var
* 0
* > (set! notified-var 32)
* notified-var set to 32
* 32
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer func1(s7_scheme *sc, s7_pointer args)
{
return(s7_make_integer(sc, s7_integer(s7_car(args)) + 1));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
s7_pointer new_env;
s7 = s7_init();
/* "func1" and "var1" will be placed in an anonymous environment,
* accessible from Scheme via the global variable "lib-exports"
*/
new_env = s7_inlet(s7, s7_curlet(s7), s7_nil(s7));
/* make a private environment for func1 and var1 below (this is our "namespace") */
s7_gc_protect(s7, new_env);
s7_define(s7, new_env,
s7_make_symbol(s7, "func1"),
s7_make_function(s7, "func1", func1, 1, 0, false, "func1 adds 1 to its argument"));
s7_define(s7, new_env, s7_make_symbol(s7, "var1"), s7_make_integer(s7, 32));
/* those two symbols are now defined in the new environment */
/* add "lib-exports" to the global environment */
s7_define_variable(s7, "lib-exports", s7_let_to_list(s7, new_env));
if (argc == 2)
{
fprintf(stderr, "load %s\n", argv[1]);
if (!s7_load(s7, argv[1]))
fprintf(stderr, "can't find %s\n", argv[1]);
}
else
{
char buffer[512];
char response[1024];
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
}
/* > func1
* ;func1: unbound variable, line 1
* > lib-exports
* ((var1 . 32) (func1 . func1))
* ;; so lib-exports has the C-defined names and values
* ;; we can use these directly:
*
* > (define lib-env (apply sublet (curlet) lib-exports))
* lib-env
* > (with-let lib-env (func1 var1))
* 33
*
* ;; or rename them to prepend "lib:"
* > (define lib-env (apply sublet
(curlet)
(map (lambda (binding)
(cons (string->symbol
(string-append "lib:" (symbol->string (car binding))))
(cdr binding)))
lib-exports)))
* lib-env
* > (with-let lib-env (lib:func1 lib:var1))
* 33
*
* ;;; now for convenience, place "func1" in the global environment under the name "func2"
* > (define func2 (cdadr lib-exports))
* func2
* > (func2 1)
* 2
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer error_handler(s7_scheme *sc, s7_pointer args)
{
fprintf(stdout, "error: %s\n", s7_string(s7_car(args)));
return(s7_f(sc));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
bool with_error_hook = false;
s7 = s7_init();
s7_define_function(s7, "error-handler", error_handler, 1, 0, false, "our error handler");
if (with_error_hook)
s7_eval_c_string(s7, "(set! (hook-functions *error-hook*) \n\
(list (lambda (hook) \n\
(error-handler \n\
(apply format #f (hook 'data))) \n\
(set! (hook 'result) 'our-error))))");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
s7_pointer old_port, result;
int gc_loc = -1;
const char *errmsg = NULL;
/* trap error messages */
old_port = s7_set_current_error_port(s7, s7_open_output_string(s7));
if (old_port != s7_nil(s7))
gc_loc = s7_gc_protect(s7, old_port);
/* evaluate the input string */
result = s7_eval_c_string(s7, buffer);
/* print out the value wrapped in "{}" so we can tell it from other IO paths */
fprintf(stdout, "{%s}", s7_object_to_c_string(s7, result));
/* look for error messages */
errmsg = s7_get_output_string(s7, s7_current_error_port(s7));
/* if we got something, wrap it in "[]" */
if ((errmsg) && (*errmsg))
fprintf(stdout, "[%s]", errmsg);
s7_close_output_port(s7, s7_current_error_port(s7));
s7_set_current_error_port(s7, old_port);
if (gc_loc != -1)
s7_gc_unprotect_at(s7, gc_loc);
}
}
}
/*
* gcc -c s7.c -I. -g3
* gcc -o ex3 ex3.c s7.o -lm -I. -ldl
*
* if with_error_hook is false,
*
* > (+ 1 2)
* {3}
* > (+ 1 #\c)
* {wrong-type-arg}[
* ;+ argument 2, #\c, is character but should be a number, line 1
* ]
*
* so s7 by default prepends ";" to the error message, and appends "\n",
* sending that to current-error-port, and the error type ('wrong-type-arg here)
* is returned.
*
* if with_error_hook is true,
*
* > (+ 1 2)
* {3}
* > (+ 1 #\c)
* error: + argument 2, #\c, is character but should be a number
* {our-error}
*
* so now the *error-hook* code handles both the error reporting and
* the value returned ('our-error in this case).
*/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
static s7_pointer my_hook_function(s7_scheme *sc, s7_pointer args)
{
fprintf(stderr, "a is %s\n", s7_object_to_c_string(sc, s7_symbol_local_value(sc, s7_make_symbol(sc, "a"), s7_car(args))));
return(s7_car(args));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7_pointer test_hook;
s7 = s7_init();
/* define test_hook in C, test-hook in Scheme, arguments are named a and b */
test_hook = s7_eval_c_string(s7, "(make-hook 'a 'b)");
s7_define_constant(s7, "test-hook", test_hook);
/* add my_hook_function to the test_hook function list */
s7_hook_set_functions(s7, test_hook,
s7_cons(s7,
s7_make_function(s7, "my-hook-function", my_hook_function, 1, 0, false, "my hook-function"),
s7_hook_functions(s7, test_hook)));
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/*
* > test-hook
* #<lambda (hook)>
* > (hook-functions test-hook)
* (my-hook-function)
* > (test-hook 1 2)
* a is 1
* #<unspecified>
*/
We can use dlopen to load a shared library, and dlsym to initialize that library in our main program. The tricky part is to conjure up the right compiler and loader flags. First we define a module that defines a new s7 function, add-1 that we'll tie into s7 explicitly, and another function that we'll try to call by waving a wand.
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
double a_function(double an_arg);
double a_function(double an_arg)
{
return(an_arg + 1.0);
}
static s7_pointer add_1(s7_scheme *sc, s7_pointer args)
{
return(s7_make_integer(sc, s7_integer(s7_car(args)) + 1));
}
void init_ex(s7_scheme *sc);
void init_ex(s7_scheme *sc) /* this needs to be globally accessible (not "static") */
{
/* tell s7 about add-1, but leave a_function hidden */
s7_define_function(sc, "add-1", add_1, 1, 0, false, "(add-1 x) adds 1 to x");
}
And here is our main program:
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "s7.h"
#include <dlfcn.h>
static void *library = NULL;
static s7_pointer try(s7_scheme *sc, s7_pointer args)
{
/* try tries to call an arbitrary function in the shared library */
void *func;
func = dlsym(library, s7_string(s7_car(args)));
if (func)
{
/* we'll assume double f(double) */
typedef double (*dl_func)(double arg);
return(s7_make_real(sc, ((dl_func)func)(s7_real(s7_cadr(args)))));
}
return(s7_error(sc, s7_make_symbol(sc, "can't find function"),
s7_list(sc, 2, s7_make_string(sc, "loader error: ~S"),
s7_make_string(sc, dlerror()))));
}
static s7_pointer cload(s7_scheme *sc, s7_pointer args)
{
/* cload loads a shared library */
#define CLOAD_HELP "(cload so-file-name) loads the module"
library = dlopen(s7_string(s7_car(args)), RTLD_LAZY);
if (library)
{
/* call our init func to define add-1 in s7 */
void *init_func;
init_func = dlsym(library, s7_string(s7_cadr(args)));
if (init_func)
{
typedef void *(*dl_func)(s7_scheme *sc);
((dl_func)init_func)(sc); /* call the initialization function (init_ex above) */
return(s7_t(sc));
}
}
return(s7_error(sc, s7_make_symbol(sc, "load-error"),
s7_list(sc, 2, s7_make_string(sc, "loader error: ~S"),
s7_make_string(sc, dlerror()))));
}
int main(int argc, char **argv)
{
char buffer[512];
char response[1024];
s7_scheme *s7;
s7 = s7_init();
s7_define_function(s7, "cload", cload, 2, 0, false, CLOAD_HELP);
s7_define_function(s7, "try", try, 2, 0, false,
"(try name num) tries to call name in the shared library with the argument num.");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/* Put the module in the file ex3a.c and the main program in ex3.c, then
*
* in Linux:
* gcc -c -fPIC ex3a.c
* gcc ex3a.o -shared -o ex3a.so
* gcc -c s7.c -I. -fPIC -shared
* gcc -o ex3 ex3.c s7.o -lm -ldl -I. -Wl,-export-dynamic
* # omit -ldl in freeBSD, openBSD might want -ftrampolines
*
* in Mac OSX:
* gcc -c ex3a.c
* gcc ex3a.o -o ex3a.so -dynamic -bundle -undefined suppress -flat_namespace
* gcc -c s7.c -I. -dynamic -bundle -undefined suppress -flat_namespace
* gcc -o ex3 ex3.c s7.o -lm -ldl -I.
*
* and run it:
* ex3
* > (cload "/home/bil/snd-18/ex3a.so" "init_ex")
* #t
* > (add-1 2)
* 3
* > (try "a_function" 2.5)
* 3.5
*/
All of this is just boring boilerplate, so with a little support from s7, we can write a script to do the entire linkage. The s7 side is an extension to "load" that loads a shared object file if its extension is "so", and runs an initialization function whose name is defined in the load environment (the optional second argument to load). An example of the scheme side is cload.scm, included in the s7 tarball. It defines a function that can be called:
(c-define '(double j0 (double)) "m" "math.h")
This links the s7 function m:j0 to the math library function j0. See cload.scm for more details.
Here's a shorter example:
add1.c:
#include <stdlib.h>
#include "s7.h"
static s7_pointer add1(s7_scheme *sc, s7_pointer args)
{
if (s7_is_integer(s7_car(args)))
return(s7_make_integer(sc, 1 + s7_integer(s7_car(args))));
return(s7_wrong_type_arg_error(sc, "add1", 1, s7_car(args), "an integer"));
}
void add1_init(s7_scheme *sc);
void add1_init(s7_scheme *sc)
{
s7_define_function(sc, "add1", add1, 1, 0, false, "(add1 int) adds 1 to int");
}
/* gcc -fpic -c add1.c
* gcc -shared -Wl,-soname,libadd1.so -o libadd1.so add1.o -lm -lc
* gcc s7.c -o repl -fpic -DWITH_MAIN -I. -ldl -lm -Wl,-export-dynamic -DUSE_SND=0
* repl
* (load "libadd1.so" (inlet 'init_func 'add1_init))
* (add1 2)
*/
Bignum support depends on gmp, mpfr, and mpc. In this example, we define "add-1" which adds 1 to any kind of number. The s7_big_* functions return the underlying gmp/mpfr/mpc pointer.
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <gmp.h>
#include <mpfr.h>
#include <mpc.h>
#include "s7.h"
static s7_pointer big_add_1(s7_scheme *sc, s7_pointer args)
{
/* add 1 to either a normal number or a bignum */
s7_pointer x, n;
x = s7_car(args);
if (s7_is_big_integer(x))
{
mpz_t big_n;
mpz_init_set(big_n, *s7_big_integer(x));
mpz_add_ui(big_n, big_n, 1);
n = s7_make_big_integer(sc, &big_n);
mpz_clear(big_n);
return(n);
}
if (s7_is_big_ratio(x))
{
mpq_t big_q;
mpq_init(big_q);
mpq_set_si(big_q, 1, 1);
mpq_add(big_q, *s7_big_ratio(x), big_q);
mpq_canonicalize(big_q);
n = s7_make_big_ratio(sc, &big_q);
mpq_clear(big_q);
return(n);
}
if (s7_is_big_real(x))
{
mpfr_t big_x;
mpfr_init_set(big_x, *s7_big_real(x), MPFR_RNDN);
mpfr_add_ui(big_x, big_x, 1, MPFR_RNDN);
n = s7_make_big_real(sc, &big_x);
mpfr_clear(big_x);
return(n);
}
if (s7_is_big_complex(x))
{
mpc_t big_z;
mpc_init2(big_z, mpc_get_prec(*s7_big_complex(x)));
mpc_add_ui(big_z, *s7_big_complex(x), 1, MPC_RNDNN);
n = s7_make_big_complex(sc, &big_z);
mpc_clear(big_z);
return(n);
}
if (s7_is_integer(x))
return(s7_make_integer(sc, 1 + s7_integer(x)));
if (s7_is_rational(x))
return(s7_make_ratio(sc, s7_numerator(x) + s7_denominator(x), s7_denominator(x)));
if (s7_is_real(x))
return(s7_make_real(sc, 1.0 + s7_real(x)));
if (s7_is_complex(x))
return(s7_make_complex(sc, 1.0 + s7_real_part(x), s7_imag_part(x)));
return(s7_wrong_type_arg_error(sc, "add-1", 0, x, "a number"));
}
int main(int argc, char **argv)
{
s7_scheme *s7;
char buffer[512];
char response[1024];
s7 = s7_init();
s7_define_function(s7, "add-1", big_add_1, 1, 0, false, "(add-1 num) adds 1 to num");
while (1)
{
fprintf(stdout, "\n> ");
fgets(buffer, 512, stdin);
if ((buffer[0] != '\n') ||
(strlen(buffer) > 1))
{
snprintf(response, 1024, "(write %s)", buffer);
s7_eval_c_string(s7, response);
}
}
}
/*
* gcc -DWITH_GMP=1 -c s7.c -I. -O2 -g3
* gcc -DWITH_GMP=1 -o gmpex gmpex.c s7.o -I. -O2 -lm -ldl -lgmp -lmpfr -lmpc
*
* gmpex
* > (add-1 1)
* 2
* > (add-1 2/3)
* 5/3
* > (add-1 1.4)
* 2.4
* > (add-1 1.5+i)
* 2.5+1i
* > (add-1 (bignum 3))
* 4
* > (add-1 (bignum 3/4))
* 7/4
* > (add-1 (bignum 2.5))
* 3.500E0
* > (add-1 (bignum 1.5+i))
* 2.500E0+1.000E0i
*/
To tie mpfr's bessel-j0 into s7 at run-time:
/* libgmp_s7.c */
#include <gmp.h>
#include <mpfr.h>
#include <mpc.h>
#define WITH_GMP 1
#include "s7.h"
static s7_pointer gmp_bessel_j0(s7_scheme *sc, s7_pointer args)
{
s7_pointer x, result;
mpfr_t mp;
mpfr_init2(mp, s7_integer(s7_let_field_ref(sc, s7_make_symbol(sc, "bignum-precision"))));
/* initialize the mpfr variable mp to the current s7 bignum-precision */
x = s7_car(args);
if (s7_is_big_real(x))
mpfr_j0(mp, *s7_big_real(x), MPFR_RNDN);
else
{
if (s7_is_real(x))
{
mpfr_set_d(mp, s7_real(x), MPFR_RNDN);
mpfr_j0(mp, mp, MPFR_RNDN);
}
else return(s7_wrong_type_arg_error(sc, "gmp_bessel_j0", 1, x, "real"));
}
result = s7_make_big_real(sc, &mp);
mpfr_clear(mp);
return(result);
}
void libgmp_s7_init(s7_scheme *sc);
void libgmp_s7_init(s7_scheme *sc)
{
s7_define_function(sc, "bessel-j0", gmp_bessel_j0, 1, 0, false, "(bessel-j0 x) returns j0(x)");
}
libarb_s7.c provides some extensions of the multiprecision math: Bessel functions and the like. It is based on the Flint and Arb libraries, flintlib.org and arblib.org. In Linux:
gcc -fPIC -c libarb_s7.c gcc libarb_s7.o -shared -o libarb_s7.so -lflint -larb repl > (load "libarb_s7.so" (inlet 'init_func 'libarb_s7_init)) #f > (acb_bessel_j 0 1.0) 7.651976865579665514497175261026632209096E-1
gdbinit has some debugging commands, intended for your ~/.gdbinit file.
s7print interprets its argument as an s7 value and displays it s7eval evals its argument (a string) s7stack displays the current s7 stack (nested lets) s7value prints the value of the variable passed by its print name: s7v "*features*" s7let shows all non-global variables that are currently accessible s7history shows the history entries (if enabled)
gdbinit also has two backtrace decoders: s7bt and s7btfull. The bt replacements print the gdb backtrace info, replacing bare pointer numbers with their s7 value, wherever possible:
(gdb) s7bt
#0 0x000055555567f7ca in check_cell (p=#<lambda (lst ind)>,
func=0x5555559106e0 <__FUNCTION__.10273> "mark_slot", line=3976) at s7.c:28494
#1 0x000055555567f84d in check_nref (p=#<lambda (lst ind)>,
func=0x5555559106e0 <__FUNCTION__.10273> "mark_slot", line=3976) at s7.c:28507
#2 0x0000555555563201 in mark_slot (p='list-ref #<lambda (lst ind)>) at s7.c:3976
#3 0x0000555555564ce0 in mark_let (env=#<mock-number-class>) at s7.c:4506
#4 0x0000555555563239 in mark_slot (p='mock-number-class #<mock-number-class>) at s7.c:3976
#5 0x0000555555564ce0 in mark_let (env=(inlet 'mock-number-class #<mock-number-class> 'mock-number mock-number)) at s7.c:4506
#6 0x0000555555563239 in mark_slot (p='*mock-number* (inlet 'mock-number-class #<mock-number-class> 'mock-number...)) at s7.c:3976
#7 0x0000555555564ce0 in mark_let (env=(inlet '*features* (mockery.scm stuff.scm linux autoload dlopen...))) at s7.c:4506
#8 0x0000555555565697 in mark_closure (p=reactive-vector) at s7.c:4590
#9 0x0000555555566872 in mark_rootlet (sc=0x555555b41eb0) at s7.c:4813
#10 0x0000555555566a2f in gc (sc=0x555555b41eb0) at s7.c:4897
#11 0x000055555558e903 in copy_stack (sc=0x555555b41eb0, old_v=[sc->stack] #<stack>) at s7.c:9024
Most of the s7.h functions do little, if any, error checking. s7_car, for example, does not check that its argument is a pair. Partly this is a matter of speed; partly of simplicity. If we had elaborate error checks, we'd need some convention for passing error information back to the caller, and of course separate versions of each function for cases where all those checks are redundant. You can easily make your own C version of s7_car that includes error checks:
static s7_pointer my_car(s7_scheme *sc, s7_pointer lst)
{
if (s7_is_pair(lst))
return(s7_car(lst));
return(s7_wrong_type_arg_error(sc, "my_car", 0, "a pair"));
}
The s7.h error functions are:
s7_pointer s7_error(s7_scheme *sc, s7_pointer type, s7_pointer info); s7_pointer s7_wrong_type_arg_error(s7_scheme *sc, const char *caller, s7_int arg_n, s7_pointer arg, const char *descr); s7_pointer s7_out_of_range_error(s7_scheme *sc, const char *caller, s7_int arg_n, s7_pointer arg, const char *descr); s7_pointer s7_wrong_number_of_args_error(s7_scheme *sc, const char *caller, s7_pointer args); s7_pointer s7_current_error_port(s7_scheme *sc); s7_pointer s7_set_current_error_port(s7_scheme *sc, s7_pointer port);
s7_error is equivalent to the scheme error function, and like the latter, it takes two arguments:
a symbol giving the error type, and a list giving the error data. In s7, all of the data lists
are organized so that you can (apply format #f data) to get an error string.
If you're using catch to handle errors, the error type is what catch looks for. So, the
s7_wrong_type_arg call above could be:
s7_error(sc, s7_make_symbol(sc, "wrong-type-arg"),
s7_list(sc, 3, s7_make_string(sc, "~S is a ~S, but should be a pair"),
s7_car(lst),
s7_type_of(sc, s7_car(lst))));
s7_wrong_type_arg_error takes the name of the caller, the argument number, the argument itself, and a description of the type expected. If the argument number is 0, that info is left out of the error message (that is, the caller takes only one argument). s7_out_of_range_error is similar. s7_wrong_number_of_args_error takes the caller's name and the offending arg list. The corresponding error types are 'wrong-type-arg, 'wrong-number-of-args, and 'out-of-range.
Normally, s7_error sends its error message to the current error-port which defaults to stderr. In GUI-based apps, you may need to redirect the output to your interface. One method, used in Snd's snd-motif.c, captures the error output in an output string:
old_port = s7_set_current_error_port(s7, s7_open_output_string(s7)); ... result = s7_eval_c_string(s7, text); errmsg = s7_get_output_string(s7, s7_current_error_port(s7)); s7_close_output_port(s7, s7_current_error_port(s7)); s7_set_current_error_port(s7, old_port); ...
and if errmsg is not NULL, it posts it somewhere. (You'll also want to GC-protect the old port while it is idle). If you don't want catch or s7's error messages, you can go down a level via *error-hook*.
s7_error does not return; its s7_pointer return type is just a convenience. It unwinds the scheme stack, closing files, handling dynamic-winds, looking for a catch that matches its type argument and so on, then longjmps to unwind the C stack. If a catch is found, its error handler becomes the new point of execution.
If you save an s7_pointer value in C, you may need to protect it from the garbage collector. In the example above, the first "..." is:
gc_loc = s7_gc_protect(s7, old_port);
where gc_loc is (or should be) an s7_int. Since we're subsequently calling s7_eval_c_string, we need to GC protect old_port beforehand. After the evaluation,
s7_close_output_port(s7, s7_current_error_port(s7)); s7_set_current_error_port(s7, old_port); s7_gc_unprotect_at(s7, gc_loc);
The full set of GC protection functions is:
s7_int s7_gc_protect(s7_scheme *sc, s7_pointer x); void s7_gc_unprotect_at(s7_scheme *sc, s7_int loc); s7_pointer s7_gc_protected_at(s7_scheme *sc, s7_int loc); s7_pointer s7_gc_protect_via_stack(s7_scheme *sc, s7_pointer x); s7_pointer s7_gc_unprotect_via_stack(s7_scheme *sc, s7_pointer x); s7_pointer s7_gc_protect_via_location(s7_scheme *sc, s7_pointer x, s7_int loc); s7_pointer s7_gc_unprotect_via_location(s7_scheme *sc, s7_int loc); s7_pointer s7_gc_on(s7_scheme *sc, bool on);
If you create an s7 object in C, that object needs to be GC protected if there is any chance the GC might run without an existing Scheme-level reference to it. s7_gc_protect places the object in a vector that the GC always checks, returning the object's location in that table. s7_gc_unprotect_at unprotects the object (removes it from the vector) using the location passed to it. s7_gc_protected_at returns the object at the given location. There is a built-in lag between the creation of a new object and its first possible GC (the lag time is set indirectly by GC_TEMPS_SIZE in s7.c), so you don't need to worry about very short term temps such as the arguments to s7_cons in:
s7_cons(s7, s7_make_real(s7, 3.14),
s7_cons(s7, s7_make_integer(s7, 123), s7_nil(s7)));
The protect_via_stack functions place the object on the s7 stack where it is protected until the stack unwinds past that point. Besides speed, this provides a way to be sure an object is unprotected even in some complicated situation where error handling may bypass an explicit s7_gc_unprotect_at call. The protect_via_location are intended for cases where you have a location already (from s7_gc_protect), and want to reuse it for a different object. s7_gc_on turns the GC on or off. Objects can be created at a blistering pace, so don't leave the GC off for a long time!
s7_pointer s7_load(s7_scheme *sc, const char *file); s7_pointer s7_load_with_environment(s7_scheme *sc, const char *filename, s7_pointer e); s7_pointer s7_load_c_string(s7_scheme *sc, const char *content, s7_int bytes); s7_pointer s7_load_c_string_with_environment(s7_scheme *sc, const char *content, s7_int bytes, s7_pointer e); s7_pointer s7_load_path(s7_scheme *sc); s7_pointer s7_add_to_load_path(s7_scheme *sc, const char *dir); s7_pointer s7_autoload(s7_scheme *sc, s7_pointer symbol, s7_pointer file_or_function); void s7_autoload_set_names(s7_scheme *sc, const char **names, s7_int size); snd-xref.c
s7_load is similar to the scheme-side load function. Its argument is a file name, and optionally (via s7_load_with_environment) an environment in which to place top-level objects. Normally the file contains scheme code, but if WITH_C_LOADER is set when s7 is built, you can also load shared-object files. If you load a shared-object file (a dynamically loadable library), the environment argument provides a way to pass in the initialization function (named 'init_func). For example, the repl in s7.c needs access to libc's tcsetattr, so it looks for libc_s7.so (created by libc.scm). If found,
s7_load_with_environment(sc, "libc_s7.so",
s7_inlet(sc, s7_list(sc, 2, s7_make_symbol(sc, "init_func"),
s7_make_symbol(sc, "libc_s7_init")));
You can also include an 'init_args field to pass arguments to init_func. Here's an example that includes init_args:
/* tlib.c */
#include <stdio.h>
#include <stdlib.h>
#include "s7.h"
static s7_pointer a_function(s7_scheme *sc, s7_pointer args)
{
return(s7_car(args));
}
s7_pointer tlib_init(s7_scheme *sc, s7_pointer args); /* void tlib_init(s7_scheme *sc) if no init_args */
s7_pointer tlib_init(s7_scheme *sc, s7_pointer args)
{
fprintf(stderr, "tlib_init: %s\n", s7_object_to_c_string(sc, args));
s7_define_function(sc, "a-function", a_function, 1, 0, true, "");
return(s7_car(args));
}
/* in Linux:
gcc -fPIC -c tlib.c
gcc tlib.o -shared -o tlib.so -ldl -lm -Wl,-export-dynamic
/home/bil/cl/ repl
<1> (load "tlib.so" (inlet 'init_func 'tlib_init 'init_args (list 1 2 3)))
tlib_init: (1 2 3)
1
<2> (a-function 1 2 3)
1
*/
s7_load returns the last value produced during the load; so given "test.scm" with the contents:
define (f x) (+ x 1)) 32
when we call s7_load:
s7_pointer val; val = s7_load_with_environment(sc, "test.scm", s7_curlet(sc));
val is set to 32 (as a scheme object), and f is placed in the current environment. If "test.scm" is not in the current directory, s7 looks at the entries in its *load-path* variable, trying each in turn until it finds the file. If it fails, it returns NULL. s7_load_path returns this list, and s7_add_to_load_path adds a directory name to the list.
s7_load_c_string takes an array of bytes representing some scheme code (xxd -i file.scm can generate these arrays), and treats it as if it were the contents of a file of scheme code. So, unlike s7_eval_c_string, it can handle multiple statements, and things like double-quote don't need to be quoted. nrepl.c for example embeds the contents of nrepl.scm at compile time, then calls s7_load_c_string at program startup. It also includes notcurses_s7.c. The end result is a stand-alone program that doesn't need to load either nrepl.scm or notcurses_s7.so. The "content" argument should be a null-terminated C string. The "bytes" argument is the contents length, not including the trailing null, as in strlen. There are simple examples in ffitest.c.
xxd is not ideal in this context because diffs become enormous. I use this code to turn nrepl.scm into nrepl-bits.h, following the original code's layout to minimize diffs:
(call-with-output-file "nrepl-bits.h" (lambda (op) (call-with-input-file "nrepl.scm" (lambda (ip) (format op "unsigned char nrepl_scm[] = {~% ") (do ((c (read-char ip) (read-char ip)) (i 0 (+ i 1))) ((eof-object? c) (format op "0};~%unsigned int nrepl_scm_len = ~D;~%" (+ i 1))) (format op "0x~X, " (char->integer c)) (if (char=? c #\newline) (format op "~% ")))))))Then in nrepl.c:
#include "nrepl-bits.h" s7_load_c_string(sc, (const char *)nrepl_scm, nrepl_scm_len);which replaces
s7_load(sc, "nrepl.scm").
s7_autoload adds a symbol to the autoload table. As a convenience, s7_autoload_set_names adds an array of names+files. The array should be sorted alphabetically by string<? acting on the symbol names (not the file names), and the size argument is the number of symbol names (half the actual array size). snd-xref.c in Snd has more than 5000 such names:
static const char *snd_names[11848] = {
"*clm-array-print-length*", "ws.scm", /* each pair of entries is entity name + file name */
"*clm-channels*", "ws.scm", /* so clm-channels is defined in ws.scm */
...
"zone-tailed-hawk", "animals.scm",
"zoom-spectrum", "examp.scm",
};
s7_autoload_set_names(sc, snd_names, 5924);
s7_pointer s7_eval(s7_scheme *sc, s7_pointer code, s7_pointer e); s7_pointer s7_eval_c_string(s7_scheme *sc, const char *str); s7_pointer s7_eval_c_string_with_environment(s7_scheme *sc, const char *str, s7_pointer e); s7_pointer s7_apply_function(s7_scheme *sc, s7_pointer fnc, s7_pointer args); s7_pointer s7_apply_function_star(s7_scheme *sc, s7_pointer fnc, s7_pointer args); s7_pointer s7_call(s7_scheme *sc, s7_pointer func, s7_pointer args); s7_pointer s7_call_with_location(s7_scheme *sc, s7_pointer func, s7_pointer args, const char *caller, const char *file, s7_int line); s7_pointer s7_call_with_catch(s7_scheme *sc, s7_pointer tag, s7_pointer body, s7_pointer error_handler); s7_pointer s7_apply_1(s7_scheme *sc, s7_pointer args, s7_pointer (*f1)(s7_pointer a1)); s7_pointer s7_apply_n_1(s7_scheme *sc, s7_pointer args, s7_pointer (*f1)(s7_pointer a1)); /* and many more passing 2 to 9 arguments */
These functions evaluate Scheme expressions, and call Scheme functions (which might be defined in C originally). s7_eval evaluates a list that represents Scheme code. That is,
s7_eval(sc, s7_cons(sc, s7_make_symbol(sc, "+"),
s7_cons(sc, s7_make_integer(sc, 1),
s7_cons(sc, s7_make_integer(sc, 2), s7_nil(sc)))),
s7_rootlet(sc)); /* s7_nil here is the same as s7_rootlet */
returns 3 (as a Scheme integer). This may look ridiculous, but see snd-sig.c for an actual use. s7_eval_c_string evaluates a Scheme expression presented to it as a C string; it combines read and eval, whereas s7_eval is just the eval portion.
s7_eval_c_string(sc, "(+ 1 2)");
also returns 3. The expression is evaluated in rootlet (the global environment). To specify the environment, use s7_eval_c_string_with_environment.
s7_apply_function and s7_apply_function_star take an s7_function and apply it to a list of arguments. These two functions are the low-level versions of the s7_call functions. The latter set up various catches so that error handling is safe, whereas s7_apply_function assumes you have a catch already somewhere.
s7_call_with_location passes some information to the error handler, and s7_call_with_catch wraps an explicit catch around a function call: s7_call_with_catch(sc, tag, body, err) is equivalent to (catch tag body err). There are many examples of these functions in clm2xen.c, ffitest.c, etc.
The s7_apply_1 functions and its many friends are left over from long ago. I hope to deprecate them someday, but currently Snd uses them to excess. Each applies its function to the arguments.
void s7_define(s7_scheme *sc, s7_pointer env, s7_pointer symbol, s7_pointer value);
bool s7_is_defined(s7_scheme *sc, const char *name);
s7_pointer s7_define_variable(s7_scheme *sc, const char *name, s7_pointer value);
s7_pointer s7_define_variable_with_documentation(s7_scheme *sc, const char *name, s7_pointer value, const char *help);
s7_pointer s7_define_constant(s7_scheme *sc, const char *name, s7_pointer value);
s7_pointer s7_define_constant_with_documentation(s7_scheme *sc, const char *name, s7_pointer value, const char *help);
s7_pointer s7_define_constant_with_environment(s7_scheme *sc, s7_pointer envir, const char *name, s7_pointer value);
s7_pointer s7_define_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg, const char *doc);
s7_pointer s7_define_safe_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg, const char *doc);
s7_pointer s7_define_typed_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg,
const char *doc, s7_pointer signature);
s7_pointer s7_define_unsafe_typed_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg,
const char *doc, s7_pointer signature);
s7_pointer s7_define_semisafe_typed_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg,
const char *doc, s7_pointer signature);
void s7_define_function_star(s7_scheme *sc, const char *name, s7_function fnc,
const char *arglist, const char *doc);
void s7_define_safe_function_star(s7_scheme *sc, const char *name, s7_function fnc,
const char *arglist, const char *doc);
void s7_define_typed_function_star(s7_scheme *sc, const char *name, s7_function fnc,
const char *arglist, const char *doc, s7_pointer signature);
s7_pointer s7_define_macro(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg, const char *doc);
s7_pointer s7_make_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg, const char *doc);
s7_pointer s7_make_safe_function(s7_scheme *sc, const char *name, s7_function fnc,
s7_int required_args, s7_int optional_args, bool rest_arg, const char *doc);
s7_pointer s7_make_typed_function(s7_scheme *sc, const char *name, s7_function f,
s7_int required_args, s7_int optional_args, bool rest_arg,
const char *doc, s7_pointer signature);
s7_pointer s7_make_function_star(s7_scheme *sc, const char *name, s7_function fnc,
const char *arglist, const char *doc);
s7_pointer s7_make_safe_function_star(s7_scheme *sc, const char *name, s7_function fnc,
const char *arglist, const char *doc);
bool s7_is_dilambda(s7_pointer obj);
s7_pointer s7_dilambda(s7_scheme *sc,
const char *name,
s7_pointer (*getter)(s7_scheme *sc, s7_pointer args),
s7_int get_req_args, s7_int get_opt_args,
s7_pointer (*setter)(s7_scheme *sc, s7_pointer args),
s7_int set_req_args, s7_int set_opt_args,
const char *documentation);
s7_pointer s7_typed_dilambda(s7_scheme *sc,
const char *name,
s7_pointer (*getter)(s7_scheme *sc, s7_pointer args),
s7_int get_req_args, s7_int get_opt_args,
s7_pointer (*setter)(s7_scheme *sc, s7_pointer args),
s7_int set_req_args, s7_int set_opt_args,
const char *documentation,
s7_pointer get_sig, s7_pointer set_sig);
s7_pointer s7_dilambda_with_environment(s7_scheme *sc, s7_pointer envir,
const char *name,
s7_pointer (*getter)(s7_scheme *sc, s7_pointer args),
s7_int get_req_args, s7_int get_opt_args,
s7_pointer (*setter)(s7_scheme *sc, s7_pointer args),
s7_int set_req_args, s7_int set_opt_args,
const char *documentation);
The s7_define* functions add a symbol and its binding to either the top-level (global) environment or, in s7_define, the 'env' passed as the second argument. Use s7_set_shadow_rootlet to import the current let into rootlet.
s7_define(s7, s7_curlet(s7), s7_make_symbol(s7, "var"), s7_make_integer(s7, 123));
adds the variable named var to the current environment with the value 123.
Scheme code can then refer to var just as if we had said (define var 123)
in Scheme.
s7_define_variable is a wrapper for s7_define; the code above could be:
s7_define_variable(s7, "var", s7_make_integer(s7, 123)); /* (define var 123) */
except that s7_define_variable assumes you want var in rootlet.
s7_define_constant is another wrapper for s7_define; it makes the variable immutable:
s7_define_constant(sc, "var", s7_f(sc)); /* (define-constant var 123) */
The rest of the functions in this section deal with tieing C functions into Scheme.
s7_make_function creates a Scheme function object from the s7_function 'fnc'.
An s7_function is a C function of the form s7_pointer func(s7_scheme *sc, s7_pointer args).
The new function's name is 'name', it requires 'required_args' arguments,
it can accept 'optional_args' other arguments, and if 'rest_arg' is true, it accepts
a "rest" argument (a list of all the trailing arguments).
The function's documentation is 'doc'.
s7_define_function is the same as s7_make_function, but it also adds 'name' (as a symbol) to the global environment, with the function as its value. For example, the Scheme function 'car' is essentially:
s7_pointer g_car(s7_scheme *sc, s7_pointer args) {return(s7_car(s7_car(args)));} /* args is a list of args */
It is bound to the name "car":
s7_define_function(sc, "car", g_car, 1, 0, false, "(car obj)");
which says that car has one required argument, no optional arguments, and no "rest" argument.
s7_define_macro defines a Scheme macro; its arguments are not evaluated (unlike a function), but its returned value (assumed to be some sort of Scheme expression) is evaluated.
The "safe" and "unsafe" versions of these functions refer to the s7 optimizer. If it knows a function is safe, it can more thoroughly optimize the expression it is in. "Safe" here means the function does not call the evaluator itself (via s7_apply_function for example) and does not mess with s7's stack.
The "typed" versions refer to the function's signature. Since "car" is safe, and has a signature, it is defined in s7.c:
s7_define_typed_function(sc, "car", g_car, 1, 0, false, H_car, Q_car);
Here unless you use s7_define_unsafe_typed_function, the function is assumed to be safe.
We've given it the Scheme name "car", which invokes the C function g_car. It takes one
required argument, and no optional or rest arguments. Its documentation is H_car, and
its signature is Q_car. The latter is s7_make_signature(sc, 2, sc->T, sc->is_pair_symbol)
which says that car takes a pair argument, and returns any type object.
The function_star functions are similar, but in this case we pass the argument list as a string, as it would appear in Scheme. s7 makes sure the arguments are ordered correctly and have the specified defaults before calling the C function.
s7_define_function_star(sc, "a-func", a_func, "arg1 (arg2 32)", "an example of C define*");
Now in Scheme, (a-func :arg1 2) calls the C function a_func with the arguments 2 and 32.
Finally, the dilambda function define Scheme dilambda, just as the Scheme dilambda function does. The dax example above gives read/write access to its x field via:
s7_define_variable(s7, "dax-x", s7_dilambda(s7, "dax-x", dax_x, 1, 0, set_dax_x, 2, 0, "dax x field"));
const char *s7_documentation(s7_scheme *sc, s7_pointer p); const char *s7_set_documentation(s7_scheme *sc, s7_pointer symbol, const char *new_doc); const char *s7_help(s7_scheme *sc, s7_pointer obj); s7_pointer s7_arity(s7_scheme *sc, s7_pointer obj); bool s7_is_aritable(s7_scheme *sc, s7_pointer obj, s7_int args); s7_pointer s7_setter(s7_scheme *sc, s7_pointer obj); s7_pointer s7_set_setter(s7_scheme *sc, s7_pointer obj, s7_pointer setter); s7_pointer s7_signature(s7_scheme *sc, s7_pointer func); s7_pointer s7_make_signature(s7_scheme *sc, s7_int len, ...); s7_pointer s7_make_circular_signature(s7_scheme *sc, s7_int cycle_point, s7_int len, ...); s7_pointer s7_closure_body(s7_scheme *sc, s7_pointer p); s7_pointer s7_closure_let(s7_scheme *sc, s7_pointer p); s7_pointer s7_closure_args(s7_scheme *sc, s7_pointer p); s7_pointer s7_funclet(s7_scheme *sc, s7_pointer p);
These functions pertain mostly to functions, both those defined in Scheme and those in C. s7_help and s7_documentation return the documentation string associated with their argument. I find "documentation" tedious to type, and Snd uses "help", but other than the name, there isn't much difference between them. s7_set_documentation sets the documentation string, if it can.
s7_arity returns an object's arity, a cons of the number of required arguments, and the total acceptable arguments. s7_is_aritable returns true if the object can accept that number of args.
s7_setter is the object's setter, and s7_set_setter sets it, if possible.
s7_signature is the object's signature, a list of types (symbols like 'integer?) giving return and argument types. For a function defined in C, s7_make_signature and s7_make_circular_signature create the signature that is then associated with the function via s7_define_typed_function and its friends. In s7.c g_is_zero (the function that implements zero?) uses:
s7_make_signature(sc, 2, sc->is_boolean_symbol, sc->is_number_symbol); /* return a boolean, argument is a number */
Similarly, g_add is:
s7_make_circular_signature(sc, 0, 1, sc->is_number_symbol); /* returns a number, takes any number of numbers */
The two numeric arguments set the cycle start point (0-based) and the number of type symbols passed as arguments to it. So, char=? is:
s7_make_circular_signature(sc, 1, 2, sc->is_boolean_symbol, sc->is_char_symbol);
which says there are two type entries (the "2"), and the cycle starts at the second (the "1" -- it's 0-based).
The s7_closure functions only apply to functions defined in Scheme. They return the closure body (s7_closure_body, a list),
its definition environment (s7_closure_let), and its argument list (s7_closure_args). If the function is of the form
(define (f . args) ...), s7_closure_args returns the symbol ('args in this case).
s7_funclet returns the top let within the function (the let containing the argument names).
bool s7_is_c_object(s7_pointer p); s7_pointer s7_make_c_object(s7_scheme *sc, s7_int type, void *value); s7_pointer s7_make_c_object_without_gc(s7_scheme *sc, s7_int type, void *value); s7_pointer s7_make_c_object_with_let(s7_scheme *sc, s7_int type, void *value, s7_pointer let); s7_int s7_c_object_type(s7_pointer obj); void *s7_c_object_value(s7_pointer obj); void *s7_c_object_value_checked(s7_pointer obj, s7_int type); s7_pointer s7_c_object_let(s7_pointer obj); s7_pointer s7_c_object_set_let(s7_scheme *sc, s7_pointer obj, s7_pointer e); s7_int s7_make_c_type(s7_scheme *sc, const char *name); void s7_c_type_set_gc_free (s7_scheme *sc, s7_int type, s7_pointer (*gc_free) (s7_scheme *sc, s7_pointer obj)); void s7_c_type_set_gc_mark (s7_scheme *sc, s7_int type, s7_pointer (*mark) (s7_scheme *sc, s7_pointer obj)); void s7_c_type_set_is_equal (s7_scheme *sc, s7_int type, s7_pointer (*is_equal) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_is_equivalent(s7_scheme *sc, s7_int type, s7_pointer (*is_equivalent)(s7_scheme *sc, s7_pointer args)); void s7_c_type_set_ref (s7_scheme *sc, s7_int type, s7_pointer (*ref) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_set (s7_scheme *sc, s7_int type, s7_pointer (*set) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_length (s7_scheme *sc, s7_int type, s7_pointer (*length) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_copy (s7_scheme *sc, s7_int type, s7_pointer (*copy) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_fill (s7_scheme *sc, s7_int type, s7_pointer (*fill) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_reverse (s7_scheme *sc, s7_int type, s7_pointer (*reverse) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_to_list (s7_scheme *sc, s7_int type, s7_pointer (*to_list) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_to_string (s7_scheme *sc, s7_int type, s7_pointer (*to_string) (s7_scheme *sc, s7_pointer args)); void s7_c_type_set_getter (s7_scheme *sc, s7_int type, s7_pointer getter); void s7_c_type_set_setter (s7_scheme *sc, s7_int type, s7_pointer setter); void s7_mark(s7_pointer p);
These functions create a new Scheme object type. See dax above for a simple example, and s7test.scm for several progressively more complicated examples. C-objects in Scheme usually correspond to an instance of a struct in C which you want to access from Scheme. The normal sequence is: define a new c-type via s7_make_c_type, call s7_c_type_set* to specialize its behavior, then to wrap a C object, call s7_make_c_object. s7_make_c_type takes an arbitrary name, used in object->string to identify the object, and returns an s7_int, the "type" mentioned in many of the other functions.
s7_c_type_set_free sets the function that is called by the GC when a Scheme c-object is garbage-collected. You normally use this to free the associated C value (the instance of the struct). To get that value, call s7_c_object_value. It returns the void* pointer that you originally passed to s7_make_c_object. See free_dax in the dax example.
s7_c_type_set_mark sets the function that is called by the GC during its marking phase. Any s7_pointer value local to your C struct should be marked explicitly at this time, or the GC will free it. Use s7_mark for this (see mark_dax).
s7_c_type_set_equal and s7_c_type_set_equivalent set the function called when s7 sees a c-object of the current type as an argument to equal? or equivalent?. When called, these functions can assume that the first argument is a c-object of the current type, but the second argument can be anything (see dax_is_equal).
s7_c_type_set_ref and s7_c_type_set_set are called when the c-object is treated as an applicable object
in Scheme. That is, (object ...) in Scheme calls the function set as the "ref" function, and
(set! (object ...) new-value) calls the "set" function. The arguments in the set! form are
passed as a flattened list.
The rest of the s7_c_type_set* functions set the functions called when the c-object is an argument to length (s7_c_type_set_length), copy (s7_c_type_set_copy), fill! (s7_c_type_set_fill), reverse (s7_c_type_set_reverse), object->string (s7_c_type_set_to_string), and internally by map and a few other cases, s7_c_type_set_to_list. For the copy function, either the first or second argument can be a c-object of the given type. The getter and setter functions are optimizer helpers.
s7_c_object_value_checked is like s7_c_object, but it first checks that the object type matches the given type.
s7_c_object_let and s7_c_object_set_let manage the c-object's local environment. These two functions need to check that they are passed the correct number of arguments. See the block object in s7test.scm. The c_object_let provides methods normally. In Snd, marks can be passed into Scheme; the setup code is:
static s7_pointer g_mark_methods;
...
g_mark_methods = s7_openlet(s7,
s7_inlet(s7, s7_list(s7, 2, s7_make_symbol(s7, "object->let"),
mark_to_let_func)));
s7_gc_protect(s7, g_mark_methods);
xen_mark_tag = s7_make_c_type(s7, "<mark>");
s7_c_type_set_gc_free(s7, xen_mark_tag, s7_xen_mark_free);
s7_c_type_set_is_equal(s7, xen_mark_tag, s7_xen_mark_is_equal);
s7_c_type_set_copy(s7, xen_mark_tag, s7_xen_mark_copy);
s7_c_type_set_to_string(s7, xen_mark_tag, g_xen_mark_to_string);
The mark object's let (g_mark_methods) has a method for object->let. It is tied into each mark object:
s7_pointer m; m = s7_make_c_object(s7, xen_mark_tag, mx); /* mx is the C-side value */ s7_c_object_set_let(s7, m, g_mark_methods);
and now if you type (object->let mark) in Snd's listener (where "mark" is an appropriate mark of course), object->let calls the object's object->let method. Don't forget to GC-protect the let!
s7_make_c_object_without_gc makes a c-object of the given type, but the gc_free function won't be called when the s7_cell that holds the C data is freed for reuse.
bool s7_is_input_port(s7_scheme *sc, s7_pointer p);
bool s7_is_output_port(s7_scheme *sc, s7_pointer p);
void s7_close_input_port(s7_scheme *sc, s7_pointer p);
void s7_close_output_port(s7_scheme *sc, s7_pointer p);
bool s7_flush_output_port(s7_scheme *sc, s7_pointer p); /* false=flush lost data */
const char *s7_port_filename(s7_scheme *sc, s7_pointer x);
s7_int s7_port_line_number(s7_scheme *sc, s7_pointer p);
s7_pointer s7_open_input_file(s7_scheme *sc, const char *name, const char *mode);
s7_pointer s7_open_output_file(s7_scheme *sc, const char *name, const char *mode);
s7_pointer s7_open_input_string(s7_scheme *sc, const char *input_string);
s7_pointer s7_open_output_string(s7_scheme *sc);
const char *s7_get_output_string(s7_scheme *sc, s7_pointer out_port);
s7_pointer s7_output_string(s7_scheme *sc, s7_pointer out_port);
typedef enum {S7_READ, S7_READ_CHAR, S7_READ_LINE, S7_PEEK_CHAR, S7_IS_CHAR_READY, S7_NUM_READ_CHOICES} s7_read_t;
s7_pointer s7_open_output_function(s7_scheme *sc, void (*function)(s7_scheme *sc, uint8_t c, s7_pointer port));
s7_pointer s7_open_input_function(s7_scheme *sc, s7_pointer (*function)(s7_scheme *sc, s7_read_t read_choice, s7_pointer port));
s7_pointer s7_read_char(s7_scheme *sc, s7_pointer port);
s7_pointer s7_peek_char(s7_scheme *sc, s7_pointer port);
s7_pointer s7_write_char(s7_scheme *sc, s7_pointer c, s7_pointer port);
s7_pointer s7_write(s7_scheme *sc, s7_pointer obj, s7_pointer port);
s7_pointer s7_display(s7_scheme *sc, s7_pointer obj, s7_pointer port);
void s7_newline(s7_scheme *sc, s7_pointer port);
const char *s7_format(s7_scheme *sc, s7_pointer args);
s7_pointer s7_object_to_string(s7_scheme *sc, s7_pointer arg, bool use_write);
char *s7_object_to_c_string(s7_scheme *sc, s7_pointer obj);
s7_pointer s7_current_input_port(s7_scheme *sc);
s7_pointer s7_set_current_input_port(s7_scheme *sc, s7_pointer p);
s7_pointer s7_current_output_port(s7_scheme *sc);
s7_pointer s7_set_current_output_port(s7_scheme *sc, s7_pointer p);
s7_pointer s7_current_error_port(s7_scheme *sc);
s7_pointer s7_set_current_error_port(s7_scheme *sc, s7_pointer port);
s7_pointer s7_read(s7_scheme *sc, s7_pointer port);
Most of these correspond closely to the similarly named scheme function. s7_port_filename returns the file associated with a file port. s7_port_line_number returns position of the reader in an input file port. The "use_write" parameter to s7_object_to_string refers to the write/display choice in scheme. The string returned by s7_object_to_c_string should be freed by the caller. s7_output_string is the same as s7_get_output_string except that it returns an s7 string, not a C string.
s7_open_input_function and s7_open_output_function call their "function" argument when input or output is requested. The "read_choice" argument specifies to that function which of the input scheme functions called it. The intent of these two input functions is to give you complete control over IO. In the case of an input_function:
static s7_pointer my_read(s7_scheme *sc, s7_read_t peek, s7_pointer port)
{
/* this function should handle input according to the peek choice */
return(s7_make_character(sc, '0'));
}
s7_pointer port;
s7_int gc_loc;
uint8_t c;
port = s7_open_input_function(sc, my_read);
gc_loc = s7_gc_protect(sc, port);
c = s7_character(s7_read_char(sc, p1)); /* my_read "peek" == S7_READ_CHAR */
if (last_c != '0')
fprintf(stderr, "c: %c\n", c);
s7_gc_unprotect_at(sc, gc_loc);
s7_pointer s7_rootlet(s7_scheme *sc); s7_pointer s7_shadow_rootlet(s7_scheme *sc); s7_pointer s7_set_shadow_rootlet(s7_scheme *sc, s7_pointer let); s7_pointer s7_curlet(s7_scheme *sc); s7_pointer s7_set_curlet(s7_scheme *sc, s7_pointer e); s7_pointer s7_outlet(s7_scheme *sc, s7_pointer e); s7_pointer s7_sublet(s7_scheme *sc, s7_pointer let, s7_pointer bindings); s7_pointer s7_inlet(s7_scheme *sc, s7_pointer bindings); s7_pointer s7_varlet(s7_scheme *sc, s7_pointer let, s7_pointer symbol, s7_pointer value); s7_pointer s7_let_to_list(s7_scheme *sc, s7_pointer let); bool s7_is_let(s7_pointer e); s7_pointer s7_let_ref(s7_scheme *sc, s7_pointer let, s7_pointer symbol); s7_pointer s7_let_set(s7_scheme *sc, s7_pointer let, s7_pointer symbol, s7_pointer val); s7_pointer s7_let_field_ref(s7_scheme *sc, s7_pointer symbol); s7_pointer s7_let_field_set(s7_scheme *sc, s7_pointer symbol, s7_pointer new_value); s7_pointer s7_openlet(s7_scheme *sc, s7_pointer e); bool s7_is_openlet(s7_pointer e); s7_pointer s7_method(s7_scheme *sc, s7_pointer object, s7_pointer method); /* these might go away someday */ s7_pointer s7_slot(s7_scheme *sc, s7_pointer symbol); s7_pointer s7_slot_value(s7_pointer slot); s7_pointer s7_slot_set_value(s7_scheme *sc, s7_pointer slot, s7_pointer value); s7_pointer s7_make_slot(s7_scheme *sc, s7_pointer env, s7_pointer symbol, s7_pointer value); void s7_slot_set_real_value(s7_scheme *sc, s7_pointer slot, s7_double value);
Many of these are the same as the corresponding scheme function: s7_rootlet, s7_curlet, s7_outlet, s7_sublet, s7_inlet, s7_varlet, s7_let_to_list, s7_is_let, s7_let_ref, s7_let_set, s7_openlet, and s7_is_openlet.
s7_let_field_ref and s7_let_field_set refer to *s7*, the let that holds various s7 settings. To get the current default print-length,
s7_integer(s7_let_field_ref(s7, s7_make_symbol(s7, "print-length")))
s7_method looks for a field in "object" with the name "method", a symbol. For example, in clm2xen.c, if mus-copy is called on an object that Snd does not immediately recognize (i.e. a generator), it looks for a mus-copy method, and if found, Snd calls it:
s7_pointer func; func = s7_method(s7, gen, s7_make_symbol(s7, "mus-copy")); if (func != s7_undefined(s7)) return(s7_apply_function(s7, func, s7_list(s7, 1, gen)));
The object searched can be anything that has an associated let: a c-object, a function or macro, a c-pointer, or of course a let.
s7_set_curlet and the slot functions might go away someday. They are currently used in Snd. For the adventurous however, here's a sketchy description. A slot in s7 is a location in a let (a variable binding in an environment to use more standard terminology). s7_make_slot creates a slot in "env" with the given symbol and value. s7_slot_value returns the value; s7_slot_set_value sets the value; s7_slot_set_real_value sets the mutable real value's numerical value. s7_slot takes a symbol and tries to find its currently active slot. s7_set_curlet sets curlet, returning the previous curlet.
s7_shadow_rootlet and s7_set_shadow_rootlet make it easier to import a let into rootlet. This is also aimed at code that is defining lots of functions and variables, using the default functions like s7_define_variable that place things in the rootlet, but the code actually wants all those objects stored in a let other than rootlet.
s7_pointer cur_env, old_shadow; cur_env = s7_curlet(sc); old_shadow = s7_set_shadow_rootlet(sc, cur_env); /* define everything here */ s7_set_shadow_rootlet(sc, old_shadow);
s7_set_shadow_rootlet returns the previous shadow rootlet, so this turns the current environment into a shadow rootlet while defining functions, then restores the old rootlet. Similarly notcurses_s7.c places everything in the *notcurses* let, but uses s7_set_shadow_rootlet to make these available in scheme as if they were in the rootlet:
s7_pointer notcurses_let, old_shadow; s7_define_constant(sc, "*notcurses*", notcurses_let = s7_inlet(sc, s7_nil(sc))); old_shadow = s7_set_shadow_rootlet(sc, notcurses_let); /* ... here we have all the s7_defines ... */ s7_set_shadow_rootlet(sc, old_shadow);
bool s7_is_symbol(s7_pointer p); const char *s7_symbol_name(s7_pointer p); s7_pointer s7_make_symbol(s7_scheme *sc, const char *name); s7_pointer s7_gensym(s7_scheme *sc, const char *prefix); bool s7_is_keyword(s7_pointer obj); s7_pointer s7_make_keyword(s7_scheme *sc, const char *key); s7_pointer s7_keyword_to_symbol(s7_scheme *sc, s7_pointer key); s7_pointer s7_name_to_value(s7_scheme *sc, const char *name); s7_pointer s7_symbol_value(s7_scheme *sc, s7_pointer sym); s7_pointer s7_symbol_set_value(s7_scheme *sc, s7_pointer sym, s7_pointer val); s7_pointer s7_symbol_local_value(s7_scheme *sc, s7_pointer sym, s7_pointer local_env); s7_pointer s7_symbol_table_find_name(s7_scheme *sc, const char *name); bool s7_for_each_symbol_name(s7_scheme *sc, bool (*symbol_func)(const char *symbol_name, void *data), void *data); bool s7_for_each_symbol(s7_scheme *sc, bool (*symbol_func)(const char *symbol_name, void *data), void *data);
s7_is_symbol corresponds to scheme's symbol?, s7_symbol_name to symbol->string, s7_make_symbol is string->symbol, s7_gensym to gensym. The gensym prefix is the optional argument to gensym in scheme. By default the prefix is "gensym", so the gensym-created symbols are of the form {gensym}-nnn where nnn is some number. s7_is_keyword is keyword?, s7_make_keyword is string->keyword, and s7_keyword_to_symbol is keyword->symbol.
Normal symbols, and keywords do not need to be garbage-protected, but gensyms do.
s7_symbol_to_value finds the current binding of the symbol (using its string name), and returns its value, similar to symbol->value. To specify the environment in which to lookup the symbol, use s7_symbol_local_value. s7_symbol_set_value sets the value of the symbol in its current binding.
s7_symbol_table_find_name finds the symbol given its name. s7_make_symbol is the same if the symbol already exists, but s7_symbol_find_by_name returns NULL if there isn't any symbol by that name. s7_for_each_symbol_name and s7_for_each_symbol traverse the symbol table, calling "symbol_func" on each symbol. symbol_func is a boolean function that takes as arguments the symbol name and the void* data pointer. The latter can carry along whatever state your function needs. s7_for_each_symbol_name also includes some s7 constants like #f.
The C declaration above says s7_for_each_symbol is a C function that returns a boolean, and takes three arguments, an s7_scheme* pointer, a function (symbol_func), and a void* pointer (data). The function passed (symbol_func) also returns a boolean, and takes two arguments, a char* (name), and the same void* pointer that was passed to s7_symbol_for_each. If symbol_func returns true, the outer function immediately returns true, ending the symbol table traversal. Sketched in scheme, it might be:
(define (s7_for_each_symbol s7 symbol_func data)
(call-with-exit
(lambda (return)
(for-each
(lambda (symbol-name)
(if (symbol_func symbol-name data)
(return #t)))
(symbol-table))
#f)))
An example is snd-completion.c.
bool s7_is_number(s7_pointer p); char *s7_number_to_string(s7_scheme *sc, s7_pointer obj, s7_int radix); bool s7_is_integer(s7_pointer p); s7_int s7_integer(s7_pointer p); s7_pointer s7_make_integer(s7_scheme *sc, s7_int num); s7_int s7_number_to_integer(s7_scheme *sc, s7_pointer x); s7_int s7_number_to_integer_with_caller(s7_scheme *sc, s7_pointer x, const char *caller); bool s7_is_real(s7_pointer p); s7_double s7_real(s7_pointer p); s7_pointer s7_make_real(s7_scheme *sc, s7_double num); s7_pointer s7_make_mutable_real(s7_scheme *sc, s7_double n); s7_double s7_number_to_real(s7_scheme *sc, s7_pointer x); s7_double s7_number_to_real_with_caller(s7_scheme *sc, s7_pointer x, const char *caller); bool s7_is_rational(s7_pointer arg); bool s7_is_ratio(s7_pointer arg); s7_pointer s7_make_ratio(s7_scheme *sc, s7_int a, s7_int b); s7_pointer s7_rationalize(s7_scheme *sc, s7_double x, s7_double error); s7_int s7_numerator(s7_pointer x); s7_int s7_denominator(s7_pointer x); bool s7_is_complex(s7_pointer arg); s7_pointer s7_make_complex(s7_scheme *sc, s7_double a, s7_double b); s7_double s7_real_part(s7_pointer z); s7_double s7_imag_part(s7_pointer z); s7_double s7_random(s7_scheme *sc, s7_pointer state); s7_pointer s7_random_state(s7_scheme *sc, s7_pointer seed); bool s7_is_random_state(s7_pointer p); s7_pointer s7_random_state_to_list(s7_scheme *sc, s7_pointer args); void s7_set_default_random_state(s7_scheme *sc, s7_int seed, s7_int carry); bool s7_is_bignum(s7_pointer obj); mpfr_t *s7_big_real(s7_pointer x); mpz_t *s7_big_integer(s7_pointer x); mpq_t *s7_big_ratio(s7_pointer x); mpc_t *s7_big_complex(s7_pointer x); s7_pointer s7_make_big_integer(s7_scheme *sc, mpz_t *val); s7_pointer s7_make_big_ratio(s7_scheme *sc, mpq_t *val); s7_pointer s7_make_big_real(s7_scheme *sc, mpfr_t *val); s7_pointer s7_make_big_complex(s7_scheme *sc, mpc_t *val);
Most of these correspond to the obvious scheme functions, so I'll only touch on the less-obvious cases. s7_make_mutable_real returns a real number object whose value can be changed directly. In snd-sig.c, for example, we have a C procedure that applies a scheme function to every sound sample in an audio file. We do not want to create a new object for the scheme function's argument list on every call! So, we start by creating the mutable real:
yp = s7_make_slot(s7, e, arg, s7_make_mutable_real(s7, 1.5));
"e" is the let for the evaluation, "arg" is the real's name as a symbol in that let, and we make its initial value 1.5 (for no particular reason). Then on every sample, we call the function:
s7_slot_set_real_value(s7, yp, data[kp]); /* set yp's value to data[kp] */ data[kp] = opt_func(s7, res); /* call opt_func */
s7_number_to_real returns any real number as an s7_double. If it can't convert its argument, it signals an error, which is annoying because it doesn't know where that error occured in scheme. So s7_number_to_real_with_caller gives you a way to tell it at lease the caller's name.
For the bignum functions, see Bignums in C.
bool s7_is_pair(s7_pointer p); s7_pointer s7_cons(s7_scheme *sc, s7_pointer a, s7_pointer b); s7_pointer s7_car(s7_pointer p); s7_pointer s7_cdr(s7_pointer p); s7_pointer s7_set_car(s7_pointer p, s7_pointer q); s7_pointer s7_set_cdr(s7_pointer p, s7_pointer q); s7_pointer s7_cadr(s7_pointer p); etc... bool s7_is_list(s7_scheme *sc, s7_pointer p); bool s7_is_proper_list(s7_scheme *sc, s7_pointer p); s7_pointer s7_make_list(s7_scheme *sc, s7_int length, s7_pointer initial_value); s7_int s7_list_length(s7_scheme *sc, s7_pointer a); s7_pointer s7_list(s7_scheme *sc, s7_int num_values, ...); s7_pointer s7_list_nl(s7_scheme *sc, s7_int num_values, ...); s7_pointer s7_array_to_list(s7_scheme *sc, s7_int num_values, s7_pointer *array); s7_pointer s7_list_ref(s7_scheme *sc, s7_pointer lst, s7_int num); s7_pointer s7_list_set(s7_scheme *sc, s7_pointer lst, s7_int num, s7_pointer val); s7_pointer s7_reverse(s7_scheme *sc, s7_pointer a); s7_pointer s7_append(s7_scheme *sc, s7_pointer a, s7_pointer b); s7_pointer s7_assoc(s7_scheme *sc, s7_pointer obj, s7_pointer lst); s7_pointer s7_assq(s7_scheme *sc, s7_pointer obj, s7_pointer x); s7_pointer s7_member(s7_scheme *sc, s7_pointer obj, s7_pointer lst); s7_pointer s7_memq(s7_scheme *sc, s7_pointer obj, s7_pointer x); bool s7_tree_memq(s7_scheme *sc, s7_pointer sym, s7_pointer tree);
These functions are mostly obvious: s7_car corresponds to scheme car, etc. s7_list_nl was added to catch a typo that affected s7_list: the latter would accept trailing, but ignored list values. s7_tree_memq is like s7_memq, but searches an entire tree structure. not just the top-level list. s7_array_to_list takes an array of s7_pointers and returns a list of them (similar to s7_vector_to_list).
s7_pointer s7_make_vector(s7_scheme *sc, s7_int len); s7_pointer s7_make_and_fill_vector(s7_scheme *sc, s7_int len, s7_pointer fill); s7_pointer s7_make_normal_vector(s7_scheme *sc, s7_int len, s7_int dims, s7_int *dim_info); bool s7_is_vector(s7_pointer p); s7_int s7_vector_length(s7_pointer vec); s7_int s7_vector_rank(s7_pointer vect); s7_int s7_vector_dimension(s7_pointer vec, s7_int dim); s7_pointer *s7_vector_elements(s7_pointer vec); s7_int s7_vector_dimensions(s7_pointer vec, s7_int *dims, s7_int dims_size); s7_int s7_vector_offsets(s7_pointer vec, s7_int *offs, s7_int offs_size); void s7_vector_fill(s7_scheme *sc, s7_pointer vec, s7_pointer obj); s7_pointer s7_vector_copy(s7_scheme *sc, s7_pointer old_vect); s7_pointer s7_vector_to_list(s7_scheme *sc, s7_pointer vect); s7_pointer s7_make_int_vector(s7_scheme *sc, s7_int len, s7_int dims, s7_int *dim_info); s7_int *s7_int_vector_elements(s7_pointer vec); bool s7_is_int_vector(s7_pointer p); s7_int s7_int_vector_ref(s7_pointer vec, s7_int index); s7_int s7_int_vector_set(s7_pointer vec, s7_int index, s7_int value); s7_pointer s7_make_float_vector(s7_scheme *sc, s7_int len, s7_int dims, s7_int *dim_info); s7_pointer s7_make_float_vector_wrapper(s7_scheme *sc, s7_int len, s7_double *data, s7_int dims, s7_int *dim_info, bool free_data); s7_double *s7_float_vector_elements(s7_pointer vec); bool s7_is_float_vector(s7_pointer p); s7_double s7_float_vector_ref(s7_pointer vec, s7_int index); s7_double s7_float_vector_set(s7_pointer vec, s7_int index, s7_double value); s7_pointer s7_vector_ref(s7_scheme *sc, s7_pointer vec, s7_int index); s7_pointer s7_vector_set(s7_scheme *sc, s7_pointer vec, s7_int index, s7_pointer a); s7_pointer s7_vector_ref_n(s7_scheme *sc, s7_pointer vector, s7_int indices, ...); s7_pointer s7_vector_set_n(s7_scheme *sc, s7_pointer vector, s7_pointer value, s7_int indices, ...);
s7_make_vector returns a one-dimensional vector of the given length; its elements are initialized to the empty list, (). s7_make_and_fill_vector is similar, but the initial element is set by the "fill" parameter. This value is simply placed in every vector location, not copied, so if you pass a cons, then change its car, that change is reflected in every element of the vector. s7_make_normal_vector returns a possibly multidimensional inhomogenous vector (a "normal" vector, as opposed to an int-vector or a float-vector).
s7_is_vector is the same as vector?, s7_vector_length is length. s7_vector_rank returns the number of dimensions in a vector, and s7_vector_dimension returns the size of the given dimension. s7_vector_elements returns the s7_pointer array that holds that vector's elements. s7_vector_dimensions fills "dims" with the lengths of the corresponding dimensions. s7_vector_offsets does the same for the successive dimensional offsets. In a multidimensional vector, you can get the s7_vector_elements index by summing each index * offset[dimension]. s7_vector_to_list is vector->list. s7_vector_fill is fill! (as applied to a vector of course), and s7_vector_copy is copy.
s7_make_int_vector returns an int-vector. Its elements are s7_ints (int64_t), and the array of s7_ints can be accessed via s7_int_vector_elements. Similarly for float-vectors (the elements are s7_doubles which are C doubles). s7_make_float_vector_wrapper provides a way to pass a C array of doubles through scheme; it wraps up the array as a scheme float-vector. Both s7_make_int_vector and s7_make_float_vector can return multidimensional vectors. The "dims" parameter specifies the number of dimensions, and the "dim_info" parameter the individual dimensions. If dims is 1, dim_info can be NULL. If the s7_make_float_vector_wrapper "free_data" parameter is true, s7 will free the "data" array when the float-vector is garbage-collected. In ffitest.c, the g_block example calls:
v1 = s7_make_float_vector_wrapper(sc, len, g1->data, 1, NULL, false);
when checking if two blocks are equivalent. Since this data is actually being shared with a block object, we don't want s7 to free it when the g_blocks_are_equivalent function is done. g1->data is freed by g_block_free when the c-object is garbage collected.
s7_vector_ref and s7_vector_set apply to one-dimensional vectors; the "_n" cases apply to multidimensional cases. All four functions can be used on any type of vector.
bool s7_is_c_pointer(s7_pointer arg); bool s7_is_c_pointer_of_type(s7_pointer arg, s7_pointer type); void *s7_c_pointer(s7_pointer p); void *s7_c_pointer_with_type(s7_scheme *sc, s7_pointer p, s7_pointer expected_type, const char *caller, s7_int argnum); s7_pointer s7_make_c_pointer(s7_scheme *sc, void *ptr); s7_pointer s7_make_c_pointer_with_type(s7_scheme *sc, void *ptr, s7_pointer type, s7_pointer info); s7_pointer s7_c_pointer_type(s7_pointer p);
These functions are equivalent to s7's c-pointer?, c-pointer, and c-pointer-type. C-pointers in s7 are aimed primarily at passing uninterpreted C pointers through s7 from one C function to another. The "type" field can hold a type indication, useful in debugging. s7_c_pointer_of_type checks that the c-pointer's type field matches the type passed as the second argument. As a convenience, s7_c_pointer_with_type combines s7_c_pointer with s7_is_c_pointer_of_type, calling s7_error if the types don't match. Nothing else in s7 assumes the type field is actually a type symbol, so you can use the type and info fields for any purpose.
bool s7_is_string(s7_pointer p); const char *s7_string(s7_pointer p); s7_pointer s7_make_string(s7_scheme *sc, const char *str); s7_pointer s7_make_string_with_length(s7_scheme *sc, const char *str, s7_int len); s7_pointer s7_make_string_wrapper(s7_scheme *sc, const char *str); s7_pointer s7_make_permanent_string(s7_scheme *sc, const char *str); s7_int s7_string_length(s7_pointer str);
These handle s7 strings. s7_is_string corresponds to scheme's string?, and s7_string_length to scheme's string-length. s7_string returns the scheme string's value as a C string. Don't free the returned string! s7_make_string takes a C string, and returns its scheme equivalent. s7_make_string_with_length is the same, but it is faster because you pass the new string's length (s7_make_string has to use strlen). s7_make_permanent_string returns a scheme string that is not in the heap; it will never be GC'd. s7_make_string_wrapper creates a temporary string. This saves the overhead of getting a free cell from the heap and later GC-ing it, but the string may be reused at any time. It is useful as an argument to s7_call and similar functions where you know no other strings will be needed during that call.
bool s7_is_character(s7_pointer p); uint8_t s7_character(s7_pointer p); s7_pointer s7_make_character(s7_scheme *sc, uint8_t c);
s7_is_character is equivalent to character?. s7_character returns the unsigned char held by the s7 object p, and s7_make_character returns an s7 object holding the unsigned char c.
bool s7_is_hash_table(s7_pointer p); s7_pointer s7_make_hash_table(s7_scheme *sc, s7_int size); s7_pointer s7_hash_table_ref(s7_scheme *sc, s7_pointer table, s7_pointer key); s7_pointer s7_hash_table_set(s7_scheme *sc, s7_pointer table, s7_pointer key, s7_pointer value);
These functions are the C-side equivalent of hash-table?, make-hash-table, hash-table-ref, and hash-table-set!.
s7_pointer s7_make_iterator(s7_scheme *sc, s7_pointer e); bool s7_is_iterator(s7_pointer obj); bool s7_iterator_is_at_end(s7_scheme *sc, s7_pointer iter); s7_pointer s7_iterate(s7_scheme *sc, s7_pointer iter);
These are the C equivalents of make-iterator, iterator?, iterator-at-end?, and iterate.
s7_pointer s7_hook_functions(s7_scheme *sc, s7_pointer hook); s7_pointer s7_hook_set_functions(s7_scheme *sc, s7_pointer hook, s7_pointer functions);
These access the list of functions associated with a hook. See hooks for a discussion of hooks, and C and Scheme Hooks for a short example. The scheme equivalent is hook-functions (a dilambda).
s7_pointer s7_f(s7_scheme *sc); s7_pointer s7_t(s7_scheme *sc); s7_pointer s7_nil(s7_scheme *sc); s7_pointer s7_undefined(s7_scheme *sc); s7_pointer s7_unspecified(s7_scheme *sc); s7_pointer s7_eof_object(s7_scheme *sc); bool s7_is_unspecified(s7_scheme *sc, s7_pointer val); bool s7_is_null(s7_scheme *sc, s7_pointer p); bool s7_is_boolean(s7_pointer x); bool s7_boolean(s7_scheme *sc, s7_pointer x); s7_pointer s7_make_boolean(s7_scheme *sc, bool x); bool s7_is_immutable(s7_pointer p); s7_pointer s7_immutable(s7_pointer p);
These return the standard scheme or s7 constants: #f, #t, (), #<undefined>, #<unspecified>, and #<eof>. Also the s7 function unspecified?, and the scheme functions null?, and boolean?. s7_make_boolean returns #t or #f depending on its argument.
s7_immutable makes its argument immutable, and s7_is_immutable returns true if its argument is immutable. They parallel s7's immutable! and immutable?.
typedef s7_double (*s7_d_t)(void); void s7_set_d_function(s7_scheme *sc, s7_pointer f, s7_d_t df); s7_d_t s7_d_function(s7_pointer f); etc...
These functions tell s7 to call a foreign function directly, without any scheme-related overhead. The function to be called in this manner needs to take the form of one of the s7_*_t functions in s7.h. For example, one way to call + is to pass it two s7_double arguments and get an s7_double back. This is the s7_d_dd_t function (the first letter gives the return type, the rest give successive argument types, d=double, i=integer, v=c_object, p=s7_pointer). We tell s7 about it via s7_set_d_dd_function. Whenever s7's optimizer encounters + with two arguments that it (the optimizer) knows are s7_doubles, in a context where an s7_double result is expected, s7 calls the associated s7_d_dd_t function directly without preparing a list of arguments, and without wrapping up the result as an s7 object.
Here is an example of using these functions; more extensive examples are in clm2xen.c in sndlib, and in s7.c.
static s7_pointer g_plus_one(s7_scheme *sc, s7_pointer args)
{
return(s7_make_integer(sc, s7_integer(s7_car(args)) + 1));
}
static s7_int plus_one(s7_int x) {return(x + 1);}
s7_define_safe_function(sc, "plus1", g_plus_one, 1, 0, false, "");
s7_set_i_i_function(sc, s7_name_to_value(sc, "plus1"), plus_one);
s7_define_safe_function defines a Scheme function "plus1", telling the optimizer that this function is safe. A safe function does not push anything on the s7 stack, and treats the arglist passed to it as immutable and temporary (that is, it just grabs the arguments from the list). A few s7_* functions are unsafe, and that makes anything that calls them also unsafe. If the optimizer knows a function is safe, it can use prebuilt lists to pass the arguments (saving in the GC), and can combine it in various ways with other stuff. If an unsafe function handles its argument list safely, declare it with s7_define_semisafe_typed_function. If the safe function knows its return and argument types, there is another level of optimization that can call it without setting up an arglist or "unboxing" values, basically a direct call in C. In this example, the s7_set_i_i_function call tells the optimizer that if plus1 is seen in a context where the optimizer knows it is receiving an s7_int argument, and is expected to return an s7_int result, it can call plus_one directly, rather than g_plus_one.
There are more of these functions in s7.c that could be exported via s7.h if you need them.
By the way, to optimize scheme code (for speed), first use functions: the optimizer ignores anything else at the top level. Then perhaps check lint.scm and the profiler. Don't use something dumb like call/cc. Avoid append. Use iteration, not recursion. Perhaps take the hot spot and do it in C. callgrind might also be helpful, but it can be hard to map from callgrind output to the original scheme code.
s7_scheme *s7_init(void); void s7_quit(s7_scheme *sc); void s7_free(s7_scheme *sc); void s7_repl(s7_scheme *sc); bool s7_is_eq(s7_pointer a, s7_pointer b); bool s7_is_eqv(s7_scheme *sc, s7_pointer a, s7_pointer b); bool s7_is_equal(s7_scheme *sc, s7_pointer a, s7_pointer b); bool s7_is_equivalent(s7_scheme *sc, s7_pointer x, s7_pointer y); void s7_provide(s7_scheme *sc, const char *feature); bool s7_is_provided(s7_scheme *sc, const char *feature); s7_pointer s7_stacktrace(s7_scheme *sc); s7_pointer s7_history(s7_scheme *sc); s7_pointer s7_add_to_history(s7_scheme *sc, s7_pointer entry); bool s7_history_enabled(s7_scheme *sc); bool s7_set_history_enabled(s7_scheme *sc, bool enabled); s7_pointer s7_dynamic_wind(s7_scheme *sc, s7_pointer init, s7_pointer body, s7_pointer finish); s7_pointer s7_make_continuation(s7_scheme *sc); s7_pointer s7_values(s7_scheme *sc, s7_pointer args); s7_pointer s7_copy(s7_scheme *sc, s7_pointer args); s7_pointer s7_fill(s7_scheme *sc, s7_pointer args); s7_pointer s7_type_of(s7_scheme *sc, s7_pointer arg); s7_pfunc s7_optimize(s7_scheme *sc, s7_pointer expr); bool s7_is_syntax(s7_pointer p); bool s7_is_valid(s7_scheme *sc, s7_pointer arg); void (*s7_begin_hook(s7_scheme *sc))(s7_scheme *sc, bool *val); void s7_set_begin_hook(s7_scheme *sc, void (*hook)(s7_scheme *sc, bool *val));
s7_init creates a scheme interpreter. The returned value is the s7_scheme* used by many of the FFI functions. s7_quit exits the interpreter. The memory allocated for it by s7_init is not freed unless you call s7_free. (s7_free also frees its s7_scheme* argument). s7_repl fires up a REPL. s7_is_eq and friends correspond to scheme's eq?, eqv?, equal?, and equivalent?. s7_provide and s7_is_provided add a symbol to the *features* list, or check for its presence there.
s7_stacktrace is like stacktrace; it currently ignores (*s7* 'stacktrace). The s7_history functions deal with the (*s7* 'history) buffer. s7_dynamic_wind is dynamic-wind in C. The parameters "init", "body", and "finish" are the same as in scheme (i.e. #f or a thunk). s7_make_continuation is call/cc; there is an example above. s7_values is values, s7_copy is copy, s7_fill is fill!, s7_type_of is type-of, s7_is_syntax is syntax?.
s7_is_valid is a debugging aid; it tries to tell if an arbitrary value is pointing to an s7 object. Set the compile-time switch TRAP_SEGFAULT to 1 before using this function!
s7_optimize is the third-level optimizer. It is a bit hard to explain, but basically you pass it some scheme code, and it returns either NULL or a function that can be called to evaluate that code. There are several examples in snd-sig.c.
static s7_pointer g_d_func(s7_scheme *sc, s7_pointer args)
{
/* a normal C-defined s7 function that simply returns (scheme) 1.0 */
return(s7_make_real(sc, 1.0));
}
static s7_double opt_d_func(void)
{
/* a version of g_d_func that returns (C) 1.0 */
return(1.0);
}
/* now make it possible to call opt_d_func in place of g_d_func */
s7_float_function func;
s7_pointer symbol;
symbol = s7_define_safe_function(sc, "d-func", g_d_func, 0, 0, false, "opt func");
s7_set_d_function(sc, s7_name_to_value(sc, "d-func"), opt_d_func);
/* and try it (this saves creating an s7 real, accessing its value, and GC-ing it eventually) */
func = s7_float_optimize(sc, s7_list(sc, 1, s7_list(sc, 1, symbol)));
fprintf(stderr, "%f\n", func(sc));
Finally, the begin_hook functions are explained above.
The s7 tarball includes several scheme files:
libc.scm, libgsl.scm, libm.scm, libdl.scm, notcurses_s7.c, libutf8proc.scm, and libgdbm.scm tie the associated libraries into s7. gdbinit has some gdb commands for s7.
cload.scm defines the macro c-define that reduces the overhead involved in (dynamically) linking C entities into s7.
(c-define c-info (prefix "") (headers ()) (cflags "") (ldflags "") output-name)
For example, (c-define '(double j0 (double)) "m" "math.h")
links the C math library function j0 into s7 under the name m:j0,
passing it a double argument and getting a double result (a real in s7).
prefix is some arbitrary prefix that you want prepended to various names.
headers is a list of headers (as strings) that the c-info relies on, (("math.h") for example).
cflags are any special C compiler flags that are needed ("-I." in particular), and ldflags is the similar case for the loader. output-name is the name of the output C file and associated library. It defaults to "temp-s7-output" followed by a number. In libm.scm, it is set to "libm_s7" to protect it across cload calls. If cload finds an up-to-date output C file and shared library, it simply loads the library, rather than going through all the trouble of writing and compling it.
c-info is a list that describes the C entities that you want to load into s7. It can be either one list describing one entity, or a list of such lists. Each description has the form:
(return-type entity-name-in-C (argument-type...))
where each entry is a symbol, and C names are used throughout. So, in the j0
example above, (double j0 (double)) says we want access to j0, it returns
a C double, and it takes one argument, also a C double. s7 tries to figure out
what the corresponding s7 type is, but in tricky cases, you should tell it
by replacing the bare type name with a list: (C-type underlying-C-type). For example,
the Snd function set_graph_style takes an (enum) argument of type graph_style_t.
This is actually an int, so we use (graph_style_t int) as the type:
(void set_graph_style ((graph_style_t int)))
If the C entity is a constant, then the descriptor list has just two entries,
the C-type and the entity name: (int F_OK) for example. The entity name can also be a list:
((graph_style_t int) (GRAPH_LINES GRAPH_DOTS GRAPH_FILLED GRAPH_DOTS_AND_LINES GRAPH_LOLLIPOPS))
This defines all the names in the list as integers.
If the C type has a space ("struct tm*"), use (symbol "struct tm*")
to construct the corresponding symbol.
The entity is placed in the current s7 environment under the name (string-append prefix ":" name)
where the ":" is omitted if the prefix is null. So in the j0 example, we get in s7 the function m:j0.
c-define returns #t if it thinks the load worked, and #f otherwise.
There are times when the only straightforward approach is to write the desired C code directly. To insert C code on the fly, use (in-C "code..."). Two more such cases that come up all the time: C-function for linkage to functions written directly in s7 style using in-C, and C-macro for macros in the C header file that need to be wrapped in #ifdefs. Here are some examples:
;;; various math library functions
(c-define '((double j0 (double))
(double j1 (double))
(double erf (double))
(double erfc (double))
(double lgamma (double)))
"m" "math.h")
;;; getenv and setenv
(c-define '(char* getenv (char*)))
(c-define '(int setenv (char* char* int)))
;;; file-exists? and delete-file
(define file-exists? (let () ; define F_OK and access only within this let
(c-define '((int F_OK) (int access (char* int))) "" "unistd.h")
(lambda (arg) (= (access arg F_OK) 0))))
(define delete-file (let ()
(c-define '(int unlink (char*)) "" "unistd.h")
(lambda (file) (= (unlink file) 0)))) ; 0=success
;;; examples from Snd:
(c-define '(char* version_info ()) "" "snd.h" "-I.")
(c-define '(mus_float_t mus_degrees_to_radians (mus_float_t)) "" "snd.h" "-I.")
(c-define '(snd_info* any_selected_sound ()) "" "snd.h" "-I.")
(c-define '(void select_channel (snd_info* int)) "" "snd.h" "-I.")
(c-define '(((graph_style_t int) (GRAPH_LINES GRAPH_DOTS GRAPH_FILLED GRAPH_DOTS_AND_LINES GRAPH_LOLLIPOPS))
(void set_graph_style ((graph_style_t int))))
"" "snd.h" "-I.")
;;; getcwd, strftime
(c-define '(char* getcwd (char* size_t)) "" "unistd.h")
(c-define (list '(void* calloc (size_t size_t))
'(void free (void*))
'(void time (time_t*)) ; ignore returned value
(list (symbol "struct tm*") 'localtime '(time_t*))
(list 'size_t 'strftime (list 'char* 'size_t 'char* (symbol "struct tm*"))))
"" "time.h")
> (let ((p (calloc 1 8))
(str (make-string 32)))
(time p)
(strftime str 32 "%a %d-%b-%Y %H:%M %Z" (localtime p))
(free p)
str)
"Sat 11-Aug-2012 08:55 PDT\x00 "
;;; opendir, read_dir, closedir
(c-define '((int closedir (DIR*))
(DIR* opendir (char*))
(in-C "static char *read_dir(DIR *p) \
{ \
struct dirent *dirp; \
dirp = readdir(p); \
if (!dirp) return(NULL); \
return(dirp->d_name); \
}")
(char* read_dir (DIR*)))
"" '("sys/types.h" "dirent.h"))
C-init inserts its string argument into the initialization section of the module. In libgsl.scm, for example,
(C-init "gsl_set_error_handler(g_gsl_error);")
inserts that string (as C code) into libgsl_s7.c toward the beginning of the libgsl_s7_init function (line 42346 or so).
When compiling, for the simple cases above, include "-ldl -Wl,-export-dynamic" in the gcc command. So the first FFI example is built (this is in Linux):
gcc -c s7.c -I. gcc -o ex1 ex1.c s7.o -lm -I. -ldl -Wl,-export-dynamic ex1 > (load "cload.scm") c-define-1 > (c-define '(double j0 (double)) "m" "math.h") #t > (m:j0 0.5) 0.93846980724081
See also r7rs.scm, libc.scm, libgsl.scm, libm.scm, libdl.scm, and libgdbm.scm. libutf8proc.scm exists, but I have not tested it at all.
The default in the lib*.scm files is to use the C name as the Scheme name. This collides with (for example) the widespread use of "-", rather than "_" in Scheme, but I have found it much more straightforward to stick with one name. In cases like libgsl there are thousands of names, all documented at great length by the C name. Anyone who wants to use these functions has to start with the C name. If they are forced to fuss with some annoying Schemely translation of it, the only sane response is: "forget it! I'll do it in C".
(require libc.scm)
(define (copy-file in-file out-file)
(with-let (sublet *libc* :in-file in-file :out-file out-file)
;; the rest of the function body exists in the *libc* environment, with the
;; function parameters in-file and out-file imported, so, for example,
;; (open ...) below calls the libc function open.
(let ((infd (open in-file O_RDONLY 0)))
(if (= infd -1)
(error 'io-error "can't find ~S~%" in-file)
(let ((outfd (creat out-file #o666)))
(if (= outfd -1)
(begin
(close infd)
(error 'io-error "can't open ~S~%" out-file))
(let* ((BUF_SIZE 1024)
(buf (malloc BUF_SIZE)))
(do ((num (read infd buf BUF_SIZE) (read infd buf BUF_SIZE)))
((or (<= num 0)
(not (= (write outfd buf num) num)))))
(close outfd)
(close infd)
(free buf)
out-file)))))))
(define (glob->list pattern)
(with-let (sublet *libc* :pattern pattern)
(let ((g (glob.make)))
(glob pattern 0 g)
(let ((res (glob.gl_pathv g)))
(globfree g)
res))))
;; now (load "*.scm") is (for-each load (glob->list "*.scm"))
;; a couple regular expression examples
(with-let (sublet *libc*)
(define rg (regex.make))
(regcomp rg "a.b" 0)
(display (regexec rg "acb" 0 0)) (newline) ; 0 = match
(regfree rg))
(with-let (sublet *libc*)
(define rg (regex.make))
(let ((res (regcomp rg "colou\\?r" 0)))
(if (not (zero? res))
(error 'regex-error "~S: ~S~%" "colou\\?r" (regerror res rg)))
(set! res (regexec rg "The color green" 1 0))
(display res) (newline) ; #i(4 9) = match start/end
(regfree rg)))
(require libgsl.scm)
(define (eigenvalues M)
(with-let (sublet *libgsl* :M M)
(let* ((len (sqrt (length M)))
(gm (gsl_matrix_alloc len len))
(m (float-vector->gsl_matrix M gm))
(evl (gsl_vector_complex_alloc len))
(evc (gsl_matrix_complex_alloc len len))
(w (gsl_eigen_nonsymmv_alloc len)))
(gsl_eigen_nonsymmv m evl evc w)
(gsl_eigen_nonsymmv_free w)
(gsl_eigen_nonsymmv_sort evl evc GSL_EIGEN_SORT_ABS_DESC)
(let ((vals (make-vector len)))
(do ((i 0 (+ i 1)))
((= i len))
(set! (vals i) (gsl_vector_complex_get evl i)))
(gsl_matrix_free gm)
(gsl_vector_complex_free evl)
(gsl_matrix_complex_free evc)
vals))))
We can use gdbm (or better yet, mdb), the :readable argument to object->string, and the fallback methods in the environments to create name-spaces (lets) with billions of thread-safe local variables, which can be saved and communicated between s7 runs:
(require libgdbm.scm)
(with-let *libgdbm*
(define *db*
(openlet
(inlet :file (gdbm_open "test.gdbm" 1024 GDBM_NEWDB #o664
(lambda (str) (format *stderr* "gdbm error: ~S~%" str)))
:let-ref-fallback (lambda (obj sym)
(eval-string (gdbm_fetch (obj 'file) (symbol->string sym))))
:let-set-fallback (lambda (obj sym val)
(gdbm_store (obj 'file)
(symbol->string sym)
(object->string val :readable)
GDBM_REPLACE)
val)
:make-iterator (lambda (obj)
(let ((key #f)
(length (lambda (obj) (expt 2 20))))
(#_make-iterator
(let ((+iterator+ #t))
(openlet
(lambda ()
(if key
(set! key (gdbm_nextkey (obj 'file) (cdr key)))
(set! key (gdbm_firstkey (obj 'file))))
(if (pair? key)
(cons (string->symbol (car key))
(eval-string (gdbm_fetch (obj 'file) (car key))))
key))))))))))
(set! (*db* 'str) "123") ; add a variable named 'str with the value "123"
(set! (*db* 'int) 432)
(with-let *db*
(+ int (length str))) ; -> 435
(map values *db*) ; -> '((str . "123") (int . 432))
(gdbm_close (*db* 'file)))
case.scm has case*, a compatible extension of case that includes pattern matching.
(case* selector ((target...) body) ...) uses equivalent? to match the
selector to the targets, evaluating the body associated with the first matching target.
If a target is a list or vector, the elements are checked item by item.
Each target, or element of a list or vector can be a pattern. Patterns
are of the form #<whatever> (undefined constants from s7's pointer of view).
A pattern can be:
If a label occurs in the result body, the expression it labelled is substituted for it.
(case* x ((3.14) 'pi)) ; returns 'pi if x is 3.14
(case* x ((#<symbol?>))) ; returns #t if x is a symbol
(case* x (((+ 1 #<symbol?>)))) ; matches any list of the form '(+ 1 x) or any symbol in place of "x"
(case* x (((#<symbol?> #<e1:...> (+ #<e2:...>)))
(append #<e1> #<e2>))) ; passed '(a b c d (+ 1 2)), returns '(b c d 1 2)
(case* x ((#<"a.b">))) ; matches if x is a string "a.b" where "." matches anything
(define (palindrome? x)
(case* x
((() (#<>))
#t)
(((#<start:> #<middle:...> #<start>))
(palindrome? #<middle>))
(else #f)))
case*'s matching function can be used anywhere.
(let ((match? ((funclet 'case*) 'case*-match?))) ; this is case*'s matcher
(match? x '(+ #<symbol?> 1))) ; returns #t if x is of the form '(+ x 1), x any symbol
(define match+
(let ((match? ((funclet 'case*) 'case*-match?))
(labels ((funclet 'case*) 'case*-labels))) ; these are the labels and their values
(macro (arg)
(cond ((null? arg) ())
((match? arg '(+ #<a:> (+ #<b:...>))) `(+ ,(labels 'a) ,@(cadr (labels 'b))))
((match? arg '(+ #<> #<>)) `(+ ,@(cdr arg)))
(else #f)))))
;; (match+ (+ 1 (+ 2 3))) -> 6
See case.scm and s7test.scm for many more examples, including let and hash-table matching.
debug.scm has various debugging aids, including trace, break, watch, and a C-style stacktrace. The *s7* field 'debug controls when these are active, and to what extent.
(trace func) adds a tracepoint to the start of the function or macro func. (trace) adds such tracing to every subsequently defined function or macro. (untrace) turns off tracing; (untrace func) turns off tracing in func. Similarly (break func) places a breakpoint at the start of func, (unbreak func) removes it. (unbreak) removes all breakpoints. When a breakpoint is encountered, you are placed in a repl at that point; type C-q to continue. To trace a variable, use (watch var). watch reports whenever var is set! and (unwatch var) removes the watchpoint.
These trace, break and watchpoints are active only if (*s7* 'debug) is positive. If 'debug is 1, existing traces and breaks are active, but no new ones are added by s7. If 'debug is 2, s7 adds tracepoints to any subsequently defined (i.e. named) functions and macros. If (*s7* 'debug) is 3, unnamed functions are also traced. If any tracing is enabled, you can get a C-style stacktrace by setting (debug-stack) to a vector, then call (show-debug-stack) to see the calls.
Besides debug-stack, debug.scm also defines the convenience functions debug-function, debug-port, and debug-repl. debug-port is the debugger's output port, debug-repl drops into a repl at a breakpoint, and debug-function provides a way to customize the debugger's behavior. The function debug-frame provides a way to examine local variables.
> (define (g1 x) (+ x 1)) g1 > (trace g1) ; this loads debug.scm unless it's already loaded, and sets (*s7* 'debug) to 1 g1 > (procedure-source g1) ; you can add trace-in explicitly (rather than call trace) (lambda (x) (trace-in (curlet)) (+ x 1)) > (g1 2) (g1 2) ; file/line info is included if relevant -> 3 3 > (break g1) g1 > (g1 3) break: (g1 3), C-q to exit break break> x ; this is a repl started at the breakpoint 3 break> -> 4 ; C-q typed to exit the break 4 > (define var 1) 1 > (watch var) #<lambda (s v ...)> ; this is the new setter for 'var > (set! var 3) var set! to 3 3 > (define lt (inlet 'a 3)) (inlet 'a 3) > (watch (lt 'a)) #<lambda (s v ...)> > (set! (lt 'a) 12) let-set! a to 12 12
s7test.scm has more examples
lint tries to find errors or infelicities in your scheme code. To try it:
(load "lint.scm") (lint "some-code.scm")
There are several variables at the start of lint.scm to control additional output:
*report-unused-parameters* *report-unused-top-level-functions* *report-shadowed-variables* *report-undefined-identifiers* *report-multiply-defined-top-level-functions* *report-nested-if* *report-short-branch* *report-one-armed-if* *report-loaded-files* *report-any-!-as-setter* *report-doc-strings* *report-func-as-arg-arity-mismatch* *report-bad-variable-names* *report-built-in-functions-used-as-variables* *report-forward-functions* *report-sloppy-assoc* *report-bloated-arg* *report-clobbered-function-return-value* *report-boolean-functions-misbehaving* *report-repeated-code-fragments* *report-quasiquote-rewrites* *report-combinable-lets*
See lint.scm for more about these switches. You can also extend lint by adding your own code, or adding your functions to lint's tables, or most simply by defining signatures for your functions. snd-lint.scm performs these tasks for Snd. (lint exports its innards via *lint*). lint is not smart about functions defined outside the current file, so *report-undefined-variables* sometimes gets confused. You'll sometimes get a recommendation from lint that is less than helpful; nobody's perfect. If it's actually wrong, and not just wrong-headed, please let me know. Also in lint.scm are html-lint and C-lint. html-lint reads an HTML file looking for Scheme code. If any is found, it runs s7 and then lint over it, reporting troubles. Similarly C-lint reads a C file looking for s7_eval_c_string and running lint over its string.
There are three or four repls included with s7. repl.scm is a textual interface based on vt-100 codes, and nrepl.scm is an improvement of repl.scm based on the notcurses-core library. I'll treat repl.scm first, then discuss how nrepl differs from it.
repl.scm implements a repl using vt100 codes and libc.scm. It includes
symbol and filename completion, a history buffer, paren matching,
indentation, multi-line edits, and a debugger window.
To move around in the history buffer, use M-p, M-n or M-. (C-p and C-n are used to move the cursor in the current expression).
You can change the keymap or the prompt; all the repl functions are
accessible through the *repl* environment. One field is 'repl-let which
gives you access to all the repl's internal variables and functions.
Another is 'top-level-let, normally (sublet (rootlet)), which is the environment in
which the repl's evaluation takes place. You can reset the repl back to its
starting point with: (set! (*repl* 'top-level-let) (sublet (rootlet))).
You can save the current repl state via ((*repl* 'save-repl)), and
restore it later via ((*repl* 'restore-repl)). The repl's saved state
is in the file save.repl, or the filename can be passed as an argument to save-repl and restore-repl.
There is one annoying consequence of using (sublet (rootlet)) for the top-level let: if you define something in the repl, then load a file that expects to find that thing in rootlet, it won't:
<1> (define (func x) (+ x 1)) ; func is in (sublet (rootlet)) func <2> (load "use-func.scm") ; file contents: (display (func 3)) error: unbound variable func
To get around this, either load the file into curlet: (load "use-func.scm" (curlet)),
or use with-let to place the definition in rootlet: (with-let (curlet) (define (func x) (+ x 1))).
Meta keys are a problem on the Mac. You can use ESC instead, but that requires super-human capacities. I stared at replacement control keys, and nothing seemed right. If you can think of something, it's easy to define replacements: see repl.scm which has a small table of mappings.
To run the repl, either build s7 with the compiler flag -DWITH_MAIN, or conjure up a wrapper:
#include "s7.h"
int main(int argc, char **argv)
{
s7_scheme *sc;
sc = s7_init();
s7_load(sc, "repl.scm");
s7_eval_c_string(sc, "((*repl* 'run))");
return(0);
}
/* gcc -o r r.c s7.o -Wl,-export-dynamic -lm -I. -ldl
*/
Besides evaluating s7 expressions, like any repl, you can also type shell commands just as in a shell:
<1> pwd /home/bil/cl <2> cd .. /home/bil <3> date Wed 15-Apr-2015 17:32:24 PDT
In most cases, these are handled through *unbound-variable-hook*, checked using "command -v", then passed to the underlying shell via the system function.
The prompt is set by the function (*repl* 'prompt). It gets one argument, the current line number, and should set the prompt string and its length.
(set! (*repl* 'prompt) (lambda (num) (with-let (*repl* 'repl-let) (set! prompt-string "scheme> ") (set! prompt-length (length prompt-string)))))
or, to use the red lambda example mentioned earlier:
(set! (*repl* 'prompt)
(lambda (num)
(with-let (*repl* 'repl-let)
(set! prompt-string (bold (red (string #\xce #\xbb #\> #\space))))
(set! prompt-length 3)))) ; until we get unicode length calc
The line number provides a quick way to move around in the history buffer. To get a previous line without laboriously typing M-p over and over, simply type the line number (without control or meta bits), then M-. In some CL repls, the special variable '* holds the last value computed. In repl.scm, each value is retained in variables of the form '<n> where n is the number shown in the prompt.
<1> (+ 1 2) 3 <2> (* <1> 2) 6
Here is an example of adding to the keymap:
(set! ((*repl* 'keymap) (integer->char 17)) ; C-q to quit and return to caller
(lambda (c)
(set! ((*repl* 'repl-let) 'all-done) #t)))
To access the meta keys (in the keymap), use a string:
((*repl* 'keymap) (string #\escape #\p)); this is Meta-p which normally accesses
the history buffer.
You can call the repl from other code, poke around in the current environment (or whatever), then return to the caller:
(load "repl.scm")
(define (drop-into-repl e)
(let ((C-q (integer->char 17))) ; we'll use the C-q example above to get out
(let ((old-C-q ((*repl* 'keymap) C-q))
(old-top-level (*repl* 'top-level-let)))
(dynamic-wind
(lambda ()
(set! (*repl* 'top-level-let) e)
(set! ((*repl* 'keymap) C-q)
(lambda (c)
(set! ((*repl* 'repl-let) 'all-done) #t))))
(lambda ()
((*repl* 'run))) ; run the repl
(lambda ()
(set! (*repl* 'top-level-let) old-top-level)
(set! ((*repl* 'keymap) C-q) old-C-q))))))
(let ((x 32))
(format *stderr* "x: ~A~%" x)
(drop-into-repl (curlet))
(format *stderr* "now x: ~A~%" x))
Now load that code and:
x: 32 <1> x 32 <2> (set! x 91) 91 <3> x 91 <4> now x: 91 ; here I typed C-q at the prompt
Another possibility:
(set! (hook-functions *error-hook*)
(list (lambda (hook)
(apply format *stderr* (hook 'data))
(newline *stderr*)
(drop-into-repl (owlet)))))
See the end of repl.scm for more examples. See nrepl.scm for a better version of repl.scm. Eventually I'll probably retire repl.scm.
Unlike repl, nrepl has support for the mouse, traversable, scrollable, and resizable panes, built-in ties to lint.scm, debug.scm, and profile.scm, and various other enhancements. Since it includes all the libc, notcurses FFI code, and nrepl.scm at compile-time, there are no problems running it anywhere. To build nrepl:
gcc -o nrepl s7.c -O2 -I. -Wl,-export-dynamic -lm -ldl -DWITH_MAIN -DWITH_NOTCURSES -lnotcurses-core
If that is too easy, try:
gcc -c s7.c -O2 -I. -Wl,-export-dynamic -lm -ldl gcc -o nrepl nrepl.c s7.o -lnotcurses-core -lm -I. -ldl
notcurses_s7.c needs version 2.1.6 or later of the notcurses-core library.
When nrepl starts up, you have a prompt at the top of the terminal, and a status box at the bottom. You can move around the pane via C-p and C-n (no need for repl.scm's M-p and M-n), or use the mouse, or the arrow keys. If you set and hit a break point, a new pane is opened in the context of the break. C-q exits the break. At the top pane, C-q exits nrepl. C-g gives you another prompt (handy if you're caught in a messed up expression). If you're in an infinite loop, C-c interrupts it. Otherwise C-c exits nrepl.
If you set up a watcher (via watch from debug.scm), the action is displayed in a separate box in the upper right corner. The status box displays all sorts of informative and helpful messages, or at least that is the intent. lint.scm checks each expression you type, and various hooks let you know when things are happening in the background. Function signatures are posted there as well.
You can customize nrepl in basically the same ways as described above for repl.scm. You can also place these in a file named ".nrepl"; if nrepl finds such a file, it loads it automatically at startup.
After months of intense typing, Insanely declares his labors complete. "Ship it!" says Mr Big, and hands him a million stock options. Meanwhile, in the basement behind an old door with the eldritch sign "eep Ou", in a labyrinth of pounding pipes and fluorescent lights, a forgotten shadow types
(lint "insanely-great.scm")...