## s7

s7 is a Scheme implementation intended as an extension language for other applications, primarily Snd and Common Music. 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: ftp://ccrma-ftp.stanford.edu/pub/Lisp/s7.tar.gz.

s7 is the default extension language of Snd and sndlib (http://ccrma.stanford.edu/software/snd/), and Rick Taube's Common Music (commonmusic at sourceforge). There are X, Motif, Gtk, 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 (Snd for example), 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: 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!, 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).

- multiprecision arithmetic
- math functions
- define*
- define-macro
- define-constant, symbol-access
- make-type
- procedure-with-setter
- generalized set!
- multidimensional vectors
- hash tables
- hooks
- multiple-values
- call-with-exit
- format
- errors, stacktrace, trace
- procedure info
- environments
- eval
- string IO
- miscellanea
- the run macro
- FFI examples
  - read-eval-print loop (and emacs)
  - define a function with arguments and a returned value, and define a variable
  - call a Scheme function from C, and get/set Scheme variable values in C
  - C++ and Juce
  - load sndlib using the XEN functions and macros
  - add a new Scheme type and a procedure-with-setter
  - redirect display output to a C procedure
  - extend a built-in operator ("+" in this case)
  - C-side define* (s7_define_function_star)
  - C-side define-macro (s7_define_macro)
  - signal handling (C-C to break out of an infinite loop)
  - direct multidimensional vector element access
  - notification in C that a Scheme variable has been set!
  - Load C defined stuff into a separate namespace
  - Error handling in C
  - Closure defined in C
  - Hooks in C and Scheme
  - Load a C module dynamically
  - gmp and friends
  - Gtk-based REPL
  - Gtk/Scheme-based REPL
  - s7 running in a separate thread
  - begin_hook to the rescue!

#### multiprecision arithmetic

  All numeric types, integers, ratios, reals, and complex numbers are supported. The basic integer and real types are defined in s7.h, defaulting to long long int and double. pi is predefined, as are most-positive-fixnum and most-negative-fixnum. 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, bignum?, and bignum-precision. bignum-precision, which defaults to 128, sets the number of bits each float takes. pi automatically reflects the current bignum-precision:

      > pi
      3.141592653589793238462643383279502884195E0

      > (bignum-precision)
      128

      > (set! (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 a string representing the desired number:

      > (bignum "123456789123456789")
      123456789123456789

      > (bignum "1.123123123123123123123123123")
      1.12312312312312312312312312300000000009E0

  > 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 (- (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)))
  >     #f

  > and in the non-gmp case:

  >     > (= 1.0 (+ 1.0 (expt 2 -53)))
  >     #t
  >     > (= 1.0 (+ 1.0 (expt 2 -52)))
  >     #f

  > In the gmp case, integers and ratios are limited only by the size of memory, but reals are limited by bignum-precision. This means, for example, that

  >     > (floor 1e56) ; bignum-precision is 128
  >     99999999999999999999999999999999999999927942405962072064
  >     > (set! (bignum-precision) 256)
  >     256
  >     > (floor 1e56)
  >     100000000000000000000000000000000000000000000000000000000

  > The non-gmp case is similar, but it's easy to find the edge cases:

  >     > (floor (+ 0.9999999995 (expt 2.0 23)))
  >     8388609

#### math functions

  s7 includes:

  - sinh, cosh, tanh, asinh, acosh, atanh
  - logior, logxor, logand, lognot, ash, integer-length, integer-decode-float
  - random
  - nan?, infinite?

  The random function can take any numeric argument, including 0. The following constants are predefined: pi, most-positive-fixnum, most-negative-fixnum. Other math-related differences between s7 and r5rs:

  - rational? and exact mean integer or ratio (i.e. not floating point), inexact means not exact.
  - floor, ceiling, truncate, and round return (exact) integer results.
  - "#" does not stand for an unknown digit.
  - the "@" complex number notation is not supported.
  - "+i" is not considered a number; include the real part.
  - modulo, remainder, and quotient take integer, ratio, or real arguments.
  - lcm and gcd can take integer or ratio arguments.
  - log takes an optional second argument, the base.
  - '.' and an exponent can occur in a number in any base.
  - rationalize returns a ratio!

      > (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
      > (make-rectangular 1/2 0)
      1/2

  > The exponent itself is always in base 10; this follows gmp usage. Since Scheme uses "@" for its useless polar notation, s7 doesn't use it for the exponent marker, but that means `(string->number "1e1" 16)` is ambiguous — is the "e" a digit or an exponent marker? s7 could perhaps substitute "s" in this case, but instead it just prohibits exponents if the radix is greater than 10.

  >     > (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.0

  > Perhaps s7 should use "@"!

  > Should s7 predefine the numbers +inf.0, -inf.0, and nan.0? It doesn't currently, but you can get them via log:

  >     (define -inf.0 (real-part (log 0.0)))
  >     (define +inf.0 (- (real-part (log 0.0))))
  >     (define nan.0 (/ +inf.0 +inf.0))

  > But what 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))
  >     #t

  > How can they be equal? In s7, the sign of -0.0 is ignored, and they really are equal.

  > 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. make-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 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 (make-random-state 1234))
  >     r0
  >     > (random 100 r0)
  >     94
  >     > (random 100 r0)
  >     19
  >     > (define r1 (make-random-state 1234))
  >     r1
  >     > (random 100 r1)
  >     94
  >     > (random 100 r1)
  >     19

  > copy 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 make-random-state to that list.

  >     (define (log-n-of n . ints)     ; return the bits on in exactly n of ints
  >       (let ((len (length ints)))
  >         (cond ((= len 0) (if (= n 0) -1 0))
  >     	  ((= n 0)   (lognot (apply logior ints)))
  >     	  ((= n len) (apply logand ints))
  >     	  ((> n len) 0)
  >     	  (#t
  >     	   (do ((1s 0)
  >     		(prev ints)
  >     		(i 0 (+ i 1)))
  >     	       ((= i len) 1s)
  >     	     (let ((cur (ints i)))
  >     	       (if (= i 0)
  >     		   (set! 1s (logior 1s (logand cur (apply log-n-of (- n 1) (cdr ints)))))
  >     		   (let* ((mid (cdr prev))
  >     			  (nxt (if (= i (- len 1)) '() (cdr mid))))
  >     		     (set! (cdr prev) nxt)
  >     		     (set! 1s (logior 1s (logand cur (apply log-n-of (- n 1) ints))))
  >     		     (set! (cdr prev) mid)
  >     		     (set! prev mid)))))))))

#### define*, lambda*

  define* and lambda* are extensions of define and lambda that make it easier to 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 '(). You can use :optional and :key, but they are ignored.

      (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 bound to their default values, then the function's 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.

      (define* (make-parameter initial-value converter)
        (let ((value (if (procedure? converter) (converter initial-value) initial-value)))
          (lambda* ((val #<unspecified>))
            (if (not (eq? val #<unspecified>))
      	  (set! value (if (procedure? converter) (converter val) val)))
            value)))

      > (define hiho (make-parameter 12))
      hiho
      > (hiho)
      12
      > (hiho 32)
      32
      > (hiho)
      32

  > If you want a version of define* that insists that any arguments before the keyword :optional are required:

  >     (define-macro (define** declarations . forms)
  >       (let ((name (car declarations))
  >     	(args (cdr declarations)))
  >         (define (position thing lst count)
  >           (if (or (null? lst)
  >     	      (not (pair? (cdr lst)))) ; for dotted arg = "rest" arg
  >     	  #f
  >     	  (if (eq? thing (car lst))
  >     	      count
  >     	      (position thing (cdr lst) (+ count 1)))))
  >         (let ((required-args (position :optional args 0)))
  >           (if required-args
  >     	  `(define* (,name . func-args)
  >     	     (if (< (length func-args) ,required-args)
  >     		 (error "~A requires ~D argument~A: ~A"
  >     			',name ,required-args
  >                             (if (> ,required-args 1) "s" "")
  >                             func-args)
  >     		 (apply (lambda* ,args ,@forms) func-args)))
  >     	  `(define* ,declarations ,@forms)))))

  >     > (define** (hi a :optional (b 23)) (list a b))
  >     hi
  >     > (hi 1)
  >     (1 23)
  >     > (hi)
  >     ;hi requires 1 argument: ()

  > If a define* argument's default value is an expression, it is evaluated in the definition environment at the time of the procedure call:

  >     (let ((c 1))
  >       (define* (a (b (+ c 1))) b)
  >       (set! c 2)
  >       (let ((c 123))
  >         (a))) ; (+ c 1) here is (+ 2 1) so this returns 3

  > Since the expression is not evaluated until the procedure is called, it is ok to use variables that are undefined at the definition point:

  >     > (define* (a (b c)) b)
  >     a
  >     > c
  >     ;c: unbound variable
  >     > (define c 123)
  >     c
  >     > (a)
  >     123

  > To 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. 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) ...))`. To turn off this error check, add :allow-other-keys at the end of the parameter list.

  > s7's lambda* arglist handling is not the same as CL's lambda-list. First, you can have more than one :rest parameter:

  >     > ((lambda* ((a 1) :rest b :rest c) (list a b c)) 1 2 3 4 5)
  >     (1 (2 3 4 5) (3 4 5))

  > 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 expression such as:

  >     > ((lambda* ((a 3) . b c) (list a b c)) 1 2 3 4 5)
  >     stray dot?

  > Yet another nit: the :rest argument is not considered a keyword argument, so

  >     > (define* (f :rest a) a)
  >     f
  >     > (f :a 1)
  >     (:a 1)

#### macros

  define-macro, define-macro*, defmacro, defmacro*, macroexpand, gensym, and macro? implement the standard (CL-style) macro definers.

      (define-macro (add-1 arg) `(+ 1 ,arg))
      (defmacro add-1 (arg) `(+ 1 ,arg))

  macroexpand can help debug a macro:

      > (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.

      (defmacro 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

  See s7test.scm for many examples including such perennial favorites as when, loop, dotimes, do*, enum, pushnew, and defstruct.

  macro? returns #t if its argument is a macro or a symbol whose value is a macro. We can use it, and other macro-related stuff to make a version of macroexpand-all:

      (define-macro (fully-expand form)
        (define (expand form)
          (if (pair? form)
      	(if (macro? (car form))
      	    (expand ((eval (procedure-source (car form))) form))
      	    (cons (expand (car form))
      		  (expand (cdr form))))
      	form))
        (expand form))

      > (define-macro (hi a) `(+ 1 ,a))
      hi
      > (define-macro (ha c) `(hi (+ ,c 1)))
      ha
      > (fully-expand (define (ho b) (+ 1 (ha b))))
      ho
      > (procedure-source ho)
      (lambda (b) (+ 1 (+ 1 (+ b 1))))

  fully-expand expands each macro it encounters by using the procedure-source of that macro, that is, the function that the macro definition expanded into:

      (define-macro (hi a) `(+ ,a 1))

      > (procedure-source hi)
      (lambda ({defmac}-18) (apply (lambda (a) ({list} '+ a 1)) (cdr {defmac}-18)))

  > I hesitate to mention this, but macros are first-class entities in s7. You can pass one as a function argument, apply it to a list, return it from a function, and assign it to a variable:

  >     > (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))
  >         hi)
  >     make-mac

  >     > (let ((x (make-mac)))
  >         (x 2))
  >     3

  > Backquote (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 ({defmac}-16) (apply (lambda (a) ({list} '+ 1 a)) (cdr {defmac}-16)))

  >     ;; so (define-macro (hi a) ({list} + 1 a)) is the same

  >     > (define-macro (hi a) `(+ 1 ,@a))
  >     hi
  >     > (procedure-source hi)
  >     (lambda ({defmac}-17) (apply (lambda (a) ({list} '+ 1 ({apply} {values} a))) (cdr {defmac}-17)))

  >     ;; same: (define-macro (hi a) ({list} + 1 ({apply} {values} a)))

  >     > (define-macro (hi a) ``(+ 1 ,,a))
  >     hi
  >     > (procedure-source hi)
  >     (lambda ({defmac}-18) (apply (lambda (a) ({list} '{list} ({list} 'quote '+) 1 a)) (cdr {defmac}-18)))

  > and so on. "{list}" is a special version of "list" to avoid name collisions and handle a few tricky details (similarly for "{values}" and "{apply}"). There is no unquote-splicing macro in s7; ",@(...)" becomes "(unquote (apply values ...))" at read-time.

  > s7 macros are not hygienic. For example,

  >       (define-macro (mac b)
  >         `(let ((a 12))
  >            (+ a ,b)))

  >       (let ((a 1)
  >             (+ *))
  >         (mac a))

  > returns 144 because "+" has turned into "*", and "a" is the internal "a", not the argument "a". We get `(* 12 12)` where we probably expected `(+ 12 1)`. It is possible to use gensym to clean this up, but that makes the macro unreadable in all but the simplest cases. It is also possible, but not very easy, to write a macro to do the gensymification for us, but in s7 it is much more straightforward to use the environment functions. The procedure-environment of a macro is the environment at its definition time, just like a function. By wrapping the macro body in with-environment, we make sure anything in that body reflects the definition environment, not the calling environment. We then augment that environment with the macro arguments getting their values from the call-time environment:

  >     (define-macro (define-immaculo name-and-args . body)
  >       (let* ((gensyms (map (lambda (g) (gensym)) (cdr name-and-args)))
  >     	 (args (cdr (copy name-and-args)))
  >     	 (name (car name-and-args))
  >     	 (set-args (map (lambda (a g) `(list ',g ,a)) args gensyms))
  >     	 (get-args (map (lambda (a g) `(quote (cons ',a ,g))) args gensyms)))

  >         `(define-macro ,name-and-args
  >            `(let ,(list ,@set-args)                 ; get the current macro arg values
  >     	  ,(list 'with-environment
  >     		 (append (list 'augment-environment)
  >     			 (list (list 'procedure-environment ,name))
  >     			 (list ,@get-args))     ; import the current arg values into the definition environment
  >     		 ,@body)))))

  > In this version of define-immaculo, don't unquote the macro arguments in the body, and use `(apply values body)` in place of ",@body".

  >     > (define-immaculo (mac b) `(let ((a 12)) (+ a b)))
  >     mac
  >     > (let ((a 21) (+ *)) (mac a))
  >     33

  > If the slight difference in syntax is a problem

  >     (define-macro (define-immaculo name-and-args . body)
  >       (let* ((gensyms (map (lambda (g) (gensym)) (cdr name-and-args)))
  >     	 (args (cdr (copy name-and-args)))
  >     	 (name (car name-and-args))
  >     	 (set-args (map (lambda (a g) `(list ',g ,a)) args gensyms))
  >     	 (get-args (map (lambda (a g) `(quote (cons ',a ,g))) args gensyms))
  >     	 (blocked-args (map (lambda (a) `(,a ',a)) args))
  >     	 (new-body (list (eval `(let (,@blocked-args) ,@body)))))

  >         `(define-macro ,name-and-args
  >            `(let ,(list ,@set-args)
  >               ,(list 'with-environment
  >                      (append (list 'augment-environment)
  >                              (list (list 'procedure-environment ,name))
  >                              (list ,@get-args))
  >                      ',@new-body)))))

  >     > (define-immaculo (mac c d) `(let ((a 12) (b 3)) (+ a b ,c ,d)))
  >     mac
  >     > (let ((a 21) (b 10) (+ *)) (mac a b))
  >     46
  >     > (let ((a 21) (b 10) (+ *)) (mac a (+ b 10))) ; here '+' is '*'
  >     136

  >     > (macroexpand (define-immaculo (mac c d) `(let ((a 12) (b 3)) (+ a b ,c ,d))))
  >     (define-macro (mac c d)
  >       ({list} 'let
  >         (list (list '{gensym}-23 c)        ; here we get the call-time macro argument values
  >               (list '{gensym}-24 d))
  >           (list 'with-environment
  >                 (append (list 'augment-environment)
  >                                            ; now wrap the body in the augmented definition-time environment
  >                         (list (list 'procedure-environment mac))
  >                                            ; add the macro args to the definition-time env
  >                         (list '(cons 'c {gensym}-23)
  >                               '(cons 'd {gensym}-24)))
  >         '(let ((a 12)
  >                (b 3))
  >            (+ a b c d)))))

  >     > (let ((a 21) (b 10) (+ *)) (macroexpand (mac a b)))

  >     (let (({gensym}-22 a)    ; pick up mac args, this is arg 'c' with the value 'a'
  >           ({gensym}-23 b))
  >       (with-environment (augment-environment (procedure-environment #<macro>)
  >                           (cons 'c {gensym}-22) ; add them to definition-time env
  >     		      (cons 'd {gensym}-23))
  >         (let ((a 12)
  >     	  (b 3))
  >           (+ a b c d)))) ; 'a' and 'b' are local, 'c' and 'd' are from the augmented env

  > This is not the end of the story. Macro expansion happens in two different environments. Leaving aside quasiquote which operates at read-time in the global environment, a macro first evaluates its body to form a piece of code, a list with the macro's arguments plugged in. Then it evaluates that code. So the expansion into a piece of code takes place in one environment (the definition-time environment), and the code evaluation takes place in another (the call-time environment). This can be very frustrating! Say we decide to write a "symbol-set!" macro (borrowed in an oblique way from CL's set). `(symbol-set! var val)` should evaluate "var", getting a symbol as its value, then plug that symbol into `(set! var-value val)`. For example, after expansion we want something like:

  >     > (let ((x 32) (y 'x))
  >         (eval (list 'set! y 123)) ; (symbol-set! y 123) ideally
  >         (list x y))
  >     (123 x)

  > If we define our macro in the local context, then the initial expansion into (set! x 123) takes place in a context where "y" is defined:

  >     > (let ((x 32) (y 'x))
  >         (define-macro (symbol-set! var val)
  >           `(set! ,(symbol->value var) ,val))
  >         (symbol-set! y 123)
  >         (list x y))
  >     (123 x)

  > But if we try to define that at the top level so we can use it anywhere, "var" may not be defined in the environment where the initial list is created:

  >     > (define-macro (symbol-set! var val)
  >         `(set! ,(symbol->value var) ,val))
  >     symbol-set!
  >     > (let ((x 32) (y 'x))
  >         (symbol-set! y 123)
  >         (list x y))
  >     ;y: unbound variable, line 3
  >     ;    ({list} 'set! (symbol->value var) val)

  > Exactly the same thing happens in CL:

  >     > (defmacro symbol-set (var val) `(setf ,(eval var) ,val))
  >     SYMBOL-SET
  >     > (let ((x 32) (y 'x)) (symbol-set y 123))
  >     *** - EVAL: variable Y has no value

  > Our "unhygienic" macros are too clean! We want both the expansion into code and the evaluation of the code to happen in the call-time environment. Since this is a step backward for computer science, I've called these dirty macros, "bacros":

  >     > (define-bacro (symbol-set! var val)
  >        `(set! ,(symbol->value var) ,val))
  >     symbol-set!
  >     > (let ((x 32) (y 'x))
  >         (symbol-set! y 123)
  >         (list x y))
  >     (123 x)

  > Or maybe "hacro"? Use eval in place of symbol->value, and...

  >     > (let ((x #(1 2 3))
  >             (y `(x 1)))
  >         (symbol-set! y 123)
  >         (list x y))
  >     (#(1 123 3) (x 1))

  > s7 uses a bacro to implement macroexpand so that it can handle locally defined macros. By the way, bacros solve part of our original problem:

  >       (define-bacro (mac b)
  >         `(let ((a 12))
  >            (+ a ,(symbol->value b))))

  >       (let ((a 1))
  >         (mac a))

  > returns 13! No variable capture! Perhaps we can massage this idea a bit:

  >     (set! *#readers*
  >       (cons (cons #\_ (lambda (str)
  >     		    `(with-environment
  >                            (initial-environment)
  >                            ,(string->symbol (substring str 1)))))
  >     	*#readers*))

  >     (define-bacro* (mac b)
  >       `(#_let ((a 12))
  >          (#_+ a ,(eval b)))) ; eval rather than symbol->value so that 'b' can be any expression

  > Guaranteed hygienic! I'm not sure it's a big improvement over immaculos or gensyms, but it works.

  > There is another problem with macros: accidental loops. Take the following example; we're trying to write a macro that defines a function that returns its argument in a list statement.

  >     > (define-macro (hang arg) `(define ,arg `(list (cdr ,,arg)))) ; obvious, no?
  >     hang

  >     > (macroexpand (hang (f a)))
  >     (define #1=(f a) ({list} 'list ({list} 'cdr #1#)))

  >     > (hang (f a))
  >     f

  >     > (procedure-source f)
  >     (lambda #1=(a) ({list} 'list ({list} 'cdr (f . #1#))))

  >     >(f 1)

  > And now we are hung. As I think is clear from the procedure source, we've created a procedure with a circular list in its definition! This is surprisingly easy to do by accident. Here's one way out:

  >     > (define-macro (hang arg) `(define ,arg `(list ,,@(cdr arg))))
  >     hang
  >     > (macroexpand (hang (f a)))
  >     (define (f a) ({list} 'list a))
  >     > (hang (f a))
  >     f
  >     > (f 1)
  >     (list 1)

  > The moral of this story is: if you see a circular list in macroexpand, break the loop!

  > But we should end on a happy note. Here is Peter Seibel's once-only macro:

  >       (defmacro once-only (names . body)
  >         (let ((gensyms (map (lambda (n) (gensym)) names)))
  >           `(let (,@(map (lambda (g) `(,g (gensym))) gensyms))
  >     	 `(let (,,@(map (lambda (g n) ``(,,g ,,n)) gensyms names))
  >     	    ,(let (,@(map (lambda (n g) `(,n ,g)) names gensyms))
  >     	       ,@body)))))

  > From the land of sparkling bacros:

  >     (define-bacro (once-only names . body)
  >       `(let (,@(map (lambda (name) `(,name ,(eval name))) names))
  >          ,@body))

#### define-constant, constant?, symbol-access

  define-constant defines a constant and constant? returns #t if its argument is a constant. A constant in s7 is really constant: it can't be set or rebound.

      > (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

  This has the possibly surprising side effect that previous uses of the constant name become constants:

       (define (func a) (let ((cvar (+ a 1))) cvar))
       (define-constant cvar 23)
       (func 1)
       ;can't bind or set an immutable object: cvar

  So, obviously, choose unique names for your constants, or don't use define-constant. A function can also be a constant.

  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). All of these cases modify the path between a symbol and its value. s7 gives you a handle on that path via the procedure-with-setter symbol-access. `(symbol-access symbol)` returns that symbol's accessors, and `(set! (symbol-access symbol) accessor-list)` changes them. The accessor-list is a list of three functions, the get, set, and bind functions. The set and bind functions take two arguments, the symbol in question and the value that it is about to be set or bound to. The variable is set or bound to the value they return. We could replace define-constant, and add local constants with:

      (define constant-access
        (list #f
      	(lambda (symbol new-value)
      	  (format #t "can't change constant ~A's value to ~A" symbol new-value)
                'error)
      	(lambda (symbol new-value)
      	  (format #t "can't bind constant ~A to a new value, ~A" symbol new-value)
                'error)))

      (define-macro (define-constant symbol value)
        `(begin
           (define ,symbol ,value)
           (set! (symbol-access ',symbol) constant-access)
           ',symbol))

      (define-macro (let-constant vars . body)
        (let ((varlist (map car vars)))
          `(let ,vars
             ,@(map (lambda (var)
      		`(set! (symbol-access ',var) constant-access))
      	      varlist)
             ,@body)))

  In the next example, we restrict the values a variable can take to integers:

      (define-macro (define-integer var value)
        `(begin
           (define ,var ,value)
           (set! (symbol-access ',var)
      	   (list #f
      		 (lambda (symbol new-value)
      		   (if (real? new-value)
      		       (floor new-value) ; or min/max to restrict it to some range etc
                             (begin
                               (format #t "~A can only take an integer value, not ~S" symbol new-value)
                               'error)))
      		 #f))
           ',var))

      > (define-integer int 123)
      int
      > (set! int 321.67)
      321
      > (set! int (list 1 2))
      ;int can only take an integer value, not (1 2)

  Here are trace and untrace. We save the previous accessors in trace, restore them upon untrace, and in between, call the previous set accessor, if any, after reporting the set:

      (define (trace var)
        (let* ((cur-access (symbol-access var))
      	 (cur-set (and cur-access (cadr cur-access))))
          (set! (symbol-access var)
      	  (list (and cur-access (car cur-access))
      		(lambda (symbol new-value)
      		  (format #t "~A set to ~A~%" symbol new-value)
      		  (if cur-set
      		      (cur-set symbol new-value)
      		      new-value))
      		(and cur-access (caddr cur-access))
      		cur-access)))) ; save the old version

      (define (untrace var)
        (if (and (symbol-access var)
      	   (cdddr (symbol-access var)))
            (set! (symbol-access var) (cadddr (symbol-access var)))))

  The "get" function is currently not implemented. I believe symbol-access is similar to Ruby's hooked variables, or perhaps Perl's tied variables. We could implement all kinds of things with this mechanism, including property lists.

#### make-type

  make-type, borrowed from Alaric Snell-Pym, returns a type-object: a list of three functions '?, 'make, and 'ref. The ? func returns #t if its argument is of the new type, the make function returns a new object of the new type with the value of the argument to the make function, and the ref function returns that value when passed that object.

      (define special-value ((cadr (make-type)) 'special))
      ;; now special-value's value can't be eq? to any other Scheme object

      ;; expand, for example, (define-record rec (a 1) (b 2))
      (begin
        (define rec? #f)
        (define make-rec #f)
        (define rec-a #f)
        (define rec-b #f)

        (let* ((rec-type (make-type))
      	 (? (car rec-type))
      	 (make (cadr rec-type))
      	 (ref (caddr rec-type)))

          (set! make-rec (lambda* ((a 1) (b 2))
      		     (make (vector a b))))

          (set! rec? ?)

          (set! rec-a (make-procedure-with-setter
      		 (lambda (obj)
      		   (and (rec? obj)
      			(vector-ref (ref obj) 0)))
      		 (lambda (obj val)
      		   (if (rec? obj)
      		       (vector-set! (ref obj) 0 val)))))

          (set! rec-b (make-procedure-with-setter
      		 (lambda (obj)
      		   (and (rec? obj)
      			(vector-ref (ref obj) 1)))
      		 (lambda (obj val)
      		   (if (rec? obj)
      		       (vector-set! (ref obj) 1 val)))))))

      #|
      (let ((hi (make-rec 32 '(1 2))))
        (set! (rec-b hi) 123)
        (format #t "rec: ~A ~A"
      	  (rec-a hi)
      	  (rec-b hi)))

      "rec: 32 123"
      |#

  Currently make-type takes some optional arguments to specify other actions. I might change this to be an alist of (operation function) pairs, but for now, the optional (optkey) arguments are: print equal getter setter length name copy fill. Except for the 'name' argument, these are functions. When these functions are called, the argument representing the object is the value of the object, not the object itself; see the examples below. If no print function is specified, the 'name' argument is used when the object is displayed. The 'equal' function checks two objects of the new type for equality. The 'getter' function applies the object to whatever arguments are passed, and the 'setter' function does the same in the context of set!. The 'length' function returns the length of the object's value. The 'copy function returns a new object of the same type with the copy function applied to the old object's value. The 'fill' function takes two arguments, the object and what to fill its value with. So, remembering that (cadr type) is the make function:

      > ((cadr (make-type)) 3.14)
      #<anonymous-type 3.14>

      > ((cadr (make-type :name "hiho")) 123)
      #<hiho 123>

      > ((cadr (make-type :print (lambda (a) (format #f "#<typo: |~A|>" a)))) 1)
      #<typo: |1|>

      > (((cadr (make-type :getter (lambda (a b) (vector-ref a b)))) (vector 1 2 3)) 1)
      2

  The last is easier to read if we separate out the steps:

      > (let* ((type (make-type
                       :getter (lambda (a b)
                                 (vector-ref a b))))   ; make a new type with its own getter function
               (object ((cadr type) (vector 1 2 3))))  ; create an object of the new type, its value is a vector
             (object 1))                               ; apply the object to 1 => (vector-ref object 1) via the getter
      2

  The objects created in this way, or via s7_new_type in C, can be passed to map and for-each if you supply the length and getter functions to make-type.

      > (define-macro (enum . args)
           `(for-each define ',args ((cadr (make-type :getter (lambda (a b) b)
                                                      :length (lambda (a) ,(length args)))))))
      enum
      > (enum zero one two three)
      #<unspecified>
      > two
      2

  > Here is define-record using make-type. It has a few Common Lisp extensions:

  >     (define-macro (define-record struct-name . fields)
  >       (let* ((name (if (list? struct-name) (car struct-name) struct-name))
  >     	 (sname (if (string? name) name (symbol->string name)))

  >     	 (fsname (if (list? struct-name)
  >     		     (let ((cname (assoc :conc-name (cdr struct-name))))
  >     		       (if cname
  >     			   (symbol->string (cadr cname))
  >     			   sname))
  >     		     sname))

  >     	 (make-name (if (list? struct-name)
  >     			(let ((cname (assoc :constructor (cdr struct-name))))
  >     			  (if cname
  >     			      (cadr cname)
  >     			      (string->symbol (string-append "make-" sname))))
  >     			(string->symbol (string-append "make-" sname))))

  >     	 (is-name (string->symbol (string-append sname "?")))

  >     	 (copy-name (if (list? struct-name)
  >     			(let ((cname (assoc :copier (cdr struct-name))))
  >     			  (if cname
  >     			      (cadr cname)
  >     			      (string->symbol (string-append "copy-" sname))))
  >     			(string->symbol (string-append "copy-" sname))))

  >     	 (field-names (map (lambda (n)
  >     			     (symbol->string (if (list? n) (car n) n)))
  >     			   fields))

  >     	 (field-types (map (lambda (field)
  >     			     (if (list? field)
  >     				 (apply (lambda* (val type read-only) type) (cdr field))
  >     				 #f))
  >     			   fields))

  >     	 (field-read-onlys (map (lambda (field)
  >     				  (if (list? field)
  >     				      (apply (lambda* (val type read-only) read-only) (cdr field))
  >     				      #f))
  >     				fields)))
  >         `(begin

  >            ;; declare our globally-accessible names
  >            (define ,is-name #f)
  >            (define ,make-name #f)
  >            (define ,copy-name #f)

  >            ,@(map (lambda (n)
  >     		`(define ,(string->symbol (string-append fsname "-" n)) #f))
  >     	      field-names)

  >            (let* ((rec-type (make-type))
  >     	      (? (car rec-type))
  >     	      (make (cadr rec-type))
  >     	      (ref (caddr rec-type)))

  >     	 (set! ,is-name ?)

  >     	 (set! ,make-name (lambda* ,(map (lambda (n)
  >     					    (if (and (list? n)
  >     						     (>= (length n) 2))
  >     						(list (car n) (cadr n))
  >     						(list n #f)))
  >     					  fields)
  >     			    (make (vector ',(string->symbol sname) ,@(map string->symbol field-names)))))

  >     	 (set! ,copy-name (lambda (obj)
  >     			    (make (copy (ref obj)))))

  >     	 ,@(map (let ((ctr 1))
  >     		  (lambda (n type read-only)
  >     		    (let ((val (if read-only
  >     				   `(set! ,(string->symbol (string-append fsname "-" n))
  >     					  (lambda (arg) ((ref arg) ,ctr)))
  >     				   `(set! ,(string->symbol (string-append fsname "-" n))
  >     					  (make-procedure-with-setter
  >     					   (lambda (arg) ((ref arg) ,ctr))
  >     					   (lambda (arg val) (set! ((ref arg) ,ctr) val)))))))
  >     		      (set! ctr (+ 1 ctr))
  >     		      val)))
  >     		field-names field-types field-read-onlys)

  >     	',struct-name))))

  >     > (define-record point (x 0.0) (y 0.0))
  >     point
  >     > (let ((pt (make-point 1.0)))
  >         (set! (point-y pt) 3.0)
  >         (list (point? pt) (point-x pt) (point-y pt)))
  >     (#t 1.0 3.0)

  > In the next example, we define a float-vector type:

  >     (begin
  >       (define make-float-vector #f)
  >       (define float-vector? #f)
  >       (define float-vector #f)

  >       (let* ((fv-type (make-type
  >     		   :getter vector-ref :length length :copy copy :fill fill!
  >     		   :setter (lambda (obj index value)
  >     			     (if (not (real? value))
  >     				 (error 'wrong-type-arg-error "float-vector element must be real: ~S" value))
  >     			     (vector-set! obj index (exact->inexact value)))
  >     		   :name "float-vector"))
  >     	 (fv? (car fv-type))
  >     	 (make-fv (cadr fv-type))
  >     	 (fv-ref (caddr fv-type)))

  >         (set! make-float-vector
  >           (lambda* (len (initial-element 0.0))
  >             (if (not (real? initial-element))
  >     	    (error 'wrong-type-arg-error "make-float-vector initial element must be real: ~S" initial-element))
  >     	(make-fv (make-vector len (exact->inexact initial-element)))))

  >         (set! float-vector? fv?)

  >         (set! float-vector
  >           (lambda args
  >     	(let* ((len (length args))
  >     	       (fv (make-float-vector len))
  >     	       (v (fv-ref fv)))
  >     	  (do ((lst args (cdr lst)))
  >     	       (i 0 (+ i 1)))
  >     	      ((null? lst) fv)
  >     	    (let ((arg (car lst)))
  >     	      (if (not (real? arg))
  >     		  (error 'wrong-type-arg-error "float-vector element must be real: ~S in ~S" arg args))
  >     	      (set! (v i) (exact->inexact arg))))))))

  >     > (let ((v (make-float-vector 3))) (set! (v 1) 32) v)
  >     #<float-vector #(0.0 32.0 0.0)>

  >     > (let ((v (make-float-vector 3))) (set! (v 1) "hi") v)
  >     ;float-vector element must be real: "hi"

  >     > (map + (list 1 2 3) (float-vector 1 2 3)) ; we have a getter and length, so map and for-each will work
  >     (2.0 4.0 6.0)

  > I seem to be using the same construct over and over; a begin to hold the names defined in the outer environment, a let to hold internal stuff, and set!s to give the names values. It's a clumsy, but simple way for multiple functions to share a closure. Maybe it rates a macro:

  >     (define-macro (blet* names bindings . body)
  >       `(begin
  >          ,@(map (lambda (name)
  >     	      `(define ,name #f))
  >     	    names)
  >          (let* ,bindings
  >     	,@body)))

  >     (blet* (make-adjustable-vector adjustable-vector? adjust-vector)

  >            ((av-type (make-type :name "adjustable-vector"
  >     			    :getter (lambda (obj index)
  >     				      ((car obj) index))
  >     			    :setter (lambda (obj index value)
  >     				      (set! ((car obj) index) value))
  >     		            :length (lambda (obj)
  >     			              (vector-length (car obj)))
  >     			    :print (lambda (obj)
  >     				     (object->string (car obj)))))
  >     	(av? (car av-type))
  >     	(make-av (cadr av-type))
  >     	(av-ref (caddr av-type)))

  >       (set! make-adjustable-vector (lambda args
  >     				 (make-av (list (apply make-vector args)))))
  >       (set! adjustable-vector? av?)
  >       (set! adjust-vector (lambda* (obj new-length initial-element)
  >     		        (let* ((new-vector (make-vector new-length initial-element))
  >     			       (copy-len (min new-length (length obj))))
  >     			  (do ((i 0 (+ i 1)))
  >     			      ((= i copy-len))
  >     			    (set! (new-vector i) (obj i)))
  >     			  (set! (car (av-ref obj)) new-vector)))))

  >     > (define v (make-adjustable-vector 3 #f))
  >     v

  >     > v
  >     #(#f #f #f)

  >     > (set! (v 1) 32.0)
  >     32.0

  >     > v
  >     #(#f 32.0 #f)

  >     > (adjust-vector v 10 #f)
  >     #(#f 32.0 #f #f #f #f #f #f #f #f)

#### procedure-with-setter

  A procedure-with-setter consists of two functions, the "getter" and the "setter". The getter is called when the object is encountered as a function, and the setter when it is set:

      (define xx (let ((x 32))
                   (make-procedure-with-setter
                     (lambda () x)
                     (lambda (val) (set! x val) x))))
      (xx) -> 32
      (set! (xx) 1)
      (xx) -> 1

  The setter's last argument is the value passed to set!. That is,

      (define v123
        (let ((vect (vector 1 2 3)))
          (make-procedure-with-setter
            (lambda (index)
              (vector-ref vect index))     ; using explicit indexing -- (vect index) is the same (see "generalized set!" below)
            (lambda (index value)
              (vector-set! vect index value)))))

      > (v123 2)
      3
      > (set! (v123 2) 32)
      32
      > (v123 2)
      32

  make-procedure-with-setter can add generalized set! support to any function:

      > (define cadr (make-procedure-with-setter
                       cadr
                       (lambda (lst val)
                         (set! (car (cdr lst) ) val))))
      cadr
      > (cadr '(1 2 3))
      2
      > (let ((lst (list 1 2 3)))
          (set! (cadr lst) 4)
          lst)
      (1 4 3)

  To get the setter from a procedure-with-setter (for procedure-arity for example), use procedure-setter.

  > Here is a pretty example of make-procedure-with-setter:

  >     (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 procedure-with-setter that gets/sets X

  >       (define (X-marks-the-spot accessor tree)
  >         (if (pair? tree)
  >     	(or (X-marks-the-spot (cons 'car accessor) (car tree))
  >     	    (X-marks-the-spot (cons 'cdr accessor) (cdr tree)))
  >     	(if (eq? tree 'X) accessor #f)))

  >       (let ((body 'lst))
  >         (for-each
  >          (lambda (f)
  >            (set! body (list f body)))
  >          (reverse (X-marks-the-spot '() path)))

  >         `(make-procedure-with-setter
  >           (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)))))))))))))))

  > We can extend c?r into something incredibly useful! A goto implementation using circular lists:

  >     (define-macro (define-with-goto name-and-args . body)
  >       ;; run through the body collecting label accessors, (label name)
  >       ;; run through getting goto positions, (goto name)
  >       ;; tie all the goto's to their respective labels (via set-cdr! essentially)

  >       (define (find-accessor type)
  >         (let ((labels '()))
  >           (define (gather-labels accessor tree)
  >     	(if (pair? tree)
  >     	    (if (equal? (car tree) type)
  >     		(begin
  >     		  (set! labels (cons (cons (cadr tree)
  >     					   (let ((body 'lst))
  >     					     (for-each
  >     					      (lambda (f)
  >     						(set! body (list f body)))
  >     					      (reverse (cdr accessor)))
  >     					     (make-procedure-with-setter
  >     					      (apply lambda '(lst) (list body))
  >     					      (apply lambda '(lst val) `((set! ,body val))))))
  >     				     labels))
  >     		  (gather-labels (cons 'cdr accessor) (cdr tree)))
  >     		(begin
  >     		  (gather-labels (cons 'car accessor) (car tree))
  >     		  (gather-labels (cons 'cdr accessor) (cdr tree))))))
  >           (gather-labels '() body)
  >           labels))

  >       (let ((labels (find-accessor 'label))
  >     	(gotos (find-accessor 'goto)))
  >         (if (not (null? gotos))
  >     	(for-each
  >     	 (lambda (goto)
  >     	   (let* ((name (car goto))
  >     		  (goto-accessor (cdr goto))
  >     		  (label (assoc name labels))
  >     		  (label-accessor (and label (cdr label))))
  >     	     (if label-accessor
  >     		 (set! (goto-accessor body) (label-accessor body))
  >     		 (error 'bad-goto "can't find label: ~S" name))))
  >     	   gotos))

  >         `(define ,name-and-args
  >            (let ((label (lambda (name) #f))
  >     	     (goto (lambda (name) #f)))
  >     	 ,@body))))

  >     (define-with-goto (hi)
  >       (display "start ")
  >       (goto 'the-end)
  >       (display "oops")
  >       (label 'the-end)
  >       (display "all done"))

  >     (hi) -> "start all done"

  > I wonder if it would be more consistent to use the name "procedure/setter" in place of "make-procedure-with-setter". Its syntax is closer to vector than make-vector, for example. Even better: "dilambda":

  >     (define-macro (dilambda getter setter)
  >       `(make-procedure-with-setter
  >          (lambda ,@getter)
  >          (lambda ,@setter)))

  >     (let ((a 32))
  >       (dilambda (() a)
  >                 ((b) (set! a b))))

  > "bilambda" would mix Latin and Greek since the Romans used "el", not "lambda", according to Wikipedia.

#### applicable objects, generalized set!, generic functions

  procedure-with-setters 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, and any cooperating C or Scheme-defined objects are both applicable and settable. newLisp calls this implicit indexing, 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!

      ;; an example taken from R Cox's website

      (define dense (make-vector 128))
      (define sparse (make-vector 128))
      (define n 0)

      (define (add-member i)
        (set! (dense n) i)
        (set! (sparse i) n)
        (set! n (+ n 1)))

      (define (is-member i)
        (and (number? (sparse i))
             (< (sparse i) n)
             (= (dense (sparse i)) i)))

      (define (clear-all) (set! n 0))

      (define (remove-member i)
        (if (is-member i)
            (begin
      	(let ((j (dense (- n 1))))
      	  (set! (dense (sparse i)) j)
      	  (set! (sparse j) (sparse i))
      	  (set! n (- n 1))))))

      (add-member 32)
      1
      (add-member 12)
      2
      (is-member 14)
      #f
      (is-member 12)
      #t

  Some more examples:

      > (let ((lst (list 1 2 3)))
          (set! (lst 1) 32)
          (list (lst 0) (lst 1)))
      (1 32)

      > (let ((hash (make-hash-table)))
          (set! (hash 'hi) 32)
          (hash 'hi))
      32

      > (let ((str "123"))
          (set! (str 1) #\x) str)
      "1x3"

  > 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).

  > 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!, 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")
  >     2

  > string->list and vector->list are `(map values object)`. Their inverses are (and always have been) equally trivial. Here's an FFT procedure that accepts lists or vectors, or any similar object:

  >             (define* (cfft! data n (dir 1)) ; (complex data)
  >               (if (not 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)))
  >                 (let ((m (/ n 2)))
  >                   (do ()
  >             	  ((or (< m 2) (< j m)))
  >             	(set! j (- j m))
  >             	(set! m (/ m 2)))
  >                   (set! j (+ j m))))
  >               (let ((ipow (floor (log n 2)))
  >             	(prev 1))
  >                 (do ((lg 0 (+ lg 1))
  >             	 (mmax 2 (* mmax 2))
  >             	 (pow (/ n 2) (/ pow 2))
  >             	 (theta (make-rectangular 0.0 (* pi dir)) (* theta 0.5)))
  >             	((= lg ipow))
  >                   (let ((wpc (exp theta))
  >             	    (wc 1.0))
  >             	(do ((ii 0 (+ ii 1)))
  >             	    ((= ii prev))
  >             	  (do ((jj 0 (+ jj 1))
  >             	       (i ii (+ i mmax))
  >             	       (j (+ ii prev) (+ j mmax)))
  >             	      ((>= jj pow))
  >             	    (let ((tc (* wc (data j))))
  >             	      (set! (data j) (- (data i) tc))
  >             	      (set! (data i) (+ (data i) tc))))
  >             	  (set! wc (* wc wpc)))
  >             	(set! prev mmax))))
  >               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)

  > 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 list, 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 functions). s7 extends that list with map, for-each, reverse, and length, and adds a few others such as copy, fill!, sort!, object->string, and continuation?. 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)`.

#### multidimensional vectors

  s7 supports vectors with any number of dimensions. It is here, in particular, that the generalized set! stuff 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 (list 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.

          > (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

  > matrix multiplication:

  >     (define (matrix-multiply A B)
  >       ;; assume square matrices and so on here for simplicity
  >       (let* ((size (car (vector-dimensions A)))
  >     	 (C (make-vector (list size size) 0)))
  >         (do ((i 0 (+ i 1)))
  >     	((= i size) C)
  >           (do ((j 0 (+ j 1)))
  >     	  ((= j size))
  >     	(let ((sum 0))
  >     	  (do ((k 0 (+ k 1)))
  >     	      ((= k size))
  >     	    (set! sum (+ sum (* (A i k) (B k j)))))
  >     	  (set! (C i j) sum))))))

  > Multidimensional vector constant syntax is modelled after CL: #nd(...) or #nD(...) signals that the lists specify the elements of an 'n' dimensional vector: `#2D((1 2 3) (4 5 6))`

  >         > (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))

  > 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())
  >         #f

  > To 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 args 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))

  > Perhaps I should add an optional number-of-dimensions argument? 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))

  > Another question: should we accept the multi-index syntax in a case such as: `(let ((v #("abc" "def"))) (v 0 2))`? Currently s7 complains because it expects each index in a case like this to refer to the same kind of object. It wants you to use: `(let ((v #("abc" "def"))) ((v 0) 2))`.

#### hash-tables

  - (make-hash-table (size 512))
  - (hash-table ...)
  - (hash-table-ref ht key)
  - (hash-table-set! ht key value)
  - (hash-table? obj)
  - (hash-table-size ht)
  - (make-hash-table-iterator ht)

  Any s7 object can be the key or the key's value. Each hash-table keeps track of the keys it contains, optimizing the search wherever possible. 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.

      (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 cons's containing key/value pairs. The result is a new hash-table with those values preinstalled: `(hash-table '("hi" . 32) '("ho" . 1))`. make-hash-table-iterator returns a function of no arguments (a "thunk"). Each time you call this function, it returns the next entry in the hash table. When it runs out of entries, it returns nil.

  > 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. (Both use make-hash-table-iterator internally).

  >     (define (hash-table->alist table)
  >       (map (lambda (x) x) table)) ; clearer perhaps than (map values table), append would also work here

  > reverse of a hash-table returns a new table with the keys and values reversed. `(fill! table '())` removes all entries from the hash-table.

#### hooks

          (make-hook (arity (0 0 #f)) (documentation ""))  ; make a new hook
          (hook ...)                                       ; make a hook, the args are functions
          (hook? obj)                                      ; return #t if obj is a hook
          (hook-functions hook)                            ; the hook's list of functions
          (hook-arity hook)                                ; the hook's arity list: (required optional rest)
          (hook-documentation hook)                        ; the hook's documentation string
          (hook-apply hook ...) and (<hook> ...)           ; run the hook (it is an applicable object)

  A hook holds a list of functions. When something interesting happens, the hook is invoked, and it applies its arguments to each function in the list. In GUI toolkits hooks are called callback-lists, in CL conditions, in other contexts watchpoints or signals. s7 itself has several hooks: *trace-hook*, *error-hook*, *unbound-variable-hook*, and *load-hook*. A hook is created with make-hook or hook, called either as an applicable object or via hook-apply, and recognized via hook?. The list of functions is accessed via hook-functions. All the functions on the list have to be compatible with the way the hook itself is invoked, so the hook has an arity, hook-arity.

      > (let ((h (make-hook '(1 0 #f) "an example hook")))     ; 1 required arg and no others
          (set! (hook-functions h)                             ; add 1 function to the hook's list
            (list (lambda (x) (format #t "x is ~A" x))))
          (h 23))                                              ; invoke the hook's functions with argument 23
      "x is 23"

#### multiple-values

  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)

        ;; call-with-values:
        (define-macro (call-with-values producer consumer)
          `(,consumer (,producer)))

        ;; multiple-value-bind ("receive" in srfi-8):
        (define-macro (multiple-value-bind vars expr . body)
          `((lambda ,vars ,@body) ,expr))

        ;; multiple-value-set!:
        (define-macro (multiple-value-set! vars expr . body)
          (let ((local-vars (map (lambda (n) (gensym)) vars)))
            `((lambda ,local-vars ,@(map (lambda (n ln) `(set! ,n ,ln)) vars local-vars) ,@body) ,expr)))

        ;; let*-values is defined as a macro at the end of s7.c (commented out)

  > There aren't that many real uses for multiple-values in Scheme. Nearly all can be replaced by a normal list. There are two cases, however, that can't be handled easily with a list. First, you can use "values" 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)

  >     > (define (filter-map func lst) (map (lambda (x) (if (func x) x (values))) lst))

  > Second, you can use multiple-values to turn off the short-circuit evaluation of 'or' and 'and'. Normally these operators stop evaluating their arguments as soon as they hit #t ('or') or #f ('and'). By wrapping the arguments in 'values', you can force all of them to be evaluated:

  >     > (let ((x 1))
  >         (and (let () #f)             ; this returns #f so
  >              (let () (set! x 3) #f)) ;   this is never evaluated
  >         x)
  >     1

  >     > (let ((x 1))
  >         (and (values (let () #f)
  >                      (let () (set! x 3) #f)))
  >       x)
  >     3

  >     > (let ((x 1))                ; (apply and ...) has the same effect
  >         (apply and (list #f (set! x 3))) x)
  >     3

  > At the top-level, since there's nothing to splice into, so 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.

  > Internally, s7 uses `(apply values ...)` to implement unquote splicing (",@") in quasiquote.

  > In some Schemes, values behaves like CL's prog1:

  >     (not s7)> (let ((x 1)) (cond ((values #f (set! x 2) #t) 3) (#t x)))
  >     2
  >     (not s7)> (if (values #f #t) 1 2)
  >     2

  > But in s7 we're trying to implement real multiple values (else why have them at all?). There are many ways we could interpret `(cond ((values ...))...)` and `(cond ((values...) => func))`, but surely equivalent uses of "cond" and "if" should give the same result. Currently in s7, where a test is in progress, only `(values #f)` is the same as #f.

  >     > (if (values #f #f) 1 2)            ; (values #f #f) is not #f
  >     1
  >     > (cond ((values #f #f) 1) (#t 2))
  >     1
  >     ;;; but if we interpreted this as splicing in the values, we get an inconsistency:
  >     > (cond (#f #f 1) (#t 2))
  >     2

  >     > (if (values #f) 1 2)
  >     2
  >     > (cond ((values #f) 1) (#t 2))
  >     2

  >     > (if (values) 1 2)
  >     1
  >     > (cond ((values) 1) (#t 2))
  >     1
  >     ;;; this is consistent with (cond (1) (#t 2))

  > So "if" and "cond" agree, but it requires that in one case the "values" behavior is slightly weird. `(or (values #f #f))` is #f, but that isn't inconsistent because "or" is not testing anything. We might choose to say that `(if (values #f #f)...)` is an error, but that would be hasty — our troubles have only begun. First, "cond" can omit the expressions that follow the test, unlike "if":

  >     > (cond (3))
  >     3

  > and even trickier, "cond" can pass the test value to a function:

  >     > (cond (3 => +))
  >     3

  > The various standards agree that in the "=>" case, the "fed to" function receives one argument, so

  >     (not s7)> (cond ((values 1 2) => +))
  >     1

  > If we were following the "splice immediately" model, this would be `(cond (1 2 => +))` which is an error in some Schemes. So something has to give. My druthers is to make "values" work as consistently as possible, and hope that the one odd corner will not trip anyone. From that point of view, the "one arg" standard looks like a wasted opportunity. s7 handles it this way:

  >     > (+ 1 (cond ((values 2 3))) 4)   ; trailing values are not ignored
  >     10
  >     > (cond ((values 1 2 3) => +))
  >     6

  > Of course, it is unproblematic that the expression can itself involve multiple values:

  >     > (+ (cond (#t (values 1 2))))
  >     3

  > Now, what have I missed?

  > 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.

  > I wrote all that and said "nobody needs multiple values!". In desperation,

  >     (define (flatten lst)
  >       (define (flatten-1 lst)
  >         (cond ((null? lst) (values))
  >     	  ((not (pair? lst)) lst)
  >     	  (#t (values (flatten-1 (car lst))
  >     		      (flatten-1 (cdr lst))))))
  >       (map values (list (flatten-1 lst))))
  >     (define (boring-flatten x)
  >       (cond ((null? x) '())
  >             ((not (pair? x)) (list x))
  >             (#t (append (boring-flatten (car x))
  >     		    (boring-flatten (cdr x))))))

  > Here's a much more entertaining version:

  >     (define (flatten! lst) ; in-place flatten
  >       (let loop ((L lst))
  >         (if (pair? (car L))
  >     	(let ((end (cdr L))
  >     	      (p (car L)))
  >     	  (set! (car L) (car p))
  >     	  (set! (cdr L) (cdr p))
  >     	  (set! (cdr (list-tail L (- (length p) 1))) end)
  >     	  (loop L))
  >     	(if (not (null? (cdr L)))
  >     	    (if (null? (car L))
  >     		(begin
  >     		  (set! (car L) (cadr L))
  >     		  (set! (cdr L) (cddr L))
  >     		  (loop L))
  >     		(loop (cdr L)))))
  >         (if (equal? lst '(()))
  >     	'()
  >     	(let ((len (length lst)))
  >     	  (if (null? (car (list-tail lst (- len 1))))
  >     	      (set! (cdr (list-tail lst (- len 2))) '()))
  >     	  lst))))

#### call-with-exit and continuation?

  call-with-exit is call/cc without the ability to jump back into the original context, similar to "return" in C. This takes the place of CL's catch/throw (s7 uses "catch" for error handling).

      (define (find-first-even-number arg)
        (call-with-exit
         (lambda (return)
           (for-each
            (lambda (a)
      	(if (even? a)
      	    (return a)))
            arg))))

      (find-first-even-number (list 1 3 9 13 8 2 4)) -> 8

      (define-macro (block . body)
        `(call-with-exit
           (lambda (return)
             ,@body)))

      (block (display "hi") (return 32) (display "oops")) -> 32

  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:

      (let ()
        (catch #t
      	 (lambda ()
      	   (let ((res (call/cc
                              (lambda (ok)
      			  (error 'cerror "an error" ok)))))
      	     (display res) (newline)))
      	 (lambda args
      	   (if (and (eq? (car args) 'cerror)
      		    (continuation? (cadadr args)))
      	       (begin
      		 (display "continuing...")
      		 ((cadadr args) 2)))
      	   (display "oops"))))

        -> continuing...2

  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. Otherwise, it blithely announces that it is continuing from the point of the error, but then fails to do so.

  > 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.

#### format, object->string

  s7's built-in 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
      ~A        object->string as in display
      ~S        object->string as in write
      ~C        print as character
      ~P        insert 's' if current argument is not 1 or 1.0 (use ~@P for "ies" or "y")
      ~B        number->string in base 2
      ~O        number->string in base 8
      ~D        number->string in base 10
      ~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)

  The last eight take the usual numeric arguments to specify field width and precision.

  `(format #f ...)` simply returns the formatted string; `(format #t ...)` also sends it to *stdout*. To send the string to *stderr* instead, `(format *stderr* ...)`.

  > Floats can occur in any base, so:

  >     > #xf.c
  >     15.75

  > This 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"

  object->string returns the string representation of its argument:

      > (object->string "hiho")
      "\"hiho\""

      > (format #f "~S" "hiho")
      "\"hiho\""

  > 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 will leave 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))))

#### error handling

  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 (append (list #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

  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.

  When an error is encountered, the variable *error-info*, a vector, contains additional info about that error:

  - 0: the error type or tag, e.g. 'division-by-zero
  - 1: the message or information passed by the error function
  - 2: if not #f, the code that s7 thinks triggered the error
  - 3: if not #f, the line number of that code
  - 4: if not #f, the file name of that code
  - 5: the environment at the point of the error
  - 6...: stack environment pointers, ending in #f

  > To find a variable's value at the point of the error:

  >     (symbol->value var (vector-ref *error-info* 5))

  > To print the stack at the point of the error:

  >     (stacktrace *error-info*)

  > 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-environment
  >     	    (augment-environment
  >     	     (*error-info* 5)      ; the error env
  >     	     (cons 'args args))    ; add the error handler args
  >     	    (list args x y)))))    ; we have access to 'y'

  The hook *error-hook* provides a way to specialize error reporting. Its functions take two arguments, the values passed by the error function: the error type and whatever other info accompanies it.

      (set! (hook-functions *error-hook*) (list (lambda (tag args) (apply format #t args))))

  stacktrace can be called anytime to see the chain of function calls. Its optional argument can be *error-info* to show the stack at the point of the last error, or a continuation to show the continuation stack.

          (let ()
            (define (a1 a) (+ a #\c))
            (define (a2 b) (+ b (a1 b)))
            (define (a3 c) (+ c (a2 c)))
            (catch #t
              (lambda () (a3 1))
              (lambda args (stacktrace *error-info*))))

      ->    (a1 (a . 1))
            (a2 (b . 1))
            (a3 (c . 1))

  See also trace below. There is a break macro defined in Snd (snd-xen.c) which allows you to stop at some point, then evaluate arbitrary expressions in that context. There's yet another hook, *unbound-variable-hook*, which is called before the error is signalled when an unbound variable is encountered. Its functions take one argument, the unbound symbol. In Snd, this is used to implement autoloading:

      (set! (hook-functions *unbound-variable-hook*)
        (list (lambda (sym)
                ;; add your own symbol checks here
                (let ((file (autoload-file (symbol->string sym))))
                  ;; autoload-file is a Snd function that knows where a lot of Snd's Scheme functions are
                  (if file (load file))
                  (symbol->value sym))))) ; this will return #<undefined> if we didn't find its source file

  The s7-built-in catch tags are 'wrong-type-arg, 'syntax-error, 'read-error, 'out-of-memory, 'wrong-number-of-args, 'format-error, 'out-of-range, 'division-by-zero, 'io-error, and 'bignum-error. There's a s7 lint checker: lint.scm in the Snd tarball.

  trace and untrace provide tracing:

          (define (hiho arg)
            (if (> arg 0)
                (+ 1 (hiho (- arg 1)))
                0))

          (trace hiho)

          (hiho 3)

          [hiho 3]
           [hiho 2]
            [hiho 1]
             [hiho 0]
              0
             1
            2
           3

  trace adds a function to the list of functions being traced, and untrace removes it. trace with no arguments causes everything to be traced, and untrace with no arguments turns this off. To trace a function that is internal to another function, put the trace and untrace calls in the enclosing function.

  There is also a hook, *trace-hook*. It takes functions of 2 arguments, the currently traced function and the list of current arguments. The hook's functions are evaluated in the environment of the traced function call (that is, global to the function, not the function's local environment).

          (define (hiho a b c) (* a b c))
          (set! (hook-functions *trace-hook*) (list (lambda (f args) (format #t "sum of args: ~A~%" (apply + args)))))
          (trace hiho)
          (hiho 2 3 4)

          [hiho 2 3 4]
          sum of args: 9
           24

#### procedure info

  procedure-source, procedure-arity, procedure-setter, procedure-documentation, and help provide a look into a Scheme function. procedure-documentation returns the documentation string associated with a procedure: the initial string in the function's body. procedure-arity returns a list describing the argument list of a function: `'(required-args optional-args rest-arg?)`. procedure-setter returns the set function associated with a procedure (set-car! with car, for example). procedure-source returns the source, as a list, of a procedure. procedure-environment returns a procedure's environment.

      > (define* (add-2 a (b 32)) "add-2 adds its 2 args" (+ a b))
      add-2

      > (procedure-documentation add-2)
      "add-2 adds its 2 args"

      > (procedure-arity add-2)
      (0 2 #f)

      > (procedure-source add-2)
      (lambda* (a (b 32)) "add-2 adds its 2 args" (+ a b))

  We can use procedure-environment and __func__ to write a function that tells us where the source is for a function:

      (define (where-is func)
        (let ((addr (symbol->value '__func__ (procedure-environment func))))
          (if (not (pair? addr))
      	"not found"
      	(format #f "~A is at line ~D of ~A" (car addr) (caddr addr) (cadr addr)))))

      > (where-is enveloped-mix)
      "enveloped-mix is at line 68 of extensions.scm"

  > procedure-source returns the actual function source — more fun than a barrel of monkeys. Here is a self-modifying factorial function:

  >     (define fact         ; Reini Urban, http://autocad.xarch.at/lisp/self-mod.lsp.txt
  >       (let ((old '())
  >     	(result '()))

  >         (define (last lst)
  >           (list-tail lst (- (length lst) 1)))

  >         (define (butlast lis)
  >           (let ((len (length lis)))
  >     	(if (<= len 1) '()
  >     	    (let ((result '()))
  >     	      (do ((i 0 (+ i 1))
  >     		   (lst lis (cdr lst)))
  >     		  ((= i (- len 1)) (reverse result))
  >     		(set! result (cons (car lst) result)))))))

  >         (lambda (n)
  >           (cond ((zero? n) 1)
  >     	    (#t
  >     	     (set! old (procedure-source fact))
  >     	     (set! fact (apply lambda '(n)
  >     			  `((cond
  >     			    ,@(butlast (cdr (car (cdr (cdr old)))))
  >     			    ((= n ,n) ,(let ()
  >     					 (set! result (* n (fact (- n 1))))
  >     					 result))
  >     			    ,@(last (cdr (car (cdr (cdr old)))))))))
  >     	     result)))))

  > If you modify the procedure source directly, it is safest to redefine the procedure (as above) so that everything in s7 knows about the change. augment-environment serves a similar purpose when editing environments. Here's a more useful example; it adds trace and local variable info for debugging:

  >     (define-macro (procedure-annotate proc)
  >       (let ((orig (procedure-source proc)))

  >         (define (proc-walk source)
  >           (if (pair? source)
  >     	  (if (or (eq? (car source) 'let)     ; if let or let*, show local variables
  >     		  (eq? (car source) 'let*))
  >     	      (if (symbol? (cadr source))
  >     		  ;; (let name vars . body) -> (let name vars print-vars . body)
  >     		  (append
  >     		   (list (car source)
  >     			 (cadr source)
  >     			 (caddr source)
  >     			 `(format #t "    (let ~A (~{~A~^ ~}) ...)~%" ,(cadr source) (car (environment->list (current-environment)))))
  >     		   (cdddr source))
  >     		  ;; (let(*) vars . body) -> (let vars print-vars . body)
  >     		  (append
  >     		   (list (car source)
  >     			 (cadr source)
  >     			 `(format #t "    (~A (~{~A~^ ~}) ...)~%" ,(car source) (car (environment->list (current-environment)))))
  >     		   (cddr source)))
  >     	      (cons (proc-walk (car source))
  >     		    (proc-walk (cdr source))))
  >     	  source))

  >         (let* ((new-body (proc-walk orig))
  >     	   (result (gensym))
  >     	   (new-source
  >     	    `(lambda ,(cadr orig)
  >     	       (let ((,result #<undefined>))
  >     		 (dynamic-wind
  >     		     (lambda ()       ; upon entry, show procedure name and args
  >     		       (format #t "(~A~{ ~A~})~%" ',proc (caddr (environment->list (current-environment)))))
  >     		     (lambda ()
  >     		       (set! ,result (,new-body ,@(cadr orig)))
  >     		       ,result)
  >     		     (lambda ()       ; at exit, show result
  >     		       (if (eq? ,result #<undefined>)
  >     			   (format #t "  ~A returns early~%")
  >     			   (format #t "  ~A returns ~A~%" ',proc ,result))))))))

  >           `(set! ,proc (eval ,new-source)))))

  >     > (define (hi a) (let ((b 12)) (+ b a)))
  >     hi
  >     > (procedure-annotate hi)
  >     #<closure>
  >     > (let ((x 32)) (+ 1 (hi x)))
  >     45
  >     ;; printing:
  >     (hi (a . 32))
  >         (let ((b . 12)) ...)
  >       hi returns 44

  > Since define* accepts multiple rest arguments, perhaps procedure-arity should return that number, rather than a boolean. I haven't run into a case where it matters. Another odd case: `(procedure-arity (lambda* (:allow-other-keys) #f))`. How should we indicate this in procedure-arity?

  >     (define (for-each-subset func args)
  >       ;; form each subset of args, apply func to the subsets that fit its arity
  >       (let* ((arity (procedure-arity func))
  >     	 (min-args (car arity))                      ; required args
  >     	 (max-args (if (caddr arity)                 ; rest arg?
  >     		       (length args)
  >     		       (+ min-args (cadr arity)))))  ; required+optional
  >         (define (subset source dest len)
  >           (if (null? source)
  >     	  (if (<= min-args len max-args)             ; does this subset fit?
  >     	      (apply func dest))
  >     	(begin
  >     	  (subset (cdr source) (cons (car source) dest) (+ len 1))
  >     	  (subset (cdr source) dest len))))
  >         (subset args '() 0)))

#### environment info

  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 objects in s7.

        (environment? obj)            #t if obj is an environment
        (global-environment)          the top-level environment
        (current-environment)         the currently visible variables and their values
        (procedure-environment proc)  the environment at the time when proc was defined
        (initial-environment)         the current environment, but all built-in functions have their original values

        (with-environment env . body) evaluate body in the environment env

        (augment-environment env . bindings)   add bindings to env
        (augment-environment! env . bindings)
        (environment->list env)       return the environment as a list of lists of (symbol . value) cons's
        (symbol->value sym (env (current-environment)))
        (defined? sym (env (current-environment)))
        (symbol-table)

  `(with-environment env . body)` evaluates its body in the environment env. There are several examples of its use in the macro section. defined? returns #t if the symbol is defined in the environment, and symbol->value returns the value associated with it. To add or change a symbol's value, use augment-environment:

      (let ((a 1))
        (eval '(+ a b)
               (augment-environment
                 (current-environment)
                 (cons 'b 32)))) ; add 'b with the value 32 to this environment

      -> 33

  augment-environment does not change the environment passed to it. It just prepends the new bindings, shadowing any old ones, as if you had called "let". To add the bindings directly to the environment, use augment-environment!. Both of these functions accept nil as the 'env' argument. In this case, they return an environment containing only the bindings you pass in.

  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-environment (initial-environment) ...)`:

      > (let ((caar 123))
          (+ caar (with-environment (initial-environment)
                    (caar '((2) 3)))))
      125

  with-environment and initial-environment are constants, so you can use them in any context without worrying about whether they've been redefined. 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 initial-environment to make sure that none of his bindings pollute the library code:

      (let ()
        (with-environment (initial-environment)
          (load "any-library.scm" (current-environment)) ; 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:

      (begin
        (define bitwise-not-or #f)
        (let ()
          (with-environment (initial-environment)
            (load "any-library.scm" (current-environment))
            (set! bitwise-not-or (symbol->value 'lognor)))))

  Or equivalently:

      (augment-environment! (current-environment)
        (cons 'bitwise-not-or
          (symbol->value 'lognor
            (with-environment (initial-environment)
              (load "any-library.scm" (current-environment))
              (current-environment)))))

  Say he wants to make sure the library is cleanly loaded, but all its bindings are exported into the current environment:

      (apply augment-environment! (current-environment)
        (with-environment (initial-environment)
          (load "any-library.scm" (current-environment))
          (car (environment->list (current-environment))))) ; these are the bindings introduced by loading the library

  To do the same thing, but prepend "library:" to each name:

      (apply augment-environment! (current-environment)
        (with-environment (initial-environment)
          (load "any-library.scm" (current-environment))
          (map (lambda (binding)
      	   (cons (string->symbol
      		  (string-append "library:" (symbol->string (car binding))))
      		 (cdr binding)))
      	 (car (environment->list (current-environment))))))

  That's all there is to it!

  `(symbol-table)` returns the symbol table, a vector of lists of symbols. Here we scan the symbol table looking for any function that doesn't have documentation:

             (let ((st (symbol-table)))
               (do ((i 0 (+ i 1)))
                   ((= i (vector-length st)))
                 (let ((lst (vector-ref st i)))
                   (for-each
                     (lambda (sym)
             	         (if (defined? sym)
      	             (let ((val (symbol->value sym)))
      	               (if (and (procedure? val)
      			        (string=? "" (procedure-documentation val)))
      		           (format #t "~A " sym)))))
                     lst))))

  But geez how boring can something be? Nobody cares about procedure-documentation! Here's a better example, an automatic software torture tester. Even in kiddie mode where we only feed in a few constants, I bet it segfaults!

      (let ((constants (list #f #t pi () 1 1.5 3/2 1.5+i)))

        (define (autotest func args args-left)
          (catch #t (lambda () (apply func args)) (lambda any #f))
          (if (> args-left 0)
      	(for-each
      	 (lambda (c)
      	   (autotest func (cons c args) (- args-left 1)))
      	 constants)))

        (let ((st (symbol-table)))
          (do ((i 0 (+ i 1)))
      	((= i (length st)))
            (let ((lst (st i)))
      	(for-each
      	 (lambda (sym)
      	   (if (defined? sym)
      	       (let ((val (symbol->value sym)))
      		 (if (procedure? val)
      		     (let* ((arity (procedure-arity val))
      			    (req (car arity))
      			    (opt (cadr arity))
      			    (rst (caddr arity)))
      		       (if (or (> (+ opt req) 4)
      		       	       (member (symbol->string sym) '("trace" "exit" "abort")))
      			   (format #t ";skip ~A for now~%" sym) ; no time! no time!
      			   (begin
      			     (format #t ";whack on ~A...~%" sym)
      			     (autotest val '() (+ req opt 1 (if rst 1 0))))))))))
      	 lst)))))

#### eval

  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

  > The environment argument is mainly useful in debugging. A breakpoint can be set, for example, then any input is evaluated in the environment of the break. Say we have the following code in ex.scm:

  >     (define-macro (break)
  >       `(let ((break-env (current-environment))
  >     	 (prompt (format #f "~%~A > " (if (defined? '__func__) __func__ "break"))))
  >          (call-with-exit
  >           (lambda (return)
  >     	(do () ()                       ; our debugger's own REPL
  >     	  (display prompt)              ; show where we stopped
  >     	  (let ((str (read-line '())))  ; read a line of input, :go -> exit the debugger
  >     	    ;; the nil argument to read-line makes sure that we read C's stdin.  In any normal
  >     	    ;;    program, we'd get the string from a text widget.
  >     	    (if (> (length str) 0)
  >     		(catch #t               ; try to handle typing mistakes etc
  >     		       (lambda ()
  >     			 (let ((val (eval-string str break-env)))
  >     			   (if (eq? val :go)
  >     			       (return))
  >     			   (write val)))
  >     		       (lambda args
  >     			 (format #t "error: ~A" args))))))))))

  >     ;; now some random code that has a breakpoint
  >     (define (a-function b)
  >       (let ((x 32))
  >         (do ((i 0 (+ i 1)))
  >     	((= i 10))
  >           (if (= i 3)
  >     	  (break)))
  >         x))

  >     (a-function 123)
  >     (display "done!") (newline)

  > Start up a REPL, and:

  >     > (load "ex.scm")
  >     (a-function "ex.scm" 26) > x    ; here we're in the debugger
  >     32
  >     (a-function "ex.scm" 26) > (+ b i)
  >     126
  >     (a-function "ex.scm" 26) > :go
  >     done!

#### IO functions

  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)              ; return output accumulated in the string output port
          (open-input-string string)            ; open a string input port reading string

      (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"

  Other functions:

  - read-byte and write-byte: binary IO, named "read-u8" and "write-u8" in r6rs, I think
  - read-line: line-at-a-time reads (for write-line, use format or for-each with write-char).

  The variable *vector-print-length* sets the upper limit on how many vector elements 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. See below for an example.

  s7 also includes current-error-port and set-current-error-port.

  > 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. Besides read-byte and write-byte, it uses integer-decode-float, and the various bitwise operators.

#### miscellanea

  *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 is the filename. While loading, the port-filename and port-line-number of the current-input-port can tell you where you are in the file.

      (set! (hook-functions *load-hook*) (list (lambda (name) (format #t "loading ~S...~%" name))))

  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 (filename)
                (let ((pos -1)
      	        (len (length filename)))
                  (do ((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*
      (snd11 snd snd-s7 snd-motif gsl alsa xm clm4 clm sndlib gmp s7)

      > (provided? 'gmp)
      #t

  Multi-line and in-line comments can be enclosed in #| and |#. `(+ #| add |# 1 2)`.

  Leaving aside these two cases, 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, #i123, 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

  I use *#readers* primarily to implement a way to get the current line number and file name, along the lines of C's __LINE__ and __FILE__. port-line-number works if we're reading a file (during load for example), and *error-info* has the same information if an error happens. But during Snd's auto-test sequence, there are many cases that aren't errors, and the file is no longer being loaded, but I need to know where something unexpected happened. So:

      (set! *#readers*
            (cons (cons #\_ (lambda (str)
      			(if (string=? str "__line__")
      			    (port-line-number)
      			    (if (string=? str "__file__")
      			        (port-filename)
      			        #f))))
                  *#readers*))

  Here's a reader macro for read-time evaluation:

      (set! *#readers*
        (cons (cons #\. (lambda (str)
      		    (if (string=? str ".") (eval (read)) #f)))
      	*#readers*))

      > '(1 2 #.(* 3 4) 5)
      (1 2 12 5)

  To return no value from a reader, use `(values)`.

          > (set! *#readers* (cons (cons #\; (lambda (s) (read) (values))) *#readers*))
          ((#\; . #<closure>))
          > (+ 1 #;(* 2 3) 4)
          5

  (make-list length (initial-element #f)) returns a list of 'length' elements defaulting to 'initial-element'.

  reverse! is an in-place version of the built-in function reverse. That is, it modifies the list passed to it in the process of reversing its contents. list-set! sets a member of a list. sort! sorts a list or a vector using the function passed as its second argument to choose the new ordering.

      > (sort! (list 3 4 8 2 0 1 5 9 7 6) <)
      (0 1 2 3 4 5 6 7 8 9)

      (define (mix-notelists . notelists)
        ;; assume the 2nd parameter is the begin time in seconds (the 1st is the instrument name)
        (sort!
         (apply append notelists)
         (lambda (note1 note2)
           (< (cadr note1) (cadr note2)))))

      (mix-notelists '((fm-violin 0 1 440 .1)
      		 (fm-violin 1 1 550 .1))
      	       '((bird 0 .1 )
      		 (bird .2 .1)
      		 (bird 1.2 .3)
      		 (bird .5 .5)))

       -> ((bird 0 0.1) (fm-violin 0 1 440 0.1) (bird 0.2 0.1) (bird 0.5 0.5) (fm-violin 1 1 550 0.1) (bird 1.2 0.3))

  Despite the "!" in its name, sort! actually copies any list argument passed to it, but vectors are sorted in place. sort! can also handle any C-defined object, or anything from make-type, that provides getter, setter, and length functions.

  Keywords exist mainly for define*'s benefit. The keyword functions are: keyword?, make-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.

  help tries to find information about its argument.

      > (help 'caadar)
      "(caadar lst) returns (car (car (cdr (car lst)))): (caadar '((1 (2 3)))) -> 2"

  If the initial expression in a function body is a string constant, it is assumed to be a documentation string (accessible via help or procedure-documentation):

      (define (add1 a)
        "(add1 a) adds 1 to its argument"
        (+ a 1))

      > (help add1)
      "(add1 a) adds 1 to its argument"

  gc calls the garbage collector. `(gc #f)` turns off the GC, and `(gc #t)` turns it on.

  Some other differences from r5rs:

  - after the initial binding, do sets its step variables, rather than rebinding them.
  - no force or delay (use slib).
  - no syntax-rules or any of its friends.
  - s7-version returns the current s7 version.
  - no scheme-report-environment (use initial-environment), null-environment, or interaction-environment (use current-environment).
  - no transcript-on or transcript-off.
  - __func__ is the name (or name and location) of the function currently being defined or called, as in C.
  - 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.
  - letrec*, but without conviction.
  - set! and *-set! return the new value, not #<unspecified>.
  - port-closed?
  - current-input-port, current-output-port, and current-error-port have setters
  - the default IO ports are named *stdin*, *stdout*, and *stderr*.
  - *gc-stats* is a boolean that controls whether GC stats are printed.
  - member and assoc accept an optional 3rd argument, the comparison function (equal? is the default).
  - case accepts => much like cond (the function argument is the selector).

  > Schemes vary in their treatment of (). s7 considers it a constant that evaluates to itself, so you rarely 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. One place where the quote matters is in a case statement; the selector is evaluated but the key is not:

  >     > (case '() ((()) 2) (else 1))
  >     2
  >     > (case '() (('()) 2) (else 1)) ; (eqv? '() ''()) is #f
  >     1
  >     ;;; which parallels #f (or a number such as 2 etc):
  >     > (case '#f ((#f) 2) (else 1))
  >     2
  >     > (case '#f (('#f) 2) (else 1)) ; (eqv? '#f ''#f) is #f
  >     1

  > Similarly, 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.

  > Schemes also vary in handling trailing arguments: `(* 0 "hi")` in Guile returns 0, but s7 gives an error. `(cond (1) (=>))` is 1 in both, and `(or 1 2 . 3)` is an error in Guile, and 1 in s7! Because it flushes trailing arguments, Guile returns 0 from `(* 0 +inf.0)`, but I think it should return NaN.

  > And a harder one... How should s7 treat this: `(string-set! "hiho" 1 #\z)`, or `(vector-set! #(1 2 3) 1 32)`, or `(list-set! '(1 2 3) 1 32)`? Originally, in s7, the first two were errors, and the third was allowed, which doesn't make much sense. Guile and Common Lisp accept all three, but that leads to weird cases where we can reach into a function's body:

  >     > (let ((x (lambda () '(1 2 3)))) (list-set! (x) 1 32) (x))
  >     (1 32 3) ; s7, Guile

  >     > (flet ((x () '(1 2 3))) (setf (nth 1 (x)) 32) (x))
  >     (1 32 3) ; Clisp

  >     > (let ((x (lambda () (list 1 2 3)))) (list-set! (x) 1 32) (x))
  >     (1 2 3)

  > But it's possible to reach into a function's closure, even when the closed-over thing is a constant:

  >     > (flet ((x () '(1 2 3))) (setf (nth 1 (x)) 32) (x))
  >     (1 32 3)

  >     > (let ((xx (let ((x '(1 2 3))) (lambda () x)))) (list-set! (xx) 1 32) (xx))
  >     (1 32 3)

  >     > (let ((xx (let ((x (list 1 2 3))) (lambda () x)))) (list-set! (xx) 1 32) (xx))
  >     (1 32 3)

  > And it's possible to reach into a constant list via list-set! (or set-car! of course):

  >     > (let* ((x '(1 2)) (y (list x)) (z (car y))) (list-set! z 1 32) (list x y z))
  >     ((1 32) ((1 32)) (1 32))

  > It would be a programmer's nightmare to have to keep track of which piece of a list is constant, and an implementor's nightmare to copy every list. set! in all its forms is used for its side-effects, so why should we try to put a fence around them? If we flush "immutable constant" because it is a ham-fisted, whack-it-with-a-shovel approach, the only real problem I can see is symbol->string. In CL, this is explicitly an error:

  >     > (setf (elt (symbol-name 'xyz) 1) #\X)
  >     *** - Attempt to modify a read-only string: "XYZ"

  > And in Guile:

  >     > (string-set! (symbol->string 'symbol->string) 1 #\X)
  >     ERROR: string is read-only: "symbol->string"

  > So both have a notion of immutable strings. I wonder what other Scheme programmers (not implementors!) want in this situation. Currently, there are no immutable list, string, or vector constants, and symbol->string returns a copy of the string. One simple way to ensure immutability is to use copy:

  >     > (let ((x (lambda () (copy "hiho")))) (string-set! (x) 1 #\x) (x))
  >     "hiho"

  > There is one pitfall here. s7 normally tries to optimize garbage collection by removing some constants from the heap. If that constant is a list or a vector, and you later set some member of it to something that needs GC protection, nobody in the heap points to it, so it is GC'd. Here is an example:

  >     (define (bad-idea)
  >       (let ((lst '(1 2 3)))              ; or #(1 2 3) and vector-ref|set
  >         (let ((result (list-ref lst 1)))
  >          (list-set! lst 1 (* 2.0 16.6))
  >          (gc)
  >          result)))

  > Put this is a file, load it into the interpreter, then call `(bad-idea)` a few times. You can turn off the optimization in question by setting the variable *safety* to 1. *safety* defaults to 0. (Also, if *safety* is not 0, sort! is safe from infinite loops).

  > 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#)) ; shared lists use the same syntax: '((1 . 2) (3 1 . 2)) spelled out

  > 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*.

  > 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)))`.

  > 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 #t "~{~A~^ ~}~%" args)) '(1 2 3))
  >       (define (pinner cur nvals len)
  >         (if (= len 1)
  >             (apply func (cons (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 shape

  > s7 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
  >     T

  > This 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.

  > These symbols are not just a silly optimization of string comparison:

  >     (define-macro (hi a)
  >       (let ((funny-name (string->symbol (string #\;))))
  >         `(let ((,funny-name ,a)) (+ 1 ,funny-name))))

  >     > (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 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)))
  >     3

  > I hope that makes you as happy as it makes me!

  > The built-in syntactic names, 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) ; use apply instead of define-bacro
  >         `(apply set! ,var (list ,val)))

  > We can snap together program fragments ("look Ma, no macros!"):

  >     (let* ((x 3)
  >            (arg '(x))
  >            (body `((+ ,x x 1))))
  >       ((apply lambda arg body) 12)) ; "legolambda"?

  >     (let ()
  >       (define (hi a) (+ a x))
  >       ((apply let '((x 32)) (list (procedure-source hi))) 12)) ; one function, many closures?

  > If you apply define or define-macro, the returned value is a symbol, so to apply the new function or macro, you need to use either eval or symbol->value:

  >     > ((symbol->value (apply define-macro '((m a) `(+ 1 ,a)))) 3)
  >     4
  >     > ((symbol->value (apply define '((hi a) (+ a 1)))) 3)
  >     4

  > This gives us a way to make anonymous macros, just as lambda returns an anonymous function:

  >     (define-macro (mu args . body)
  >       (let ((m (gensym)))
  >         `(symbol->value (apply define-macro '((,m ,@args) ,@body)))))

  >     > ((mu (a) `(+ 1 ,a)) 3)
  >     4

  > Currently, you can't set! a built-in syntactic object to some new value: `(set! if 3)`. I hope this kind of thing is not actually very useful, but let me know if you need it. The issue is purely one of speed.

  > 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 at the enclosing level.

  >     > (let ((y 2))
  >           (let ((x 1))
  >             (begin
  >               (define x y)         ; x is 2 (this x is the same as the x in the let above it)
  >               (set! x (* x 2))     ; now it is 4
  >               (define y 123))      ; this is great, but it doesn't affect x
  >              x))                   ; defines in begin are in the enclosing environment so
  >        4                           ;   we get 4

  > I can't find the right tone for this section; this is the 400-th revision; I wish I were a better writer! I think the exact/inexact distinction in Scheme is confused and useless, and leads to verbose and buggy code. In some Schemes, "rational" means "could possibly be expressed equally well as a ratio (floats are approximations)". In s7 it's: "is actually expressed as a ratio (or an integer of course)"; otherwise "rational?" is the same as "real?":

  >     (not-s7-scheme)> (rational? (sqrt 2))
  >     #t

  > 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-scheme)> (integer? 9007199254740993.1)
  >     #t

  > When 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-scheme)> (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-scheme)> (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. When I started work on s7, I thought perhaps "exact" could mean "is represented exactly in the computer". We'd have integers and ratios exact; reals and complex exact if they are exactly represented in the current floating point implementation. 0.0 and 0.5 might be exact if the printout isn't misleading, and 0.1 is inexact. "integer?" and friends would refer instead to the programmer's point of view. That is, if the programmer uses 1 or if the thing prints as 1, it is the integer 1, whereas 1.0 means floating point (not integer!). And to keep exactness in view, we'd have to monitor which operations introduce inexactness — a kind of interval arithmetic. But then what would inexact->exact do? If we discard the exact/inexact distinction, 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))

  > #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

  > Speaking of #b and friends, what should `(string->number "#xffff" 2)` return?

  > r7rs:

  >       (define vector-map map) (define vector-for-each for-each) (define copy-vector copy) (define (vector->string vect) (apply string (vector->list vect)))
  >       (define string-map map) (define string-for-each for-each) (define (string->vector str) (apply vector (string->list str)))
  >       (define copy-list copy)

  >       (define string-ni=? string=?) (define string-ni<? string<?) (define string-ni>? string>?)
  >       (define string-ni<=? string<=?) (define string-ni>=? string>=?)
  >       (define char-foldcase char-downcase) (define string-foldcase string-downcase)
  >       (define (string-downcase str) (apply string (map char-downcase str)))
  >       (define (string-upcase str) (apply string (map char-upcase str)))

  >       (define -inf.0 (real-part (log 0.0))) (define +inf.0 (- -inf.0)) (define +nan.0 (/ +inf.0 +inf.0))
  >       (define (finite? n) (and (number? n) (not (nan? n)) (not (infinite? n))))

  >       (define exact-integer? integer?)
  >       (define (exact-integer-sqrt i) (let ((sq (floor (sqrt i)))) (values sq (- i (* sq sq)))))

  >       (define (port-open? p) (not (port-closed? p))) (define (character-port? p) #t) (define (binary-port? p) #t)
  >       (define (port? p) (or (input-port? p) (output-port? p)))

  >       (define read-u8 read-byte) (define write-u8 write-byte) (define u8-ready? char-ready?) (define peek-u8 peek-char)
  >       (define blob? vector?) (define make-blob make-vector) (define blob-length length) (define blob-copy copy)
  >       (define blob-u8-ref vector-ref) (define blob-u8-set! vector-set!)

  >       (define scheme-report-environment initial-environment)
  >       (define interaction-environment current-environment)
  >       (define (include file) (load file (current-environment)))

  >       (set! *#readers* (cons (cons #\; (lambda (s) (read) (values))) *#readers*))

  > Here are some additional 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
  >        remove `#(...) support (quasiquoted vector constants)
  >        remove *-ci functions
  >        remove string<->list and vector<->list
  >        change string->symbol to symbol
  >        remove call-with-values and its friends
  >        remove char-ready?
  >        change eof-object? to eof? or end-of-input? or just omit it (you can use eq? #<eof>)
  >        use @ as the exponent marker if base > 10
  >        remove the "d", "f", "s", and "l" exponent markers (leaving "e" and "E")

  > and perhaps:

  >        remove even? and odd?
  >        remove the 4-way cxxxxr functions
  >        add file-exists?, directory?, and delete-file
  >        remove string-length, vector-length, and hash-table-size.
  >        remove list-ref|set!, string-ref|set!, vector-ref|set!, hash-table-ref|set!,
  >          set-car!|cdr!, and set-current-output|input|error-port.

  > Scheme needs a more elegant way to define functions that share a closure. The begin+define+let+set! shuffle used above is an embarrassment. Here's an idle thought:

  >     (define f1 (let ((x 23))
  >     	     (lambda (a)
  >     	       (+ x a))))
  >     (define f2
  >       (with-environment (procedure-environment f1) ; import f1's closure ("x") into f2
  >        (lambda (b)
  >          (+ b (* 2 x)))))

  >     > (+ (f1 1) (f2 1))
  >     71

  > s7 originally had 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 pthreads 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, as discussed at length below, threads were not useful mainly because the GUI toolkits are not thread safe, so we use begin_hook now instead. 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.

  > "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)

#### the run macro

  s7 is primarily aimed at computer music, CLM-based sound synthesis in particular. A CLM instrument is usually a do-loop running things like oscillators and envelopes for zillions of sound samples. These calculations do not involve recursion, or complex numbers, or fancy list processing, so it is not too hard to write an optimizer for them. In sndlib, that optimizer is called "run". It is a macro (in modern jargon, a JIT byte compiler) that can be wrapped around any piece of Scheme code that you want to speed up. If it can't optimize the code, it passes it to the s7 interpreter. If run is successful, you will normally get a speed up by a factor of about 10.

### FFI examples

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:

        HAVE_STDBOOL_H                 1 if you have stdbool.h
        WITH_GMP                       1 if you want multiprecision arithmetic (requires gmp, mpfr, and mpc, default is 0)
        WITH_COMPLEX                   1 if your compiler supports complex numbers
        HAVE_COMPLEX_TRIG              1 if your math library has complex versions of the trig functions
        S7_DISABLE_DEPRECATED          1 if you want to make sure you're not using any deprecated s7 stuff (default is 0)
        HAVE_GETTIMEOFDAY              1 if you want timing info from the GC (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 1)

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:

- read-eval-print loop (and emacs)
- define a function with arguments and a returned value, and define a variable
- call a Scheme function from C, and get/set Scheme variable values in C
- C++ and Juce
- load sndlib using the XEN functions and macros
- add a new Scheme type and a procedure-with-setter
- redirect display output to a C procedure
- extend a built-in operator ("+" in this case)
- C-side define* (s7_define_function_star)
- C-side define-macro (s7_define_macro)
- signal handling (C-C to break out of an infinite loop)
- direct multidimensional vector element access
- notification in C that a Scheme variable has been set!
- Load C defined stuff into a separate namespace
- Error handling in C
- Closure defined in C
- Hooks in C and Scheme
- Load a C module dynamically
- gmp and friends
- Gtk-based REPL
- Gtk/Scheme-based REPL
- s7 running in a separate thread
- begin_hook to the rescue!

First, a bare REPL:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>
    #include "s7.h"

    static s7_pointer our_exit(s7_scheme *sc, s7_pointer args)
    {
      /* all added functions have this form, args is a list,
       *    s7_car(args) is the 1st arg, etc
       */
      exit(1);
      return(s7_nil(sc)); /* never executed, but makes the compiler happier */
    }

    int main(int argc, char **argv)
    {
      s7_scheme *s7;
      char buffer[512];
      char response[1024];

      s7 = s7_init();                     /* initialize the interpreter */
      s7_define_function(s7, "exit", our_exit, 0, 0, false, "(exit) exits the program");
                                          /* add the function "exit" to the interpreter.
                                           *   0, 0, false -> no required args,
    				       *                  no optional args,
    				       *                  no "rest" arg
    				       */
      while (1)                           /* fire up a REPL */
        {
          fprintf(stdout, "\n> ");        /* prompt for input */
          fgets(buffer, 512, stdin);
          if ((buffer[0] != '\n') ||
    	  (strlen(buffer) > 1))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response); /* evaluate input and write the result */
    	}
        }
    }

    /* make mus-config.h (it can be empty), then
     *
     *   gcc -c s7.c -I.
     *   gcc -o doc7 doc7.c s7.o -lm -I.
     *
     * run it:
     *
     *    doc7
     *    > (+ 1 2)
     *    3
     *    > (define (add1 x) (+ 1 x))
     *    add1
     *    > (add1 2)
     *    3
     *    > (exit)
     */

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 ("doc7"), then call the emacs function run-scheme: M-x eval-expression in emacs, followed by (setq scheme-program-name "doc7"), then M-x run-scheme, and you're talking to s7 in emacs. Of course, this connection can be customized indefinitely. See, for example, snd-inf.el in the Snd package.

To read stdin while working in a GUI-based program is trickier. In glib/gtk, 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);

If we accidentally get into an infinite loop in our REPL, we have to exit the program. See signal handling and begin_hook to the rescue! below for two ways to fix this.

Define a function with arguments and a returned value, and a variable:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer our_exit(s7_scheme *sc, s7_pointer args)
    {
      exit(1);
      return(s7_nil(sc));
    }

    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"));
    }

    int main(int argc, char **argv)
    {
      s7_scheme *s7;
      char buffer[512];
      char response[1024];

      s7 = s7_init();                     /* initialize the interpreter */

      s7_define_function(s7, "exit", our_exit, 0, 0, false, "(exit) exits the program");
      s7_define_function(s7, "add1", add1, 1, 0, false, "(add1 int) adds 1 to int");
      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))
    	{
    	  sprintf(response, "(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)
     */

Call a Scheme-defined function from C, and get/set Scheme variable values in C:

    #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: %d\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: %d\n",
    	  s7_integer(s7_name_to_value(s7, "an-integer")));

      fprintf(stderr, "(add1 2): %d\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
     */

C++ and Juce, from Rick Taube:

    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;
    }

Load sndlib using the XEN functions and macros into an s7 repl:

    #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 */

    #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 */
    	   s7_make_symbol(s7, "mus-error"),
    	   s7_cons(s7, s7_make_string(s7, msg), s7_nil(s7)));
    }

    static s7_pointer our_exit(s7_scheme *sc, s7_pointer args)
    {
      exit(1);
      return(s7_nil(sc));
    }

    /* the next functions are needed for either with-sound or many standard instruments, like fm-violin */
    /*   (these are in the xen-style FFI) */

    static XEN g_file_exists_p(XEN name)
    {
      #define H_file_exists_p "(file-exists? filename): #t if the file exists"
      XEN_ASSERT_TYPE(XEN_STRING_P(name), name, XEN_ONLY_ARG, "file-exists?", "a string");
      return(C_TO_XEN_BOOLEAN(mus_file_probe(XEN_TO_C_STRING(name))));
    }

    XEN_NARGIFY_1(g_file_exists_p_w, g_file_exists_p)

    static XEN g_delete_file(XEN name)
    {
      #define H_delete_file "(delete-file filename): deletes the file"
      XEN_ASSERT_TYPE(XEN_STRING_P(name), name, XEN_ONLY_ARG, "delete-file", "a string");
      return(C_TO_XEN_BOOLEAN(unlink(XEN_TO_C_STRING(name))));
    }

    XEN_NARGIFY_1(g_delete_file_w, g_delete_file)

    int main(int argc, char **argv)
    {
      char buffer[512];
      char response[1024];

      s7 = s7_init();                     /* initialize the interpreter */
      xen_initialize();                   /* 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 */

      XEN_DEFINE_PROCEDURE("file-exists?", g_file_exists_p_w, 1, 0, 0, H_file_exists_p);
      XEN_DEFINE_PROCEDURE("delete-file",  g_delete_file_w,   1, 0, 0, H_delete_file);
      s7_define_function(s7, "exit", our_exit, 0, 0, false, "(exit) exits the program");

      while (1)                           /* fire up a "repl" */
        {
          fprintf(stdout, "\n> ");        /* prompt for input */
          fgets(buffer, 512, stdin);

          if ((buffer[0] != '\n') ||
    	  (strlen(buffer) > 1))
    	{
    	  sprintf(response, "(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
     *
     *   (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
     */

Add a new Scheme type and procedure-with-setters:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer our_exit(s7_scheme *sc, s7_pointer args)
    {
      exit(1);
      return(s7_nil(sc));
    }

    /* 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 char *print_dax(s7_scheme *sc, void *val)
    {
      char *data_str, *str;
      int data_str_len;
      dax *o = (dax *)val;
      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);
      return(str);
    }

    static void free_dax(void *val)
    {
      if (val) free(val);
    }

    static bool equal_dax(void *val1, void *val2)
    {
      return(val1 == val2);
    }

    static void mark_dax(void *val)
    {
      dax *o = (dax *)val;
      if (o) s7_mark_object(o->data);
    }

    static int dax_type_tag = 0;

    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_car(s7_cdr(args));
      else o->data = s7_nil(sc);
      return(s7_make_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_object(s7_car(args)) &&
    			 s7_object_type(s7_car(args)) == dax_type_tag));
    }

    static s7_pointer dax_x(s7_scheme *sc, s7_pointer args)
    {
      dax *o;
      o = (dax *)s7_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_object_value(s7_car(args));
      o->x = s7_real(s7_car(s7_cdr(args)));
      return(s7_car(s7_cdr(args)));
    }

    static s7_pointer dax_data(s7_scheme *sc, s7_pointer args)
    {
      dax *o;
      o = (dax *)s7_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_object_value(s7_car(args));
      o->data = s7_car(s7_cdr(args));
      return(o->data);
    }

    int main(int argc, char **argv)
    {
      s7_scheme *s7;
      char buffer[512];
      char response[1024];

      s7 = s7_init();

      s7_define_function(s7, "exit", our_exit, 0, 0, false, "(exit) exits the program");
      s7_define_variable(s7, "*listener-prompt*", s7_make_string(s7, ">"));

      dax_type_tag = s7_new_type("dax", print_dax, free_dax, equal_dax, mark_dax, NULL, NULL);
      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_make_procedure_with_setter(s7, "dax-x", dax_x, 1, 0, set_dax_x, 2, 0, "dax x field"));

      s7_define_variable(s7, "dax-data",
                         s7_make_procedure_with_setter(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))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response); /* evaluate input and write the result */
    	}
        }
    }

    /*
     *    > *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)
     */

Redirect output (and input) to a C procedure:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static void my_print(s7_scheme *sc, char 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(s7, 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))
    	{
    	  sprintf(response, "(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]
     */

Extend a built-in operator ("+" in this case):

    #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))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response);
    	}
        }
    }

    /*
     *    > (+ 1 2)
     *    3
     *    > (+ "hi" "ho")
     *    "hiho"
     */

C-side define* (s7_define_function_star):

    #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_car(s7_cdr(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))
    	{
    	  sprintf(response, "(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
     */

C-side define-macro (s7_define_macro):

    #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_car(s7_cdr(args));
      return(s7_cons(sc, s7_make_symbol(sc, "+"),  /* we are forming the list `(+ ,a ,b) */
    	   s7_cons(sc, a,
    	     s7_cons(sc, b, s7_nil(sc)))));
    }

    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))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response);
    	}
        }
    }

    /*
     *    > (plus 2 3)
     *    5
     */

Signal handling (C-C to break out of an infinite loop), and s7_make_continuation to pick up where we were interrupted:

    #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_exit(s7_scheme *sc, s7_pointer args)
    {
      /* this function is really needed if we are trapping C-C! */
      exit(1);
      return(s7_f(sc));
    }

    static s7_pointer our_sleep(s7_scheme *sc, s7_pointer args)
    {
      /* slow down out 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, "exit", our_exit, 0, 0, false, "(exit) exits");
      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))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response);
    	}
        }
    }

    /*
     *    > (do ((i 0 (+ i 1))) ((= i -1)) (format #t "~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
     */

Multidimensional vector element access:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>
    #include <stdarg.h>

    #include "s7.h"

    static s7_pointer multivector_ref(s7_scheme *sc, s7_pointer vector, int indices, ...)
    {
      /* multivector_ref returns an element of a multidimensional vector */
      int ndims;
      ndims = s7_vector_rank(vector);

      if (ndims == indices)
        {
          va_list ap;
          s7_Int index = 0;
          va_start(ap, indices);

          if (ndims == 1)
    	{
    	  index = va_arg(ap, s7_Int);
    	  va_end(ap);
    	  return(s7_vector_ref(sc, vector, index));
    	}
          else
    	{
    	  int i;
    	  s7_pointer *elements;
    	  s7_Int *offsets, *dimensions;

    	  elements = s7_vector_elements(vector);
    	  dimensions = s7_vector_dimensions(vector);
    	  offsets = s7_vector_offsets(vector);

    	  for (i = 0; i < indices; i++)
    	    {
    	      int ind;
    	      ind = va_arg(ap, int);
    	      if ((ind < 0) ||
    		  (ind >= dimensions[i]))
    		{
    		  va_end(ap);
    		  return(s7_out_of_range_error(sc,
                                                   "multivector_ref", i,
                                                   s7_make_integer(sc, ind),
                                                   "index should be between 0 and the dimension size"));
    		}
    	      index += (ind * offsets[i]);
    	    }
    	  va_end(ap);
    	  return(elements[index]);
    	}
        }
      return(s7_wrong_number_of_args_error(sc,
                                           "multivector_ref: wrong number of indices: ~A",
                                           s7_make_integer(sc, indices)));
    }

    int main(int argc, char **argv)
    {
      char buffer[512];
      char response[1024];
      s7_scheme *s7;

      s7 = s7_init();
      s7_eval_c_string(s7, "(define vect (make-vector '(2 3 4) 0))");
      s7_eval_c_string(s7, "(set! (vect 1 1 1) 32)");

      fprintf(stdout, "vect[0,0,0]: %s, vect[1,1,1]: %s\n",
    	  s7_object_to_c_string(s7, multivector_ref(s7, s7_name_to_value(s7, "vect"), 3, 0, 0, 0)),
    	  s7_object_to_c_string(s7, multivector_ref(s7, s7_name_to_value(s7, "vect"), 3, 1, 1, 1)));
    }

    /* vect[0,0,0]: 0, vect[1,1,1]: 32
     */

Notification from Scheme that a given Scheme variable has been set.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    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_car(s7_cdr(args))));
      return(s7_car(s7_cdr(args)));
    }

    int main(int argc, char **argv)
    {
      s7_scheme *s7;
      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      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_symbol_set_access(s7,   /* set symbol-access of notified-var to (list #f notify-C #f) */
    		       s7_make_symbol(s7, "notified-var"),
    		       s7_cons(s7,
    			       s7_f(s7),
    			       s7_cons(s7,
    				       s7_name_to_value(s7, "notify-C"),
    				       s7_cons(s7,
    					       s7_f(s7),
    					       s7_nil(s7)))));

      if (argc == 2)
        {
          fprintf(stderr, "load %s\n", argv[1]);
          s7_load(s7, 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))
    	    {
    	      sprintf(response, "(write %s)", buffer);
    	      s7_eval_c_string(s7, response);
    	    }
    	}
        }
    }

    /*    > notified-var
     *    0
     *    > (set! notified-var 32)
     *    notified-var set to 32
     *    32
     */

Load C defined stuff into a separate namespace.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    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();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      /* "func1" and "var1" will be placed in an anonymous environment,
       *   accessible from Scheme via the global variable "lib-exports"
       */

      new_env = s7_augment_environment(s7, s7_cons(s7, s7_current_environment(s7), s7_nil(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_car(s7_environment_to_list(s7, new_env)));

      if (argc == 2)
        {
          fprintf(stderr, "load %s\n", argv[1]);
          s7_load(s7, 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))
    	    {
    	      sprintf(response, "(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 augment-environment (current-environment) lib-exports))
     *     lib-env
     *     > (with-environment lib-env (func1 var1))
     *     33
     *
     *     ;; or rename them to prepend "lib:"
     *     > (define lib-env (apply augment-environment
                                    (current-environment)
                                    (map (lambda (binding)
                                           (cons (string->symbol
                                                   (string-append "lib:" (symbol->string (car binding))))
                                                 (cdr binding)))
                                         lib-exports)))
     *     lib-env
     *     > (with-environment 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
     */

Handle scheme errors in C.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    static s7_pointer error_handler(s7_scheme *sc, s7_pointer args)
    {
      /* put <<>> around the string so it's obvious who is producing what */

      fprintf(stdout, "<<%s>>", s7_string(s7_car(args)));
      return(s7_make_symbol(sc, "our-error"));
    }

    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, "exit", my_exit, 0, 0, false, "(exit) exits the program");
      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 (tag args)                             \n\
                                        (error-handler                               \n\
                                          (apply format #f (car args) (cdr args))))))");

      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.
     *
     * 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)
     *   <<+ 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).
     */

We often have hooks or callback lists in Scheme, and would like to place a C-defined s7 function on such a list. If the C-side function does not have any state, we can just add its name to the list, but if it is effectively a closure, we have a problem. C itself does not provide closures, so the standard two-step is to include a void* pointer with the C function in a struct, then when that is called, pass the pointer to the function by hand. This obviously does not work if we want that function to be a member of a normal Scheme list of functions. So in the next example, we define a closure in C using s7_make_closure.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer closure_func(s7_scheme *sc, s7_pointer args)
    {
      /* closure_func is the function portion of our closure.  It assumes its
       *   environment has an integer named "x".  The function also takes one argument,
       *   an integer we'll call it "y".
       */
      return(s7_make_integer(sc,                            /* return (+ y x) */
                             s7_integer(s7_car(args)) +     /*   this is y */
                             s7_integer(s7_name_to_value(sc, "x"))));
    }

    static s7_pointer define_closure(s7_scheme *sc, const char *name, s7_pointer func, s7_pointer x_value)
    {
      /* make_closure creates a new closure with x_value as the local value of x,
       *   and func as the function.  It defines this in Scheme as "name".
       *
       *   s7_make_closure's arguments are the closure code as (<args> <code>), and
       *   the closure's environment.  For the first part, we'll use '((y) (f y)),
       *   and for the second, we'll augment the current environment with
       *   ((x . x_value) (f . func)).
       */
      s7_define(sc,
    	    s7_nil(sc),
    	    s7_make_symbol(sc, name),
    	    s7_make_closure(sc,
    			    s7_cons(sc,
    				    s7_cons(sc,            /* closure arg list: '(y) */
    				            s7_make_symbol(sc, "y"),
                                                s7_nil(sc)),
    				    s7_cons(sc,            /* closure code: (f y) */
    					    s7_cons(sc,
    						    s7_make_symbol(sc, "f"),
    						    s7_cons(sc,
                                                                s7_make_symbol(sc, "y"),
                                                                s7_nil(sc))),
    					    s7_nil(sc))),
    			    s7_augment_environment(sc,
    						   s7_current_environment(sc),
    						   s7_cons(sc,
    							   s7_cons(sc,  /* the local binding for "x" */
                                                                       s7_make_symbol(sc, "x"),
                                                                       x_value),
    							   s7_cons(sc,  /*     and "f" */
    								   s7_cons(sc,
                                                                               s7_make_symbol(sc, "f"),
                                                                               func),
    								   s7_nil(sc))))));
      return(s7_unspecified(sc));
    }

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    int main(int argc, char **argv)
    {
      char buffer[512];
      char response[1024];
      s7_pointer c_func;
      s7_scheme *s7;

      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      c_func = s7_make_function(s7, "#<closure function>", closure_func, 1, 0, false, "function used by define_closure");

      define_closure(s7, "closure-1", c_func, s7_make_integer(s7, 32));  /* (let ((x 32)) (lambda (y) (+ y x))) */
      define_closure(s7, "closure-2", c_func, s7_make_integer(s7, 123)); /* (let ((x 123)) (lambda (y) (+ y x))) */

      while (1)
        {
          fprintf(stdout, "\n> ");
          fgets(buffer, 512, stdin);
          if ((buffer[0] != '\n') ||
    	  (strlen(buffer) > 1))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response);
    	}
        }
    }

    /*
     *   > (closure-1 3)
     *   35
     *   > (closure-2 3)
     *   126
     *   > (procedure-source closure-1)
     *   (lambda (y) (f y))
     *   > (environment->list (procedure-environment closure-1))
     *   (((f . #<closure function>) (x . 32)))
     */

C and Scheme hook handling.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    static s7_pointer my_hook_function(s7_scheme *sc, s7_pointer args)
    {
      fprintf(stderr, "arg is %s\n", s7_object_to_c_string(sc, 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();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      /* define test_hook in C, test-hook in Scheme */
      test_hook = s7_make_hook(s7, 2, 0, false, "test-hook's functions take 2 arguments");
      s7_define_constant(s7, "test-hook", test_hook);

      /* add my_hook_function to the test_hook function list */
      s7_hook_set_functions(test_hook,
    			s7_cons(s7,
    				s7_make_function(s7, "my-hook-function", my_hook_function, 2, 0, false, "my hook-function"),
    				s7_hook_functions(test_hook)));
      while (1)
        {
          fprintf(stdout, "\n> ");
          fgets(buffer, 512, stdin);

          if ((buffer[0] != '\n') ||
    	  (strlen(buffer) > 1))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response);
    	}
        }
    }

    /*
     *    > test-hook
     *    #<hook>
     *
     *    > (hook-functions test-hook)
     *    (my-hook-function)
     *
     *    > (set! (hook-functions test-hook)
     *        (cons (lambda (a b) (format #t "a is ~S~%" a))
     *              (hook-functions test-hook)))
     *    (#<closure> my-hook-function)
     *
     *    > (test-hook 1 2)
     *    a is 1
     *    arg is 1
     *    1
     */

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:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include "s7.h"

    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") */
    {
      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"

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    #include <dlfcn.h>
    static s7_pointer cload(s7_scheme *sc, s7_pointer args)
    {
      #define CLOAD_HELP "(cload so-file-name init-func-name) loads the module and calls the init function"
      void *library;
      library = dlopen(s7_string(s7_car(args)), RTLD_LAZY);
      if (library)
        {
          void *init_func;
          init_func = dlsym(library, s7_string(s7_car(s7_cdr(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));
    	}
          else fprintf(stderr, "loader error: %s\n", dlerror());
        }
      else fprintf(stderr, "loader error: %s\n", dlerror());
      return(s7_f(sc));
    }

    int main(int argc, char **argv)
    {
      char buffer[512];
      char response[1024];
      s7_scheme *s7;

      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");
      s7_define_function(s7, "cload", cload, 2, 0, false, CLOAD_HELP);
      while (1)
        {
          fprintf(stdout, "\n> ");
          fgets(buffer, 512, stdin);

          if ((buffer[0] != '\n') ||
    	  (strlen(buffer) > 1))
    	{
    	  sprintf(response, "(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
     *
     * 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-12/ex3a.so" "init_ex")
     *   #t
     *   > (add-1 2)
     *   3
     */

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, so we have to copy that into a new number before adding.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include <gmp.h>
    #include <mpfr.h>
    #include <mpc.h>

    #include "s7.h"

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    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;
      x = s7_car(args);
      if (s7_is_bignum(x))
        {
          s7_pointer n;
          if (s7_is_integer(x))
    	{
    	  mpz_t *big_n;
    	  n = s7_make_big_integer(sc, s7_big_integer(x)); /* copy x */
    	  big_n = s7_big_integer(n);                      /* get mpz_t pointer of copy */
    	  mpz_add_ui(*big_n, *big_n, 1);                  /* add 1 to that */
    	  return(n);                                      /* return the new bignum */
    	}
          if (s7_is_ratio(x))
    	{
    	  mpq_t *big_q;
    	  mpz_t num, den;
    	  n = s7_make_big_ratio(sc, s7_big_ratio(x));
    	  big_q = s7_big_ratio(n);
    	  mpz_init_set(num, mpq_numref(*big_q));
    	  mpz_init_set(den, mpq_denref(*big_q));
    	  mpz_add(num, num, den);
    	  mpq_set_num(*big_q, num);
    	  mpz_clear(num);
    	  mpz_clear(den);
    	  return(n);
    	}
          if (s7_is_real(x))
    	{
    	  mpfr_t *big_x;
    	  n = s7_make_big_real(sc, s7_big_real(x));
    	  big_x = s7_big_real(n);
    	  mpfr_add_ui(*big_x, *big_x, 1, GMP_RNDN);
    	  return(n);
    	}
          /* x must be big complex */
          {
    	mpc_t *big_z;
    	n = s7_make_big_complex(sc, s7_big_complex(x));
    	big_z = s7_big_complex(n);
    	mpc_add_ui(*big_z, *big_z, 1, MPC_RNDNN);
    	return(n);
          }
        }
      else
        {
          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, "exit", my_exit, 0, 0, false, "(exit) exits the program");
      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))
    	{
    	  sprintf(response, "(write %s)", buffer);
    	  s7_eval_c_string(s7, response);
    	}
        }
    }

    /*
     *   gcc -DWITH_GMP=1 -c s7.c -I. -O2 -g3
     *   gcc -DWITH_GMP=1 -o ex2 ex2.c s7.o -I. -O2 -lm -lgmp -lmpfr -lmpc
     *
     *   ex2
     *   > (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          ; this is the bignum 4
     *   > (add-1 (bignum "3/4"))
     *   7/4
     *   > (add-1 (bignum "1.4"))
     *   2.399999999999999911182158029987476766109E0
     *   > (add-1 (bignum "1.5+i"))
     *   2.500E0+1.000E0i
     */

In this example, we use Gtk to make a window with a scrolled text widget, running s7 in a read-eval-print loop. I've tried to make this as short as possible; see Snd for a much more elaborate REPL. From s7's point of view, the only tricky part involves catching errors.

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    /* use Gtk to post a text widget as a REPL.
     */
    #include <gtk/gtk.h>

    #if HAVE_GTK_3
      #include <gdk/gdk.h>
      #define Return_Key GDK_KEY_Return
    #else
      #include <gdk/gdkkeysyms.h>
      #define Return_Key GDK_Return
    #endif

    #include "s7.h"
    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    #define S7_PROMPT "s7> "
    #define S7_PROMPT_LENGTH 4

    static GtkWidget* repl;                        /* the REPL text widget */
    static GtkTextBuffer *repl_buf;                /* its text buffer */
    static GtkTextTag *prompt_not_editable = NULL; /* a tag to make sure the prompt can't be erased */

    static gint quit_repl(GtkWidget *w, GdkEvent *event, gpointer context)
    {
      /* called when we click the 'x' window decoration */
      exit(0);
    }

    static void evaluate_expression(s7_scheme *sc, char *expression)
    {
      /* evaluate expression, display result, catching and displaying any errors */
      if ((expression) &&
          (*expression))
        {
          if ((strlen(expression) > 1) ||
    	  (expression[0] != '\n'))
    	{
    	  const char *errmsg;
    	  int gc_loc = -1;
    	  s7_pointer old_port, result;
    	  GtkTextIter pos;

    	  /* open a port to catch error info */
    	  old_port = s7_set_current_error_port(sc, s7_open_output_string(sc));
    	  if (old_port != s7_nil(sc))
    	    gc_loc = s7_gc_protect(sc, old_port);

    	  result = s7_eval_c_string(sc, expression);

    	  errmsg = s7_get_output_string(sc, s7_current_error_port(sc));
    	  /* if error, display it, else display result of evaluation */
    	  gtk_text_buffer_get_end_iter(repl_buf, &pos);

    	  if ((errmsg) && (*errmsg))
    	    gtk_text_buffer_insert(repl_buf, &pos, errmsg, strlen(errmsg));
    	  else
    	    {
    	      char *result_as_string;
    	      result_as_string = s7_object_to_c_string(sc, result);
    	      if (result_as_string)
    		{
    		  gtk_text_buffer_insert(repl_buf, &pos, "\n", 1);
    		  gtk_text_buffer_insert(repl_buf, &pos, result_as_string, strlen(result_as_string));
    		  free(result_as_string);
    		}
    	    }

    	  s7_close_output_port(sc, s7_current_error_port(sc));
    	  s7_set_current_error_port(sc, old_port);
    	  if (gc_loc != -1)
    	    s7_gc_unprotect_at(sc, gc_loc);
    	}
          g_free(expression);
        }
    }

    static char *get_current_expression(void)
    {
      /* find the enclosing expression and return it.  This could be a lot smarter, but
       *    for the current example, I'll just look back to the previous prompt, then
       *    forward for the next prompt or the buffer end.
       */
      GtkTextIter pos, previous, next, temp;
      GtkTextMark *m;

      m = gtk_text_buffer_get_insert(repl_buf);
      gtk_text_buffer_get_iter_at_mark(repl_buf, &pos, m);

      if (gtk_text_iter_backward_search(&pos, S7_PROMPT, 0, &temp, &previous, NULL))
        {
          /* previous now marks the end of the previous prompt */
          if (!gtk_text_iter_forward_search(&pos, S7_PROMPT, 0, &next, &temp, NULL))
    	{
    	  gtk_text_buffer_get_end_iter(repl_buf, &next);
    	  /* next now marks the end of the buffer, so there's no complication */
    	  return(gtk_text_buffer_get_text(repl_buf, &previous, &next, true));
    	}
          /* here next marks the start of the next prompt, but that probably includes
           *   the result printout from an earlier evaluation.  s7_eval_c_string evaluates
           *   all the expressions in its string, returning the value of the last one,
           *   but we want the first.  We'll backup two '\n'.
           */
          gtk_text_iter_backward_search(&next, "\n", 0, &pos, &temp, NULL);
          gtk_text_iter_backward_search(&pos, "\n", 0, &next, &temp, NULL);
          return(gtk_text_buffer_get_text(repl_buf, &previous, &next, true));
        }
      return(NULL);
    }

    static gboolean repl_key_press(GtkWidget *w, GdkEventKey *event, gpointer data)
    {
      /* called when we type anything in the text widget.
       *   'data' is our s7 interpreter.
       */
      guint key;
      key = event->keyval;
      if (key == Return_Key)
        {
          GtkTextIter pos;
          /* get enclosing expression, evaluate it, display result (or error), prompt for next */
          evaluate_expression((s7_scheme *)data, get_current_expression());

          /* prompt for next expression */
          gtk_text_buffer_get_end_iter(repl_buf, &pos);
          gtk_text_buffer_insert_with_tags(repl_buf, &pos,
                                           "\n" S7_PROMPT, 1 + S7_PROMPT_LENGTH, prompt_not_editable, NULL);

          /* make sure the stuff we added is visible */
          gtk_text_buffer_place_cursor(repl_buf, &pos);
          gtk_text_view_scroll_mark_onscreen(GTK_TEXT_VIEW(repl), gtk_text_buffer_get_insert(repl_buf));

          /* tell Gtk that we already sent the '\n' */
          g_signal_stop_emission((gpointer)w,
                                 g_signal_lookup("key_press_event", G_OBJECT_TYPE((gpointer)w)), 0);
        }
      return(false);
    }

    int main(int argc, char **argv)
    {
      s7_scheme *s7;
      GtkWidget *shell, *scrolled_window;
      GtkTextIter pos;

      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      /* make a window with a scrolled text widget */
      gtk_init(&argc, &argv);
      shell = gtk_window_new(GTK_WINDOW_TOPLEVEL);
      g_signal_connect(G_OBJECT(shell), "delete_event", G_CALLBACK(quit_repl), NULL);

      scrolled_window = gtk_scrolled_window_new(NULL, NULL);
      gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(scrolled_window),
                                     GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC);
      gtk_container_add(GTK_CONTAINER(shell), scrolled_window);

      repl = gtk_text_view_new();
      repl_buf = gtk_text_buffer_new(NULL);
      gtk_container_add(GTK_CONTAINER(scrolled_window), repl);

      gtk_text_view_set_buffer(GTK_TEXT_VIEW(repl), repl_buf);
      gtk_text_view_set_editable(GTK_TEXT_VIEW(repl), true);
      gtk_text_view_set_wrap_mode(GTK_TEXT_VIEW(repl), GTK_WRAP_NONE);
      gtk_text_view_set_cursor_visible(GTK_TEXT_VIEW(repl), true);
      gtk_text_view_set_left_margin(GTK_TEXT_VIEW(repl), 4);

      /* whenever a key is pressed, call repl_key_press */
      gtk_widget_set_events(repl, GDK_ALL_EVENTS_MASK);
      g_signal_connect(G_OBJECT(repl), "key_press_event", G_CALLBACK(repl_key_press), (void *)s7);

      gtk_widget_show(repl);
      gtk_widget_show(scrolled_window);
      gtk_widget_show(shell);

      /* start with a boldface '>' prompt that can't be stepped on */
      prompt_not_editable = gtk_text_buffer_create_tag(repl_buf, "prompt_not_editable",
    						   "editable", false,
    						   "weight", PANGO_WEIGHT_BOLD,
    						   NULL);
      gtk_text_buffer_get_end_iter(repl_buf, &pos);
      gtk_text_buffer_insert_with_tags(repl_buf, &pos,
                                       S7_PROMPT, S7_PROMPT_LENGTH, prompt_not_editable, NULL);

      /* make the initial window size reasonable */
      gdk_window_resize(gtk_widget_get_window(shell), 400, 200);
      gtk_main();
    }

    /*
     *   gcc -c s7.c -I.
     *   gcc -o listener listener.c s7.o -lm -I. <insert all the gtk flags and libraries here>
     */

In the same vein, we can use libxm's Gtk/s7 bindings to make the REPL in Scheme. Here is the same code, but now using libxm; first the C side, called gtkex.c:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>

    #include <mus-config.h>
    #include "xen.h"
    void Init_libxg(void);

    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    int main(int argc, char **argv)
    {
      s7_scheme *s7;
      s7 = s7_init();             /* start s7 */
      s7_xen_initialize(s7);     /* start the xen connection to libxm */
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");
      Init_libxg();              /* load up all the glib/gdk/gtk/cairo/pango bindings in libxm */
      s7_load(s7, "gtkex.scm");  /* load and run our REPL (below) */
    }

    /*   libxm: configure --with-gtk, then make
     *   gcc -o gtkex gtkex.c libxg.so -lm -I.
     *   ;; you may need to include the libxm directory above
     */

And here is gtkex.scm. The main problem with this code is that Gtk is moving rapidly toward gtk3, and libxm is running along behind panting and complaining. There are several things that may change once Gtk settles down.

    (gtk_init 0 #f)

    (let ((shell (gtk_window_new GTK_WINDOW_TOPLEVEL))
          (s7-prompt "s7> ")
          (return-key (if (provided? 'gtk3) GDK_KEY_Return GDK_Return)))

      (g_signal_connect (G_OBJECT shell) "delete_event"
    		    (lambda (window event data)
    		      (gtk_main_quit)
    		      (exit)))
      (g_signal_connect (G_OBJECT shell) "destroy"
    		    (lambda (window data)
    		      (gtk_main_quit)
    		      (exit)))

      (let ((scrolled_window (gtk_scrolled_window_new #f #f)))

        (gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW scrolled_window)
                                        GTK_POLICY_AUTOMATIC GTK_POLICY_AUTOMATIC)
        (gtk_container_add (GTK_CONTAINER shell) scrolled_window)

        (let* ((repl (gtk_text_view_new))
    	   (repl_buf (gtk_text_buffer_new #f))
    	   (prompt_not_editable #f))

          (define (evaluate-expression expr)
    	(let ((pos (GtkTextIter))
    	      (result (catch #t
    			     (lambda ()
    			       (object->string (eval-string expr)))
    			     (lambda args
    			       (format #f "~A: ~S" (car args) (apply format #f (cadr args)))))))
    	  (gtk_text_buffer_get_end_iter repl_buf pos)
    	  (gtk_text_buffer_insert repl_buf pos "\n" 1)
    	  (gtk_text_buffer_insert repl_buf pos result (length result))))

          (define (get-current-expression)
    	(let ((m (gtk_text_buffer_get_insert repl_buf))
    	      (pos (GtkTextIter))
    	      (previous (GtkTextIter))
    	      (next (GtkTextIter))
    	      (temp (GtkTextIter)))
    	  (gtk_text_buffer_get_iter_at_mark repl_buf pos m)
    	  (if (gtk_text_iter_backward_search pos s7-prompt 0 temp previous #f)
    	      (if (not (gtk_text_iter_forward_search pos s7-prompt 0 next temp #f))
    		  (begin
    		    (gtk_text_buffer_get_end_iter repl_buf next)
    		    (gtk_text_buffer_get_text repl_buf previous next #t))
    		  (begin
    		    (gtk_text_iter_backward_search next "\n" 0 pos temp #f)
    		    (gtk_text_iter_backward_search pos "\n" 0 next temp #f)
    		    (gtk_text_buffer_get_text repl_buf previous next #t)))
    	      "")))

          (define (repl-key-press w event data)
    	(let ((key (gtk_event_keyval event)))
    	  (if (equal? key return-key)
    	      (let ((pos (GtkTextIter)))

    		(evaluate-expression (get-current-expression))

    		(gtk_text_buffer_get_end_iter repl_buf pos)
    		(gtk_text_buffer_insert_with_tags repl_buf pos
    						  (string-append (string #\newline) s7-prompt)
    						  (+ 1  (length s7-prompt))
    						  (list prompt_not_editable))
    		(gtk_text_buffer_place_cursor repl_buf pos)
    		(gtk_text_view_scroll_mark_onscreen (GTK_TEXT_VIEW repl)
    						    (gtk_text_buffer_get_insert repl_buf))
    		(g_signal_stop_emission (GPOINTER w)
    					(g_signal_lookup "key_press_event"
    							 (G_OBJECT_TYPE (G_OBJECT w)))
    					0)))))

          (gtk_container_add (GTK_CONTAINER scrolled_window) repl)
          (gtk_text_view_set_buffer (GTK_TEXT_VIEW repl) repl_buf)
          (gtk_text_view_set_editable (GTK_TEXT_VIEW repl) #t)
          (gtk_text_view_set_wrap_mode (GTK_TEXT_VIEW repl) GTK_WRAP_NONE)
          (gtk_text_view_set_cursor_visible (GTK_TEXT_VIEW repl) #t)
          (gtk_text_view_set_left_margin (GTK_TEXT_VIEW repl) 4)

          (gtk_widget_set_events repl GDK_ALL_EVENTS_MASK)
          (g_signal_connect (G_OBJECT repl) "key_press_event" repl-key-press)

          (gtk_widget_show repl)
          (gtk_widget_show scrolled_window)
          (gtk_widget_show shell)

          (set! prompt_not_editable
    	    (gtk_text_buffer_create_tag repl_buf "prompt_not_editable"
    					(list "editable" 0 "weight" PANGO_WEIGHT_BOLD)))
          (let ((pos (GtkTextIter)))
    	(gtk_text_buffer_get_end_iter repl_buf pos)
    	(gtk_text_buffer_insert_with_tags repl_buf pos
    					  s7-prompt (length s7-prompt)
    					  (list prompt_not_editable))
    	(gdk_window_resize (gtk_widget_get_window shell) 400 200)
    	(gtk_main)))))

    ;; build gtkex as above, then run it and it will load/run this code

There is one major flaw in the two preceding REPLs; if s7 gets caught in an infinite loop (via `(do () ())` for example), you have to kill the main program to stop it. We could use Unix interrupts as in the signal example earlier, but surely in a modern GUI-based program, we'd like to avoid such brute-force stuff. In particular, we want our interface to keep running while we clean up the s7 problem. So, in the next example, we use a separate thread for the s7 evaluation:

    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>
    /* changes from the Gtk/C REPL above are in red */
    #include <pthread.h>
    #include <gtk/gtk.h>

    #if HAVE_GTK_3
      #include <gdk/gdk.h>
      #define Return_Key GDK_KEY_Return
      #define C_Key GDK_KEY_C
      #define c_Key GDK_KEY_c
    #else
      #include <gdk/gdkkeysyms.h>
      #define Return_Key GDK_Return
      #define C_Key GDK_C
      #define c_Key GDK_c
    #endif

    #include "s7.h"
    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    #define S7_PROMPT "s7> "
    #define S7_PROMPT_LENGTH 4

    static GtkWidget* repl;                        /* the REPL text widget */
    static GtkTextBuffer *repl_buf;                /* its text buffer */
    static GtkTextTag *prompt_not_editable = NULL; /* a tag to make sure the prompt can't be erased */
    static GdkCursor *arrow, *spinner;

    static gint quit_repl(GtkWidget *w, GdkEvent *event, gpointer context) {exit(0);}

    static s7_scheme *s7;
    static s7_pointer s7_result;
    static bool just_quit = false, s7_is_running = false;
    static pthread_t *s7_thread;

    static void *run_s7_thread(void *obj)
    {
      /* make sure we can stop this thread */
      pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
      pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, NULL);

      s7_result = s7_eval_c_string(s7, (const char *)obj);
      s7_is_running = false;
      return(NULL);
    }

    static void evaluate_expression(s7_scheme *sc, char *expression)
    {
      /* evaluate expression, display result, catching and displaying any errors */
      if ((expression) &&
          (*expression))
        {
          if ((strlen(expression) > 1) ||
    	  (expression[0] != '\n'))
    	{
    	  const char *errmsg = NULL;
    	  int gc_loc;
    	  s7_pointer old_port;
    	  GtkTextIter pos;

    	  /* open a port to catch error info */
    	  old_port = s7_set_current_error_port(sc, s7_open_output_string(sc));
    	  gc_loc = s7_gc_protect(sc, old_port);

    	  /* evaluate the expression in a separate thread */
    	  s7_thread = (pthread_t *)calloc(1, sizeof(pthread_t));
    	  just_quit = false;
    	  s7_is_running = true;
    	  gdk_window_set_cursor(gtk_text_view_get_window(GTK_TEXT_VIEW(repl), GTK_TEXT_WINDOW_TEXT), spinner);

    	  pthread_create(s7_thread, NULL, run_s7_thread, (void *)expression);

    	  while (s7_is_running)
    	    gtk_main_iteration();   /* make sure the GUI is responsive */

    	  if (!just_quit)
    	    {
    	      pthread_join(*s7_thread, NULL);
    	      free(s7_thread);
    	      s7_thread = NULL;
    	      gdk_window_set_cursor(gtk_text_view_get_window(GTK_TEXT_VIEW(repl), GTK_TEXT_WINDOW_TEXT), arrow);
    	      errmsg = s7_get_output_string(sc, s7_current_error_port(sc));
    	    }
    	  else errmsg = "\ngot C-C!";

    	  /* if error, display it, else display result of evaluation */
    	  gtk_text_buffer_get_end_iter(repl_buf, &pos);

    	  if ((errmsg) && (*errmsg))
    	    gtk_text_buffer_insert(repl_buf, &pos, errmsg, strlen(errmsg));
    	  else
    	    {
    	      char *result_as_string;
    	      result_as_string = s7_object_to_c_string(sc, s7_result);
    	      if (result_as_string)
    		{
    		  gtk_text_buffer_insert(repl_buf, &pos, "\n", 1);
    		  gtk_text_buffer_insert(repl_buf, &pos, result_as_string, strlen(result_as_string));
    		  free(result_as_string);
    		}
    	    }
    	  s7_close_output_port(sc, s7_current_error_port(sc));
    	  s7_set_current_error_port(sc, old_port);
    	  s7_gc_unprotect_at(sc, gc_loc);
    	}
          g_free(expression);
        }
    }

    static char *get_current_expression(void)
    {
      GtkTextIter pos, previous, next, temp;
      GtkTextMark *m;

      m = gtk_text_buffer_get_insert(repl_buf);
      gtk_text_buffer_get_iter_at_mark(repl_buf, &pos, m);

      if (gtk_text_iter_backward_search(&pos, S7_PROMPT, 0, &temp, &previous, NULL))
        {
          if (!gtk_text_iter_forward_search(&pos, S7_PROMPT, 0, &next, &temp, NULL))
    	{
    	  gtk_text_buffer_get_end_iter(repl_buf, &next);
    	  return(gtk_text_buffer_get_text(repl_buf, &previous, &next, true));
    	}
          gtk_text_iter_backward_search(&next, "\n", 0, &pos, &temp, NULL);
          gtk_text_iter_backward_search(&pos, "\n", 0, &next, &temp, NULL);
          return(gtk_text_buffer_get_text(repl_buf, &previous, &next, true));
        }
      return(NULL);
    }

    static void prompt(GtkWidget *w)
    {
      GtkTextIter pos;

      gtk_text_buffer_get_end_iter(repl_buf, &pos);
      gtk_text_buffer_insert_with_tags(repl_buf, &pos, "\n" S7_PROMPT, 1 + S7_PROMPT_LENGTH, prompt_not_editable, NULL);

      gtk_text_buffer_place_cursor(repl_buf, &pos);
      gtk_text_view_scroll_mark_onscreen(GTK_TEXT_VIEW(repl), gtk_text_buffer_get_insert(repl_buf));

      g_signal_stop_emission((gpointer)w, g_signal_lookup("key_press_event", G_OBJECT_TYPE((gpointer)w)), 0);
    }

    static gboolean repl_key_press(GtkWidget *w, GdkEventKey *event, gpointer data)
    {
      /* called when you type anything in the text widget.
       *   'data' is our s7 interpreter.
       */
      guint key, state;
      key = event->keyval;
      state = event->state;

      if (key == Return_Key)
        {
          if (!s7_is_running)
    	evaluate_expression((s7_scheme *)data, get_current_expression());
          prompt(w);
        }

      /* if C-C typed, and s7 is running, we're trying to break out of a loop */
      if (((key == C_Key) || (key == c_Key)) &&
          ((state & GDK_CONTROL_MASK) != 0) &&
          (s7_is_running))
        {
          just_quit = true;
          pthread_cancel(*s7_thread);
          pthread_detach(*s7_thread);
          s7_is_running = false;
          s7_quit(s7);
          free(s7_thread);
          s7_thread = NULL;
          gdk_window_set_cursor(gtk_text_view_get_window(GTK_TEXT_VIEW(repl), GTK_TEXT_WINDOW_TEXT), arrow);
          prompt(w);
        }

      return(false);
    }

    int main(int argc, char **argv)
    {
      GtkWidget *shell, *scrolled_window;
      GtkTextIter pos;

      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      /* make a window with a scrolled text widget */
      gtk_init(&argc, &argv);

      spinner = gdk_cursor_new(GDK_WATCH);
      arrow = gdk_cursor_new(GDK_LEFT_PTR);

      shell = gtk_window_new(GTK_WINDOW_TOPLEVEL);
      g_signal_connect(G_OBJECT(shell), "delete_event", G_CALLBACK(quit_repl), NULL);

      scrolled_window = gtk_scrolled_window_new(NULL, NULL);
      gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(scrolled_window), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC);
      gtk_container_add(GTK_CONTAINER(shell), scrolled_window);

      repl = gtk_text_view_new();
      repl_buf = gtk_text_buffer_new(NULL);
      gtk_container_add(GTK_CONTAINER(scrolled_window), repl);

      gtk_text_view_set_buffer(GTK_TEXT_VIEW(repl), repl_buf);
      gtk_text_view_set_editable(GTK_TEXT_VIEW(repl), true);
      gtk_text_view_set_wrap_mode(GTK_TEXT_VIEW(repl), GTK_WRAP_NONE);
      gtk_text_view_set_cursor_visible(GTK_TEXT_VIEW(repl), true);
      gtk_text_view_set_left_margin(GTK_TEXT_VIEW(repl), 4);

      /* whenever a key is pressed, call repl_key_press */
      gtk_widget_set_events(repl, GDK_ALL_EVENTS_MASK);
      g_signal_connect(G_OBJECT(repl), "key_press_event", G_CALLBACK(repl_key_press), (void *)s7);

      gtk_widget_show(repl);
      gtk_widget_show(scrolled_window);
      gtk_widget_show(shell);

      /* start with a boldface '>' prompt that can't be stepped on */
      prompt_not_editable = gtk_text_buffer_create_tag(repl_buf, "prompt_not_editable",
    						   "editable", false,
    						   "weight", PANGO_WEIGHT_BOLD,
    						   NULL);
      gtk_text_buffer_get_end_iter(repl_buf, &pos);
      gtk_text_buffer_insert_with_tags(repl_buf, &pos, S7_PROMPT, S7_PROMPT_LENGTH, prompt_not_editable, NULL);

      /* make the initial window size reasonable */
      gdk_window_resize(gtk_widget_get_window(shell), 400, 200);
      gtk_main();
    }

This code still has a flaw. Any GUI callback can call s7_call or s7_eval_c_string directly. In the code above, if the listener starts a long evaluation (or falls into an infinite loop), and we start idly poking around with the mouse, waiting for the evaluation to finish, a mouse or menu callback can trigger a call on the same s7 interpreter that is currently running in the listener. We are trying to evaluate two different expressions at the same time! What you get depends on where s7 notices the problem. If the evaluator senses that it is lost, it will raise some confusing error; otherwise the s7 stack will cause a segfault. We need the GUI to stay active so that we can interrupt computation by typing C-C. We can't sort through all the events dispatching only the C-C, because that confuses subsequent GUI actions, and the whole idea here is to keep the interface alive. We can put the listener's s7_eval_c_string in a separate s7 thread so that the multiple evaluations can be interleaved, but those evaluations can still make calls into Gtk or Motif, and unfortunately, neither GUI toolkit is thread-safe. If two threads invoke a GUI function, you get a segfault or some other bizarre screwup. In Gtk, we have to wrap gdk_threads_enter and gdk_threads_leave around any code that calls into Gtk. We'd set it up by adding

      g_thread_init(NULL);
      gdk_threads_init();
      gdk_threads_enter();

at the very start of our program, and gdk_threads_leave() at the very end. Then whenever an s7 call might involve Gtk, we wrap it within gdk_threads_enter() and gdk_threads_leave(). We can't just wrap the outer s7_eval_c_string call above, because that locks out the keyboard, and the whole point was to catch C-C while in the s7 evaluation. But in Snd, where both normal functions and gtk callbacks can trigger arbitrary Scheme code, it would be completely unreasonable to wrap these thread handlers around every bit of code that might touch the user interface (consider the xg module!). So...

Common Lisp has something called "evalhook" that makes it possible to insert your own function into eval. In s7, we have a "begin_hook" which sits at the opening of any begin block (implicit or explicit). Here are two REPLs, one for Gtk, and one for a bare terminal.

    /* 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 s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    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 bool watch_for_c_g(s7_scheme *sc)
    {
      char c;
      bool all_done = false;
      /* 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);
      return(all_done);
    }

    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;         /* if no chars waiting, just return */
          buf.c_cc[VTIME] = 0;

          signal(SIGINT, sigcatch);
          signal(SIGQUIT, sigcatch);
          signal(SIGTERM, sigcatch);
        }

      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      if (argc == 2)
        {
          fprintf(stderr, "load %s\n", argv[1]);
          s7_load(s7, 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))
    	    {
    	      sprintf(response, "(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);
    }

    /* Gtk-based REPL using s7_begin_hook
     */
    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>
    #include <gtk/gtk.h>

    #if HAVE_GTK_3
      #include <gdk/gdk.h>
      #define Return_Key GDK_KEY_Return
      #define C_Key GDK_KEY_C
      #define c_Key GDK_KEY_c
    #else
      #include <gdk/gdkkeysyms.h>
      #define Return_Key GDK_Return
      #define C_Key GDK_C
      #define c_Key GDK_c
    #endif

    #include "s7.h"
    static s7_pointer my_exit(s7_scheme *sc, s7_pointer args) {exit(0);}

    #define S7_PROMPT "s7> "
    #define S7_PROMPT_LENGTH 4
    #define S7_INTERRUPTED_MESSAGE "\ns7 interrupted!"

    static GtkWidget* repl;                        /* the REPL text widget */
    static GtkTextBuffer *repl_buf;                /* its text buffer */
    static GtkTextTag *prompt_not_editable = NULL; /* a tag to make sure the prompt can't be erased */
    static GdkCursor *arrow, *spinner;

    static gint quit_repl(GtkWidget *w, GdkEvent *event, gpointer context) {exit(0);}

    static bool C_c_typed = false;

    static bool begin_hook(s7_scheme *sc)
    {
      C_c_typed = false;
      if (gtk_events_pending()) /* this is very slow -- see snd-listener.c for a work-around */
        gtk_main_iteration();
      return(C_c_typed);
    }

    static void evaluate_expression(s7_scheme *sc, char *expression)
    {
      /* evaluate expression, display result, catching and displaying any errors */
      if ((expression) &&
          (*expression))
        {
          if ((strlen(expression) > 1) ||
    	  (expression[0] != '\n'))
    	{
    	  const char *errmsg = NULL;
    	  int gc_loc;
    	  s7_pointer old_port, result;
    	  GtkTextIter pos;

    	  old_port = s7_set_current_error_port(sc, s7_open_output_string(sc));
    	  gc_loc = s7_gc_protect(sc, old_port);
    	  gdk_window_set_cursor(gtk_text_view_get_window(GTK_TEXT_VIEW(repl), GTK_TEXT_WINDOW_TEXT), spinner);

    	  s7_set_begin_hook(sc, begin_hook);
    	  result = s7_eval_c_string(sc, expression);
    	  s7_set_begin_hook(sc, NULL);

    	  gdk_window_set_cursor(gtk_text_view_get_window(GTK_TEXT_VIEW(repl), GTK_TEXT_WINDOW_TEXT), arrow);
    	  gtk_text_buffer_get_end_iter(repl_buf, &pos);

    	  if (C_c_typed)
    	    {
    	      gtk_text_buffer_insert(repl_buf, &pos, S7_INTERRUPTED_MESSAGE, strlen(S7_INTERRUPTED_MESSAGE));
    	      C_c_typed = false;
    	    }
    	  else
    	    {
    	      errmsg = s7_get_output_string(sc, s7_current_error_port(sc));
    	      if ((errmsg) && (*errmsg))
    		gtk_text_buffer_insert(repl_buf, &pos, errmsg, strlen(errmsg));
    	      else
    		{
    		  char *result_as_string;
    		  result_as_string = s7_object_to_c_string(sc, result);
    		  if (result_as_string)
    		    {
    		      gtk_text_buffer_insert(repl_buf, &pos, "\n", 1);
    		      gtk_text_buffer_insert(repl_buf, &pos, result_as_string, strlen(result_as_string));
    		      free(result_as_string);
    		    }
    		}
    	    }

    	  s7_close_output_port(sc, s7_current_error_port(sc));
    	  s7_set_current_error_port(sc, old_port);
    	  s7_gc_unprotect_at(sc, gc_loc);
    	}

          g_free(expression);
        }
    }

    static char *get_current_expression(void)
    {
      GtkTextIter pos, previous, next, temp;
      GtkTextMark *m;
      m = gtk_text_buffer_get_insert(repl_buf);
      gtk_text_buffer_get_iter_at_mark(repl_buf, &pos, m);
      if (gtk_text_iter_backward_search(&pos, S7_PROMPT, 0, &temp, &previous, NULL))
        {
          if (!gtk_text_iter_forward_search(&pos, S7_PROMPT, 0, &next, &temp, NULL))
    	{
    	  gtk_text_buffer_get_end_iter(repl_buf, &next);
    	  return(gtk_text_buffer_get_text(repl_buf, &previous, &next, true));
    	}
          gtk_text_iter_backward_search(&next, "\n", 0, &pos, &temp, NULL);
          gtk_text_iter_backward_search(&pos, "\n", 0, &next, &temp, NULL);
          return(gtk_text_buffer_get_text(repl_buf, &previous, &next, true));
        }
      return(NULL);
    }

    static void prompt(GtkWidget *w)
    {
      GtkTextIter pos;
      gtk_text_buffer_get_end_iter(repl_buf, &pos);
      gtk_text_buffer_insert_with_tags(repl_buf, &pos, "\n" S7_PROMPT, 1 + S7_PROMPT_LENGTH, prompt_not_editable, NULL);
      gtk_text_buffer_place_cursor(repl_buf, &pos);
      gtk_text_view_scroll_mark_onscreen(GTK_TEXT_VIEW(repl), gtk_text_buffer_get_insert(repl_buf));
      g_signal_stop_emission((gpointer)w, g_signal_lookup("key_press_event", G_OBJECT_TYPE((gpointer)w)), 0);
    }

    static gboolean repl_key_press(GtkWidget *w, GdkEventKey *event, gpointer data)
    {
      /* called when you type anything in the text widget.
       *   'data' is our s7 interpreter.
       */
      guint key, state;
      s7_scheme *sc;

      sc = (s7_scheme *)data;
      key = event->keyval;
      state = event->state;

      if (key == Return_Key)
        {
          if (s7_begin_hook(sc) == NULL)
    	{
    	  evaluate_expression(sc, get_current_expression());
    	  prompt(w);
    	}
        }

      if (((key == C_Key) || (key == c_Key)) &&
          ((state & GDK_CONTROL_MASK) != 0))
        C_c_typed = true;

      return(false);
    }

    int main(int argc, char **argv)
    {
      GtkWidget *shell, *scrolled_window;
      GtkTextIter pos;
      s7_scheme *s7;

      s7 = s7_init();
      s7_define_function(s7, "exit", my_exit, 0, 0, false, "(exit) exits the program");

      gtk_init(&argc, &argv);
      spinner = gdk_cursor_new(GDK_WATCH);
      arrow = gdk_cursor_new(GDK_LEFT_PTR);

      shell = gtk_window_new(GTK_WINDOW_TOPLEVEL);
      g_signal_connect(G_OBJECT(shell), "delete_event", G_CALLBACK(quit_repl), NULL);

      scrolled_window = gtk_scrolled_window_new(NULL, NULL);
      gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(scrolled_window), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC);
      gtk_container_add(GTK_CONTAINER(shell), scrolled_window);

      repl = gtk_text_view_new();
      repl_buf = gtk_text_buffer_new(NULL);
      gtk_container_add(GTK_CONTAINER(scrolled_window), repl);

      gtk_text_view_set_buffer(GTK_TEXT_VIEW(repl), repl_buf);
      gtk_text_view_set_editable(GTK_TEXT_VIEW(repl), true);
      gtk_text_view_set_wrap_mode(GTK_TEXT_VIEW(repl), GTK_WRAP_NONE);
      gtk_text_view_set_cursor_visible(GTK_TEXT_VIEW(repl), true);
      gtk_text_view_set_left_margin(GTK_TEXT_VIEW(repl), 4);
      gtk_widget_set_events(repl, GDK_ALL_EVENTS_MASK);
      g_signal_connect(G_OBJECT(repl), "key_press_event", G_CALLBACK(repl_key_press), (void *)s7);

      gtk_widget_show(repl);
      gtk_widget_show(scrolled_window);
      gtk_widget_show(shell);

      prompt_not_editable = gtk_text_buffer_create_tag(repl_buf, "prompt_not_editable",
    						   "editable", false,
    						   "weight", PANGO_WEIGHT_BOLD,
    						   NULL);
      gtk_text_buffer_get_end_iter(repl_buf, &pos);
      gtk_text_buffer_insert_with_tags(repl_buf, &pos, S7_PROMPT, S7_PROMPT_LENGTH, prompt_not_editable, NULL);
      gdk_window_resize(gtk_widget_get_window(shell), 400, 200);
      gtk_main();
    }

In the Gtk case above, begin_hook itself checks the user-interface (via gtk_main_iteration), so a key_press event (or any other) can still get through, even if s7_eval_c_string falls into an infinite loop. If a GUI event triggers a call on s7, that call happens in the current thread at a protected point in the s7 evaluation, so the GUI toolkit is happy because there's only the current thread, and s7 is happy because it handles the interleaved expression at a point where it can't confuse the current evaluation. If the begin_hook function returns true (if C-C is typed), s7 itself calls s7_quit, interrupting the current evaluation. If return is typed, and s7 is running (begin_hook is not NULL), we ignore it. Otherwise return causes our REPL to send the current string to s7_eval_c_string. Upon returning from s7_eval_c_string, we check whether we were interrupted (C_c_typed is true), and if so, send a surprised message to the REPL. Otherwise we handle everything as in the previous REPLs.

If the s7 evaluation can't affect the GUI and the GUI can't call s7 itself, then you don't need to use begin_hook.

begin_hook provides a way to call arbitrary C or Scheme code at any time; the mind boggles! In the Snd listener, for example, you can ask for a stack trace to see if your long computation is making progress. Since the normal begin_hook function keeps the interface alive, a callback can save the current begin_hook function, insert its own function to do something useful, then that function can replace itself with the original:

    static bool (*current_begin_hook)(s7_scheme *sc);       /* this will be the saved original function */

    static bool stacktrace_begin_hook(s7_scheme *sc)        /* this is our one-shot replacement */
    {
      s7_stacktrace(sc, s7_name_to_value(sc, "*stderr*"));  /* it prints a stacktrace */
      s7_set_begin_hook(s7, current_begin_hook);            /*   then replaces itself with the original */
      return(false);
    }

    static void listener_stacktrace_callback(...)           /* the usual callback boilerplate here */
    {
      current_begin_hook = s7_begin_hook(s7);               /* save current begin_hook function */
      if (current_begin_hook)                               /* s7 is running, so... */
        s7_set_begin_hook(s7, stacktrace_begin_hook);       /*   insert our stacktrace function in its place */
    }