Scm is a portable Scheme implementation written in C. Scm provides a machine independent platform for [JACAL], a symbolic algebra system.
The most recent information about SCM can be found on SCM's WWW home page:
http://www-swiss.ai.mit.edu/~jaffer/SCM.html
COPYRIGHT (c) 1989 BY PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS. ALL RIGHTS RESERVED
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Paradigm Associates Inc not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.
PARADIGM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL PARADIGM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
gjc@paradigm.com
Phone: 617-492-6079
Paradigm Associates Inc 29 Putnam Ave, Suite 6 Cambridge, MA 02138
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA
Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.
NO WARRANTY
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
logand, logor, logxor,
lognot, ash, logcount, integer-length,
bit-extract, defmacro, macroexpand,
macroexpand1, gentemp, defvar, force-output,
software-type, get-decoded-time,
get-internal-run-time, get-internal-real-time,
delete-file, rename-file, copy-tree, acons,
and eval.
Char-code-limit, most-positive-fixnum,
most-negative-fixnum, and internal-time-units-per-second
constants. *Features* and *load-pathname* variables.
verbose function).
Restart, quit, and exec.
gsubrs, compiled closures, and records.
There are many other contributors to SCM. They are acknowledged in the file `ChangeLog', a log of changes that have been made to scm.
scm extensions (beyond Scheme standards).
Documentation on the internal representation and how to extend or
include scm in other programs.
The SCM distribution has Makefile which contains rules for making scmlit, a "bare-bones" version of SCM sufficient for running `build.scm'. `build.scm' is used to compile (or create scripts to compile) full featured versions.
Makefiles are not portable to the majority of platforms. If `Makefile' works for you, good; If not, I don't want to hear about it. If you need to compile SCM without build.scm, there are several ways to proceed:
[SLIB] is a portable Scheme library meant to provide compatibility and utility functions for all standard Scheme implementations. Although SLIB is not neccessary to run SCM, I strongly suggest you obtain and install it. Bug reports about running SCM without SLIB have very low priority. SLIB is available from the same sites as SCM:
ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c0.tar.gz
Unpack SLIB (`tar xzf slib2c0.tar.gz' or `unzip -ao
slib2c0.zip') in an appropriate directory for your system; both
tar and unzip will create the directory `slib'.
Then create a file `require.scm' in the SCM implementation-vicinity (this is the same directory as where the file `Init.scm' is installed). `require.scm' should have the contents:
(define (library-vicinity) "/usr/local/lib/slib/") (load (in-vicinity (library-vicinity) "require"))
where the pathname string `/usr/local/lib/slib/' is to be replaced by the pathname into which you installed SLIB. Absolute pathnames are recommended here; if you use a relative pathname, SLIB can get confused when the working directory is changed (see section I/O-Extensions). The way to specify a relative pathname is to append it to the implementation-vicinity, which is absolute:
(define library-vicinity
(let ((lv (string-append (implementation-vicinity) "../slib/")))
(lambda () lv)))
(load (in-vicinity (library-vicinity) "require"))
Alternatively, you can set the (shell) environment variable
SCHEME_LIBRARY_PATH to the pathname of the SLIB directory
(see section Environment Variables). If
set, the environment variable overrides `require.scm'. Again,
absolute pathnames are recommended.
The file build.scm builds and runs a relational database of how to compile and link SCM executables. It has information for most platforms which SCM has been ported to (of which I have been notified). Some of this information is old, incorrect, or incomplete. Send corrections and additions to jaffer@ai.mit.edu.
The all method will also work for MS-DOS and unix. Use the all method if you encounter problems with `build.scm'.
(load "build.scm"). Alternatively, start `scm' or
`scmlit' with the command line argument `-ilbuild'.
Invoking build without the `-F' option will build or create a shell
script with the arrays, inexact, and bignums
options as defaults.
bash$ ./build.scm
-|
#!/bin/sh
rm -f scmflags.h
echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \
eval.c sys.c subr.c unif.c rope.c
gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \
repl.o scl.o eval.o sys.o subr.o unif.o rope.o -lm -lc
To cross compile for another platform, invoke build with the `-p' or `---platform=' option. This will create a script for the platform named in the `-p' or `---platform=' option.
bash$ ./build.scm -p vms
-|
$DELETE scmflags.h
$CREATE scmflags.h
$DECK
#define IMPLINIT "/home/jaffer/scm/Init.scm"
#define BIGNUMS
#define FLOATS
#define ARRAYS
$EOD
$ cc continue scm findexec script time repl scl eval sys subr unif rope
$ macro setjump
$ link continue,scm,findexec,script,time,repl,scl,eval,sys,subr,unif,rope,setjump,sys$input/opt
-lc,sys$share:vaxcrtl/share
$RENAME continue.exe scm.exe
The options to build specify what, where, and how to build a SCM program or dynamically linked module. These options are unrelated to the SCM command line options.
The platforms defined by table platform in `build.scm' are:
name processor operating-system compiler symbol processor-family operating-system symbol symbol atom symbol symbol ================= ================= ================= ================= *unknown* *unknown* unix *unknown* acorn-unixlib acorn *unknown* *unknown* aix powerpc aix *unknown* amiga-aztec m68000 amiga aztec amiga-dice-c m68000 amiga dice-c amiga-gcc m68000 amiga gcc amiga-sas/c-5.10 m68000 amiga sas/c atari-st-gcc m68000 atari.st gcc atari-st-turbo-c m68000 atari.st turbo-c borland-c-3.1 8086 ms-dos borland-c djgpp i386 ms-dos gcc gcc *unknown* unix gcc highc.31 i386 ms-dos highc hp-ux hp-risc hp-ux *unknown* linux i386 linux gcc linux-aout i386 linux gcc microsoft-c 8086 ms-dos microsoft-c microsoft-c-nt i386 ms-dos microsoft-c microsoft-quick-c 8086 ms-dos microsoft-quick-c ms-dos 8086 ms-dos *unknown* os/2-cset i386 os/2 c-set++ os/2-emx i386 os/2 gcc sunos sparc sunos *unknown* svr4 *unknown* unix *unknown* turbo-c-2 8086 ms-dos turbo-c unicos cray unicos *unknown* unix *unknown* unix *unknown* vms vax vms *unknown* vms-gcc vax vms gcc watcom-9.0 i386 ms-dos watcom
The default is to build an executable.
system procedure.
(current-output-port).
-g flags for debugging SCM source
code.
(eq? '() '#f) is the major difference.
make_gsubr for arbitrary (< 11) arguments to C functions.
A correspondent asks:
How can we link in our own c files to the SCM interpreter so that we can add our own functionality? (e.g. we have a bunch of tcp functions we want access to). Would this involve changing build.scm or the Makefile or both?
(see section Changing Scm has instructions describing the C code format). Suppose a C file foo.c has functions you wish to add to SCM. To compile and link your file at compile time, use the `-c' and `-i' options to build:
bash$ build -c foo.c -i init_foo
-|
#!/bin/sh
rm -f scmflags.h
echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
echo '#define COMPILED_INITS init_foo();'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \
eval.c sys.c subr.c unif.c rope.c foo.c
gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \
repl.o scl.o eval.o sys.o subr.o unif.o rope.o foo.o -lm -lc
To make a dynamically loadable object file use the -t dll option:
bash$ build -t dll -c foo.c -| #!/bin/sh rm -f scmflags.h echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h echo '#define DLL'>>scmflags.h gcc -O2 -fpic -c foo.c gcc -shared -o foo.so foo.o -lm -lc
Once `foo.c' compiles correctly (and your SCM build supports
dynamic-loading), you can load the compiled file with the Scheme command
(load "./foo.so"). See section Configure Module Catalog for how to
add a compiled dll file to SLIB's catalog.
Dynamic linking has not been ported to all platforms. Operating systems
in the BSD family (a.out binary format) can usually be ported to
DLD. The dl library (#define SUN_DL for SCM) was a
proposed POSIX standard and may be available on other machines with
COFF binary format. For notes about porting to MS-Windows and
finishing the port to VMS section Finishing Dynamic Linking.
DLD is a library package of C functions that performs dynamic link editing on Linux, VAX (Ultrix), Sun 3 (SunOS 3.4 and 4.0), SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and Atari ST. It is available from:
prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz
These notes about using libdl on SunOS are from `gcc.info':
On a Sun, linking using GNU CC fails to find a shared library and reports that the library doesn't exist at all.
This happens if you are using the GNU linker, because it does only static linking and looks only for unshared libraries. If you have a shared library with no unshared counterpart, the GNU linker won't find anything.
We hope to make a linker which supports Sun shared libraries, but please don't ask when it will be finished--we don't know.
Sun forgot to include a static version of `libdl.a' with some versions of SunOS (mainly 4.1). This results in undefined symbols when linking static binaries (that is, if you use `-static'). If you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when linking, compile and link against the file `mit/util/misc/dlsym.c' from the MIT version of X windows.
The SLIB module catalog can be extended to define other
require-able packages by adding calls to the Scheme source file
`mkimpcat.scm'. Within `mkimpcat.scm', the following
procedures are defined.
#f.
If object-file exists, the add-link procedure registers
symbol feature so that the first time require is called
with the symbol feature as its argument, object-file and the
lib1 ... are dynamically linked into the executing SCM
session.
If object-file exists, add-link returns #t,
otherwise it returns #f.
For example, to install a compiled dll `foo', add these lines to `mkimpcat.scm':
(add-link 'foo
(in-vicinity (implementation-vicinity) "foo"
link:able-suffix))
add-alias registers alias as an alias for feature.
An unspecified value is returned.
add-alias causes (require 'alias) to behave like
(require 'feature).
add-source
registers feature so that the first time require is called
with the symbol feature as its argument, the file filename
will be loaded. An unspecified value is returned.
Remember to delete the file `slibcat' after modifying the file `mkimpcat.scm' in order to force SLIB to rebuild its cache.
In SCM, the ability to save running program images is called dump
(see section Dump). In order to make dump available to SCM, build
with feature `dump'. dumped executables are compatible with
dynamic linking.
Most of the code for dump is taken from `emacs-19.34/src/unex*.c'. No modifications to the emacs source code were required to use `unexelf.c'. Dump has not been ported to all platforms. If `unexec.c' or `unexelf.c' don't work for you, try using the appropriate `unex*.c' file from emacs.
These `#defines' are automatically provided by preprocessors of
various C compilers. SCM uses the presence or absence of these
definitions to configure include file locations and aliases for
library functions. If the definition(s) corresponding to your system
type is missing as your system is configured, add -Dflag to
the compilation command lines or add a #define flag line to
`scmfig.h' or the beginning of `scmfig.h'.
#define Platforms: ------- ---------- ARM_ULIB Huw Rogers free unix library for acorn archimedes AZTEC_C Aztec_C 5.2a _DCC Dice C on AMIGA __GNUC__ Gnu CC (and DJGPP) __EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0 __HIGHC__ MetaWare High C __IBMC__ C-Set++ on OS/2 2.1 _MSC_VER MS VisualC++ 4.2 MWC Mark Williams C on COHERENT _QC Microsoft QuickC __STDC__ ANSI C compliant __TURBOC__ Turbo C and Borland C __WATCOMC__ Watcom C on MS-DOS __ZTC__ Zortech C _AIX AIX operating system AMIGA SAS/C 5.10 or Dice C on AMIGA __amigados__ Gnu CC on AMIGA atarist ATARI-ST under Gnu CC GNUDOS DJGPP (obsolete in version 1.08) __GO32__ DJGPP (future?) hpux HP-UX linux Linux MCH_AMIGA Aztec_c 5.2a on AMIGA MSDOS Microsoft C 5.10 and 6.00A __MSDOS__ Turbo C, Borland C, and DJGPP nosve Control Data NOS/VE SVR2 System V Revision 2. __svr4__ SunOS THINK_C developement environment for the Macintosh ultrix VAX with ULTRIX operating system. unix most Unix and similar systems and DJGPP (!?) __unix__ Gnu CC and DJGPP _UNICOS Cray operating system vaxc VAX C compiler VAXC VAX C compiler vax11c VAX C compiler VAX11 VAX C compiler _Windows Borland C 3.1 compiling for Windows _WIN32 MS VisualC++ 4.2 under Windows-NT vms (and VMS) VAX-11 C under VMS. __alpha DEC Alpha processor __alpha__ DEC Alpha processor hp9000s800 HP RISC processor __i386__ DJGPP i386 DJGPP MULTIMAX Encore computer pyr Pyramid 9810 processor __sgi__ Silicon Graphics Inc. sparc SPARC processor sequent Sequent computer tahoe CCI Tahoe processor vax VAX processor
sizet definition is correct in `scmfig.h'.
Reduce size of HEAP_SEG_SIZE in `setjump.h'.
sizet definition.
Use 32 bit compiler mode.
Don't try to run as subproccess
SCM_INIT_PATH to be the full pathname of
`Init.scm' (see section Installing SCM).
SCHEME_LIBRARY_PATH to be the full
pathname of the scheme library [SLIB] or change library-vicinity in
`Init.scm' to point to library or remove. See section `Installation' in SLIB.
Make sure the value of (library-vicinity) has a trailing file
separator (like / or \).
Loading `r4rstest.scm' in the distribution will run an [R4RS]
conformance test on scm.
> (load "r4rstest.scm")
-|
;loading "r4rstest.scm"
SECTION(2 1)
SECTION(3 4)
#<primitive-procedure boolean?>
#<primitive-procedure char?>
#<primitive-procedure null?>
#<primitive-procedure number?>
...
Loading `pi.scm' in the distribution will enable you to compute digits of pi.
> (load "pi") ;loading "pi" ;done loading "pi.scm" ;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other #<unspecified> > (pi 100 5) 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 70679 ;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other #<unspecified>
Loading `bench.scm' will compute and display performance statistics of SCM running `pi.scm'. `make bench' or `make benchlit' appends the performance report to the file `BenchLog', facilitating tracking effects of changes to SCM on performance.
#define SHORT_ALIGN in `scmfig.h'.
HEAP_SEG_SIZE fits within sizet.
Increase size of HEAP_SEG_SIZE (or INIT_HEAP_SIZE if it is
smaller than HEAP_SEG_SIZE).
#define CHEAP_CONTIUATIONS in `scmfig.h'.
Reported problems and solutions are grouped under Compiling, Linking,
Running, and Testing. If you don't find your problem listed there, you
can send a bug report to jaffer@ai.mit.edu. The bug report
should include:
SCM_INIT_PATH and
SCHEME_LIBRARY_PATH.
scm [-a kbytes] [-ibvqmu] [-p number] [-c expression] [-e expression] [-f filename] [-l filename] [-r feature] [-- | - | -s] [filename] [arguments ...]
Upon startup scm loads the file specified by by the environment
variable SCM_INIT_PATH.
If SCM_INIT_PATH is not defined or if the file it names is not
present, scm tries to find the directory containing the
executable file. If it is able to locate the executable, scm
looks for the initialization file (usually `Init.scm') in
platform-dependent directories relative to this directory.
See section File-System Habitat for a blow-by-blow description.
As a last resort (if initialization file cannot be located), the C compile parameter IMPLINIT (defined in the makefile or `scmfig.h') is tried.
Unless the option -no-init-file or --no-init-file occurs
in the command line, `Init.scm' checks to see if there is file
`ScmInit.scm' in the path specified by the environment variable
HOME (or in the current directory if HOME is undefined). If
it finds such a file it is loaded.
`Init.scm' then looks for command input from one of three sources: From an option on the command line, from a file named on the command line, or from standard input.
This explanation applies to SCMLIT or other builds of SCM.
Scheme-code files can also invoke SCM and its variants. See section Syntax Extensions.
The options are processed in the order specified on the command line.
scm should allocate an initial heapsize of
kb kilobytes. This option, if present, must be the first on
the command line. If not specified, the default is
INIT_HEAP_SIZE in source file `setjump.h' which the
distribution sets at 25000*sizeof(cell).
perl and sh
respectively. On Amiga systems the entire option and argument need to be
enclosed in quotes. For instance `"-e(newline)"'.
scm will require the features neccessary to support [R2RS],
[R3RS], [R4RS], or proposed [R5RS], respectively.
Scm will load the first (unoptioned) file
named on the command line if no -c, -e, -f,
-l, or -s option preceeds
it.
scm command (verobse level).
scm will print prompts, evaluation
times, notice of loading files, and garbage collection statistics. This
is the same as -p3.
scm will print no extra
information. This is the same as -p0.
-r
macropackage before -m on the command line.
-m on the command line or from Scheme
code.
scm should run interactively. That means that
scm will not terminate until the (quit) or (exit)
command is given, even if there are errors. It also sets the prolixity
level to 2 if it is less than 2. This will print prompts, evaluation
times, and notice of loading files. The prolixity level can be set by
subsequent options. If scm is started from a tty, it will assume
that it should be interactive unless given a subsequent -b
option.
scm should run non-interactively. That means that
scm will terminate after processing the command line or if there
are errors.
sh, that further options are to be
treated as program aguments.
dump
(see section Dump).
If options appear on the command line after `-o filename', then the saved session will continue with processing those options when it is invoked. Otherwise the (new) command line is processed as usual when the saved image is invoked.
% scm foo.scm
% scm -f foo.scm arg1 arg2 arg3
arg1, arg2, and arg3 are stored in the
global list *argv*; Loads and executes the contents of
`foo.scm' and exits.
% scm -s foo.scm arg1 arg2
("foo.scm" "arg1" "arg2") and enters interactive
session.
% scm -e `(write (list-ref *argv* *optind*))' bar
% scm -rpretty-print -r format -i
pretty-print and format and enters interactive
session.
% scm -r5
dynamic-wind, values, and [R4RS] macros and enters
interactive (with macros) session.
% scm -r5 -r4
rev4-optional-procedures are also loaded.
scm will look for its initialization
code. The default is the file `Init.scm' in the source directory.
ed will call. If EDITOR
is not defined, the default is `ed'.
*argv* can change
during argument processing. This list is suitable for use as an argument
to [SLIB] getopt.
-m and -u options.
-i and -b
options. Define this in `ScmInit.scm' or files specified on the
command line. This can be overridden by subsequent -i and
-b options.
exit (see section `System' in SLIB). On many
systems, SCM can also tail-call another program. See section I/O-Extensions.
For documentation of the procedures getenv and system
See section `System Interface' in SLIB.
vms-debug will invoke the VMS
debugger.
EDITOR (or just ed
if it isn't defined) is invoked as a command with arguments arg1
....
ed will invoke the editor with a
single the single argument filename.
(ed arg1 ...)
will invoke your editor and return to SCM when you exit the editor. The
following definition is convenient:
(define (e) (ed "work.scm") (load "work.scm"))Typing `(e)' will invoke the editor with the file of interest. After editing, the modified file will be loaded.
The cautious and stack-limit options of build
(see section Build Options) support debugging in Scheme.
error and
user-interrupt (invoked by C-c) to print stack traces and
conclude by calling breakpoint (see section `Breakpoints' in SLIB) instead of aborting to top level. Under either condition,
program execution can be resumed by (continue).
In this configuration one can interrupt a running Scheme program with
C-c, inspect or modify top-level values, trace or untrace
procedures, and continue execution with (continue).
HEAP_SEG_SIZE/2), SCM generates a
segment violation interrupt.
The usefulness of `STACK_LIMIT' depends on the user. I don't use
it; but the user I added this feature for got primarily this type of
error.
There are several SLIB macros which so useful that SCM automatically loads the appropriate module from SLIB if they are invoked.
The routines I use most frequently for debugging are:
Print writes all its arguments, separated by spaces.
Print outputs a newline at the end and returns the value
of the last argument.
One can just insert `(print '<proc-name>' and `)' around an expression in order to see its value as a program operates.
Print-args.
(define (foo a b) (print-args foo) (+ a b)) (foo 3 6) -| In foo: a = 3; b = 6; => 9
Sometimes more elaborate measures are needed to print values in a useful manner. When the values to be printed may have very large (or infinite) external representations, section `Quick Print' in SLIB, can be used.
When trace is not sufficient to find program flow problems,
SLIB-PSD, the Portable Scheme Debugger
offers source code debugging from
GNU Emacs. PSD runs slowly, so start by instrumenting only a few
functions at a time.
ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz
A computer-language implementation designer faces choices of how reflexive to make the implementation in handling exceptions and errors; that is, how much of the error and exception routines should be written in the language itself. The design of a portable implementation is further constrained by the need to have (almost) all errors print meaningful messages, even when the implementation itself is not functioning correctly. Therefore, SCM implements much of its error response code in C.
The following common error and conditions are handled by C code. Those with callback names after them can also be handled by Scheme code (see section Interrupts). If the callback identifier is not defined at top level, the default error handler (C code) is invoked. There are many other error messages which are not treated specially.
(out-of-storage)
(end-of-program)
(hang-up)
(user-interrupt)
(arithmetic-error)
(alarm-interrupt)
error does
not set errobj.
errno and perror report ANSI C errors encountered during a
call to a system or library function.
errno. When given an argument, errno sets the system
variable errno to n and returns the previous value of
errno. (errno 0) will clear outstanding errors. This is
recommended after try-load returns #f since this occurs
when the file could not be opened.
errno and a newline. The value returned is unspecified.
warn and error provide a uniform way for Scheme code to
signal warnings and errors.
warn is defined in
`Init.scm'.
Error is defined
in `Init.scm'.
If SCM is built with the `CAUTIOUS' flag, then when an error occurs, a stack trace of certain pending calls are printed as part of the default error response. A (memoized) expression and newline are printed for each partially evaluated combination whose procedure is not builtin. See section Memoized Expressions for how to read memoized expressions.
Also as the result of the `CAUTIOUS' flag, both error and
user-interrupt (invoked by C-c) are defined to print stack
traces and conclude by calling breakpoint (see section `Breakpoints' in SLIB). This allows the user to interract with SCM as with Lisp
systems.
stack-trace returns #t if any lines were
printed and #f otherwise. See `Init.scm' for an example of
the use of stack-trace.
SCM memoizes the address of each occurence of an identifier's value when first encountering it in a source expression. Subsequent executions of that memoized expression is faster because the memoized reference encodes where in the top-level or local environment its value is.
When procedures are displayed, the memoized locations appear in a format different from references which have not yet been executed. I find this a convenient aid to locating bugs and untested expressions.
For instance, open-input-file is defined as follows in
`Init.scm':
(define (open-input-file str)
(or (open-file str OPEN_READ)
(and (procedure? could-not-open) (could-not-open) #f)
(error "OPEN-INPUT-FILE couldn't open file " str)))
If open-input-file has not yet been used, the displayed procedure
is similar to the original definition (lines wrapped for readability):
open-input-file => #<CLOSURE (str) (or (open-file str open_read) (and (procedure? could-not-open) (could-not-open) #f) (error "OPEN-INPUT-FILE couldn't open file " str))>
If we open a file using open-input-file, the sections of code
used become memoized:
(open-input-file "r4rstest.scm") => #<input-port 3> open-input-file => #<CLOSURE (str) (#@or (#@open-file #@0+0 #@open_read) (and (procedure? could-not-open) (could-not-open) #f) (error "OPEN-INPUT-FILE couldn't open file " str))>
If we cause open-input-file to execute other sections of code,
they too become memoized:
(open-input-file "foo.scm") => ERROR: No such file or directory ERROR: OPEN-INPUT-FILE couldn't open file "foo.scm" open-input-file => #<CLOSURE (str) (#@or (#@open-file #@0+0 #@open_read) (#@and (#@procedure? #@could-not-open) (could-not-open) #f) (#@error "OPEN-INPUT-FILE couldn't open file " #@0+0))>
Note: When running a saved executable (see section Dump),
restart is redefined to be exec-self.
exec-self from restart.
(room #t)
also gives the hexadecimal heap segment and stack bounds.
In order to dump a saved executable or to dynamically-link using DLD,
SCM must know where its executable file is. Sometimes SCM
(see section Executable Pathname) guesses incorrectly the location of the
currently running executable. In that case, the correct path can be set
by calling execpath with the pathname.
#f or newpath, respectively. The old path
is returned.
For other configuration constants and procedures See section `Configuration' in SLIB.
In reading this section, keep in mind that the first line of a script
file has (different) meanings to SCM and the operating system
(execve).
On unix systems, a Shell-Script is a file (with execute
permissions) whose first two characters are `#!'. The
interpreter argument must be the pathname of the program to
process the rest of the file. The directories named by environment
variable PATH are not searched to find interpreter.
The arg is an optional argument encapsulating the rest of the
first line's contents, if not just whitespace.
When executing a shell-script, the operating system invokes interpreter with (if present) arg, the pathname of the shell script file, and then any arguments which the shell-script was invoked with.
#!,
the first line of that file will be ignored.
This combination of interpretatons allows SCM source files to be used as POSIX shell-scripts if the first line is:
#!/usr/local/bin/scm
or
#!/usr/local/bin/scm -l
When such a file is invoked, /usr/local/bin/scm is executed with the name of this file as the first argument.
#!/usr/local/bin/scm
(print (program-arguments))
(quit)
=> ("scm" "./script")
#!/usr/local/bin/scm -l
(print (program-arguments))
=> ("scm" "-l" "./script")
The following shell-script will print factorial of its argument:
#!/usr/local/bin/scm -l (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) (print (fact (string->number (cadddr (program-arguments)))))
./fact 6 => 720
Shell-scripts suffer from several drawbacks:
The following approach solves these problems at the expense of slower
startup. Make `#!/bin/sh' the first line and prepend every
subsequent line to be executed by the shell with :; (type;
in older versions). The last line to be executed by the shell should
contain an exec command; exec tail-calls its argument.
/bin/sh is thus invoked with the name of the script file, which
it executes as a *sh script. Usually the second line starts
`:;exec scm -f$0', which executes scm, which in turn loads the
script file. When SCM loads the script file, it ignores the first and
second lines, and evaluates the rest of the file as Scheme source code.
The second line of the script file does not have the length restriction
mentioned above. Also, /bin/sh searches the directories listed
in the `PATH' environment variable for `scm', eliminating the need
to use absolute locations in order to invoke a program.
#!/bin/sh :;exec scm -l$0 $* (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) (print (fact (string->number (caddr (program-arguments)))))
./fact 6 => 720
Olin Shivers' Scheme Shell project solves the one-argument limitation by introducing `\' as a meta-argument. This extensions is also supported by SCM.
This is an enhancement to the shell-script format. When the optional arg is `\', the interpreter substitutes the second line of file for `\', then appends any arguments given on the command line invoking this shell-script.
#! and
a `\' is present before a newline in the file, all characters up
to `!#' will be ignored by SCM read.
This combination of interpretatons allows SCM source files to be used as POSIX shell-scripts if the first line is:
#!/usr/local/bin/scm \
The following shell-script will print its expanded argument list, then factorial of its argument:
#!/usr/local/bin/scm \ -p0 -l !# (print (program-arguments)) (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) (print (fact (string->number (list-ref (program-arguments) *optind*))))
./fact 5
=> ("scm" "-p0" "-l" "./fact" "5")
120
It turns out that we can create shell-scripts which run both under unix
and MS-DOS. To implement this, I have written the MS-DOS programs:
#!.bat and !#.exe.
With these two programs installed in a PATH directory, we have
the following syntax for <program>.BAT files.
The first two characters of the shell-script are `#!'. The interpreter can be either a unix style program path (using `/' between filename components) or a DOS program name or path. The rest of the first line of the shell-script should be literally `\ %0 %1 %2 %3 %4 %5 %6 %7 %8', as shown.
If interpreter has `/' in it, interpreter is converted to a DOS style filename (`/' => `\').
In looking for an executable named interpreter, #! first
checks this (converted) filename; if interpreter doesn't exist, it
then tries to find a program named like the string starting after the
last `\' (or `/') in interpreter. When searching for
executables, #! tries all directories named by environment
variable PATH.
Once the interpreter executable path is found, arguments are
processed in the manner of scheme-shell, with the all the text after the
`\' taken as part of the meta-argument. More precisely, #!
calls interpreter with any options on the second line of the
shell-script up to `!#', the name of the shell-script file, and
then any of at most 8 arguments given on the command line invoking this
shell-script.
The following shell-script will print its expanded argument list, then factorial of its argument. This shell-script in both MS-DOS and unix systems.
#! /usr/local/bin/scm \ %0 %1 %2 %3 %4 %5 %6 %7 %8 -p1 -l !# (print (program-arguments)) (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) (print (fact (string->number (list-ref (program-arguments) *optind*))))
Scm conforms to the [IEEE], IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming Language. and [R4RS], Revised(4) Report on the Algorithmic Language Scheme. All the required features of these specifications are supported. Many of the optional features are supported as well.
if: (if <test> <consequent>)
let*
let
do
define
list-tail
string-copy
string-fill!
make-vector of two arguments
vector-fill!
apply of more than 2 arguments
- and / of more than 2 arguments
exp
log
sin
cos
tan
asin
acos
atan
sqrt
expt
make-rectangular
make-polar
real-part
imag-part
magnitude
angle
exact->inexact
inexact->exact
delay
force
with-input-from-file
with-output-to-file
char-ready?
transcript-on
transcript-off
numerator
denominator
rationalize
delay
full-continuation
ieee-p1178
object-hash
rev4-report
source
current-time
defmacro
dynamic-wind
eval
getenv
system
hash
logical
multiarg-apply
multiarg/and-
rev4-optional-procedures
string-port
tmpnam
transcript
vicinity
with-file
array
array-for-each
bignum
complex
inexact
rational
real
#t. If not,
try-load returns #f. The try-load procedure does not affect the
values returned by current-input-port and
current-output-port.
load,
try-load, and dyn:link (see section Compiling And Linking).
*load-pathname* is used to compute the value of section `Vicinity' in SLIB.
eval-string does not change
*load-pathname* or line-number.
load, the value returned is unspecified. eval-string does
not change *load-pathname* or line-number.
@copy-tree if you
depend on this feature; copy-tree could get redefined.
Print writes all its arguments, separated by spaces.
Print outputs a newline at the end and returns the value
of the last argument.
Is the integer number of internal time units in a second.
get-internal-run-time divided by
internal-time-units-per-second will give elapsed run time in
seconds.
get-internal-real-time divided by
interal-time-units-per-second will give elapsed real time in
seconds.
current-time is
used in section `Time' in SLIB.
If n is 0, any ticks request is canceled. Otherwise a
ticks-interrupt will be signaled n from the current time.
ticks is supported if SCM is compiled with the ticks flag
defined.
ticks is called again. Program execution will
resume if the handler returns. This procedure should (abort) or some
other action which does not return if it does not want processing to
continue.
alarm-interrupt will be signaled secs from the current
time. ALARM is not supported on all systems.
SIGINT (control-C interrupt) and
SIGALRM interrupts. Program execution will resume if the handler
returns. This procedure should (abort) or some other action
which does not return if it does not want processing to continue after
it returns.
Interrupt handlers are disabled during execution system and
ed procedures.
To unestablish a response for an interrupt set the handler symbol to
#f. For instance, (set! user-interrupt #f).
To unestablish a response for an error set the handler symbol to
#f. For instance, (set! could-not-open #f).
Returns an object of type arbiter and name name. Its state is initially unlocked.
Returns #t and locks arbiter if arbiter was unlocked.
Otherwise, returns #f.
Returns #t and unlocks arbiter if arbiter was locked.
Otherwise, returns #f.
These procedures generalize and extend the standard capabilities in section `Ports' in Revised(4) Scheme.
#f is returned.
Returns #t if a character is ready on the input port and
returns #f otherwise. If char-ready? returns #t
then
the next read-char operation on the given port is
guaranteed
not to hang. If the port is at end of file then
char-ready? returns #t.
Port may be omitted, in which case it defaults to
the value returned by current-input-port.
Rationale: Char-ready? exists to make it possible for a program to
accept characters from interactive ports without getting stuck waiting
for input. Any input editors associated with such ports must ensure
that characters whose existence has been asserted by char-ready?
cannot be rubbed out. If char-ready? were to return #f at
end of file, a port at end of file would be indistinguishable from an
interactive port that has no ready characters.
A soft-port is a port based on a vector of procedures capable of accepting or delivering characters. It allows emulation of I/O ports.
For an output-only port only elements 0, 1, 2, and 4 need be
procedures. For an input-only port only elements 3 and 4 need be
procedures. Thunks 2 and 4 can instead be #f if there is no useful
operation for them to perform.
If thunk 3 returns #f or an eof-object (see section `Input' in Revised(4) Scheme) it indicates that the port has
reached end-of-file. For example:
(define stdout (current-output-port))
(define p (make-soft-port
(vector
(lambda (c) (write c stdout))
(lambda (s) (display s stdout))
(lambda () (display "." stdout))
(lambda () (char-upcase (read-char)))
(lambda () (display "@" stdout)))
"rw"))
(write p p) => #<input-output-soft#\space45d10#\>
#f if not.
If the body of a lambda (or the definition of a procedure) has
more than one expression, and the first expression (preceeding any
internal definitions) is a string, then that string is the
documentation string of that procedure.
(procedure-documentation (lambda (x) "Identity" x)) => "Identity"
(define (square x)
"Return the square of X."
(* x x))
=> #<unspecified>
(procedure-documentation square) => "Return the square of X."
In order to allow compiled code to work with #. it is good
practice to define those symbols used inside of expression with
#.(define ...). For example:
#.(define foo 9) => #<unspecified> '(#.foo #.(+ foo foo)) => (9 18)
provided? (by *features*) then form is
read as a scheme expression. If not, then form is treated as
whitespace.
Feature is a boolean expression composed of symbols and and,
or, and not of boolean expressions.
For more information on provided? and *features*,
See section `Require' in SLIB.
#+(not feature) expression.
|# is
ignored by the read. Nested #|...|# can occur inside
any thing.
A similar read syntax #! (exclamation rather than vertical bar) is supported for Posix shell-scripts (see section Shell Scripts).
#t if symbol is a syntactic keyword (such as
if) or a symbol with a value in the top level environment
(see section `Variables and regions' in Revised(4) Scheme). Otherwise
equivalent to #f.
defined to the result of evaluating the form
initial-value as if the defvar form were instead the form
(define identifier initial-value) . If identifier already
has a value, then initial-value is not evaluated and
identifier's value is not changed.
SCM also supports the following constructs from Common Lisp:
defmacro, macroexpand, macroexpand-1, and
gentemp. See section `Defmacro' in SLIB.
read, read will call the value of the
symbol read:sharp with arguments the character and the port being
read from. The value returned by this function will be the value of
read for this expression unless the function returns
#<unspecified> in which case the expression will be treated as
whitespace. #<unspecified> is the value returned by the
expression (if #f #f).
Note: When adding new # syntaxes, have your code save the
previous value of read:sharp when defining it. Call this saved
value if an invocation's syntax is not recognized. This will allow
#+, #-, #!, and section Uniform Arrays to still be
supported (as they use read:sharp).
PROCEDURE->MEMOIZING-MACRO replaces the form passed to
proc. For example:
(define trace (procedure->macro (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) (trace foo) == (set! foo (tracef foo 'foo)).
An environment is a list of environment frames. There are 2 types of environment frames:
((lambda (variable1 ...) ...) value1 ...)
(let ((variable1 value1) (variable2 value2) ...) ...)
(letrec ((variable1 value1) ...) ...)
((variable1 ...) value1 ...)
(let ((variable1 value1)) ...)
(let* ((variable1 value1) ...) ...)
(variable1 . value1) (variable2 . value2) ...
contin (see section Continuations). The procedure
(call-with-current-continuation procedure) is defined to
have the same effect as (@call-with-current-continuation
procedure).
SCM provides a synthetic identifier type for efficient implementation of
hygienic macros (for example, syntax-rules see section `Macros' in Revised(4) Scheme) A synthetic identifier may be inserted in
Scheme code by a macro expander in any context where a symbol would
normally be used. Collectively, symbols and synthetic identifiers are
identifiers.
#t if obj is a symbol or a synthetic
identifier, and #f otherwise.
If it is necessary to distinguish between symbols and synthetic identifiers,
use the predicate symbol?.
A synthetic identifier includes two data: a parent, which is an
identifier, and an environment, which is either #f or a lexical
environment which has been passed to a macro expander
(a procedure passed as an argument to procedure->macro,
procedure->memoizing-macro, or procedure->syntax).
#f or a lexical environment passed to a
macro expander. renamed-identifier returns a distinct object for
each call, even if passed identical arguments.
There is no direct way to access the data internal to a synthetic identifier, those data are used during variable lookup. If a synthetic identifier is inserted as quoted data then during macro expansion it will be repeatedly replaced by its parent, until a symbol is obtained.
renamed-identifier may be used as a replacement for gentemp:
(define gentemp
(let ((name (string->symbol "An unlikely variable")))
(lambda ()
(renamed-identifier name #f))))
If an identifier returned by this version of gentemp is inserted
in a binding position as the name of a variable then it is guaranteed
that no other identifier may denote that variable. If an identifier
returned by gentemp is inserted free, then it will denote the
top-level value bound to its parent, the symbol named "An unlikely
variable". This behavior, of course, is meant to be put to good use:
(define top-level-foo
(procedure->memoizing-macro
(lambda (exp env)
(renamed-identifier 'foo #f))))
Defines a macro which may always be used to refer to the top-level binding
of foo.
(define foo 'top-level) (let ((foo 'local)) (top-level-foo)) => top-level
In other words, we can avoid capturing foo.
If a lexical environment is passed as the second argument to
renamed-identifier then if the identifier is inserted free
its parent will be looked up in that environment, rather than in
the top-level environment. The use of such an identifier must
be restricted to the lexical scope of its environment.
There is another restriction imposed for implementation convenience:
Macros passing their lexical environments to renamed-identifier
may be lexically bound only by the special forms @let-syntax or
@letrec-syntax. No error is signaled if this restriction is not
met, but synthetic identifier lookup will not work properly.
let and letrec, but may also put extra
information in the lexical environment so that renamed-identifier
will work properly during expansion of the macros bound by these forms.
In order to maintain referential transparency it is necessary to
determine whether two identifiers have the same denotation. With
synthetic identifiers it is not necessary that two identifiers be
eq? in order to denote the same binding.
#t if identifiers id1 and id2 denote the same
binding in lexical environment env, and #f otherwise.
env must be a lexical environment passed to a macro transformer
during macro expansion.
For example,
(define top-level-foo?
(procedure->memoizing-macro
(let ((foo-name (renamed-identifier 'foo #f)))
(lambda (exp env)
(identifier-equal? (cadr exp) foo-name env)))))
(top-level-foo? foo) => #t
(let ((foo 'local))
(top-level-foo? foo)) => #f
quote
and quasiquote so that literal data in macro definitions will be
properly transcribed. syntax-quote behaves like quote, but
preserves synthetic identifier intact.
the-macro is the simplest of all possible macro transformers:
mac may be a syntactic keyword (macro name) or an expression
evaluating to a macro, otherwise an error is signaled. mac is
evaluated and returned once only, after which the same memoizied value is
returned.
the-macro may be used to protect local copies of macros against
redefinition, for example:
(@let-syntax ((let (the-macro let)))
;; code that will continue to work even if LET is redefined.
...)
(implementation-vicinity), compiles the files name1
name2 ... to an object file name name1<object-suffix>,
where <object-suffix> is the object file suffix for your computer (for
instance, `.o'). name1 must be in the current directory;
name2 ... can be in other directories.
compile-file.
cd ~/scm/
scm -e'(link-named-scm"cute""cube")'
(delete-file "scmflags.h")
(call-with-output-file
"scmflags.h"
(lambda (fp)
(for-each
(lambda (string) (write-line string fp))
'("#define IMPLINIT \"/home/jaffer/scm/Init.scm\""
"#define COMPILED_INITS init_cube();"
"#define BIGNUMS"
"#define FLOATS"
"#define ARRAYS"))))
(system "gcc -Wall -O2 -c continue.c findexec.c time.c
repl.c scl.c eval.c sys.c subr.c unif.c rope.c scm.c")
...
scm.c: In function `scm_init_extensions':
scm.c:95: warning: implicit declaration of function `init_cube'
scm.c: In function `scm_cat_path':
scm.c:589: warning: implicit declaration of function `realloc'
scm.c:594: warning: implicit declaration of function `malloc'
scm.c: In function `scm_try_path':
scm.c:612: warning: implicit declaration of function `free'
(system "cc -o cute continue.o findexec.o time.o repl.o scl.o
eval.o sys.o subr.o unif.o rope.o scm.o cube.o -lm -lc")
Compilation finished at Sun Jul 21 00:59:17
If SCM has been compiled with `dynl.c' then the additional
properties of load and ([SLIB]) require specified here are supported.
The require form is preferred.
require, then the object and library files associated with
feature will be dynamically-linked, and an unspecified value
returned. If feature is not found in *catalog*, then an
error is signaled.
(usr:lib "m") returns "/usr/lib/libm.a", the path of the C
math library.
(x:lib "X11") returns "/usr/X11/lib/libX11.sa", the path
of the X11 library.
load will also
dynamically load/link object files (produced by compile-file, for
instance). The object-suffix need not be given to load. For example,
(load (in-vicinity (implementation-vicinity) "sc2")) or (load (in-vicinity (implementation-vicinity) "sc2.o")) or (require 'rev2-procedures) or (require 'rev3-procedures)
will load/link `sc2.o' if it exists.
The lib1 ... pathnames specify additional libraries which may be needed for object files not produced by the Hobbit compiler. For instance, crs is linked on Linux by
(load (in-vicinity (implementation-vicinity) "crs.o")
(usr:lib "ncurses") (usr:lib "c"))
or (require 'curses)
Turtlegr graphics library is linked by:
(load (in-vicinity (implementation-vicinity) "turtlegr")
(usr:lib "X11") (usr:lib "c") (usr:lib "m"))
or (require 'turtle-graphics)
And the string regular expression (see section Regular Expression Pattern Matching) package is linked by:
(load (in-vicinity (implementation-vicinity) "rgx") (usr:lib "c"))
or
(require 'regex)
The following functions comprise the low-level Scheme interface to dynamic linking. See the file `Link.scm' in the SCM distribution for an example of their use.
dyn:link
procedure links and loads filename into the current SCM session.
If successfull, dyn:link returns a link-token suitable for
passing as the second argument to dyn:call. If not successful,
#f is returned.
dyn:link. name should be the name of C function of no
arguments defined in the file named filename which was succesfully
dyn:linked in the current SCM session. The dyn:call
procedure calls the C function corresponding to name. If
successful, dyn:call returns #t; If not successful,
#f is returned.
dyn:call is used to call the init_... function after
loading SCM object files. The init_... function then makes the
identifiers defined in the file accessible as Scheme procedures.
dyn:link. name should be the name of C function of 2
arguments, (int argc, char **argv), defined in the file named
filename which was succesfully dyn:linked in the current
SCM session. The dyn:main-call procedure calls the C function
corresponding to name with argv style arguments, such as
are given to C main functions. If successful,
dyn:main-call returns the integer returned from the call to
name.
dyn:main-call can be used to call a main procedure from
SCM. For example, I link in and dyn:main-call a large C program,
the low level routines of which callback (see section Callbacks) into SCM
(which emulates PCI hardware).
dyn:link. The dyn:unlink procedure removes the previously
loaded file from the current SCM session. If successful,
dyn:unlink returns #t; If not successful, #f is
returned.
Dump, (also known as unexec), saves the continuation of an entire SCM session to an executable file, which can then be invoked as a program. Dumped executables start very quickly, since no Scheme code has to be loaded.
There are constraints on which sessions are savable using dump
dump.
current-input-port, current-output-port,
current-error-port), X windows, etc. are invalid in subsequent
invocations.
This restriction could be removed; See section Improvements To Make.
Dump should only be called from a loading file when the call to
dump is the last expression in that file.
Dump can be called from the command line.
gc.
dump is #t, argument processing
will continue from the command line passed to the dumping session. If
the second argument is missing or #f then the command line
arguments of the restoring invocation will be processed.
dump may set the values of boot-tail, *argv*,
restart, and *interactive*. dump returns an
unspecified value.
When a dumped executable is invoked, the variable *interactive*
(see section Internal State) has the value it possessed when dump
created it. Calling dump with a single argument sets
*interactive* to #f, which is the state it has at the
beginning of command line processing.
The procedure program-arguments returns the command line
arguments for the curent invocation. More specifically,
program-arguments for the restored session are not saved
from the dumping session. Command line processing is done on
the value of the identifier *argv*.
The thunk boot-tail is called by SCM to process command line
arguments. dump sets boot-tail to the thunk it is
called with.
The following example shows how to create `rscm', which is like regular scm, but which loads faster and has the `random' package alreadly provided.
bash$ scm -rrandom > (dump "rscm") #<unspecified> > (quit) bash$ ./rscm -lpi.scm -e"(pi (random 200) 5)" 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 70679 82148 08651 32823 06647 09384 46095 50582 23172 53594 08128 48111 74502 84102 70193 85211 05559 64462 29489 bash$
This task can also be accomplished using the `-o' command line option (see section Options).
bash$ scm -rrandom -o rscm > (quit) bash$ ./rscm -lpi.scm -e"(pi (random 200) 5)" 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 70679 82148 08651 32823 06647 09384 46095 50582 23172 53594 08128 48111 74502 84102 70193 85211 05559 64462 29489 bash$
These procedures augment the standard capabilities in section `Numerical operations' in Revised(4) Scheme.
(angle (make-rectangular x y)) for real numbers y
and x.
$expt
is not real.
Arrays read and write as a # followed by the rank
(number of dimensions) followed by what appear as lists (of lists) of
elements. The lists must be nested to the depth of the rank. For each
depth, all lists must be the same length.
(make-array 'ho 3 3) => #2((ho ho ho) (ho ho ho) (ho ho ho))
Unshared conventional (not uniform) 0-based arrays of rank 1 (dimension) are equivalent to (and can't be distinguished from) vectors.
(make-array 'ho 3) => (ho ho ho)
When constructing an array, bound is either an inclusive range of indices expressed as a two element list, or an upper bound expressed as a single integer. So
(make-array 'foo 3 3) == (make-array 'foo '(0 2) '(0 2))
#t if the obj is an array, and #f if not.
#t if its arguments would be acceptable to array-ref.
array-set! is
unspecified.
make-shared-array can be used to create shared subarrays of other
arrays. The mapper is a function that translates coordinates in
the new array into coordinates in the old array. A mapper must be
linear, and its range must stay within the bounds of the old array, but
it can be otherwise arbitrary. A simple example:
(define fred (make-array #f 8 8)) (define freds-diagonal (make-shared-array fred (lambda (i) (list i i)) 8)) (array-set! freds-diagonal 'foo 3) (array-ref fred 3 3) => foo (define freds-center (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2)) (array-ref freds-center 0 0) => foo
The values of dim0, dim1, ... correspond to dimensions in the array to be returned, their positions in the argument list to dimensions of array. Several dims may have the same value, in which case the returned array will have smaller rank than array.
examples:
(transpose-array '#2((a b) (c d)) 1 0) => #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) => #1(a d)
(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) =>
#2((a 4) (b 5) (c 6))
An enclosed array is not a general Scheme array. Its elements may not
be set using array-set!. Two references to the same element of
an enclosed array will be equal? but will not in general be
eq?. The value returned by array-prototype when given an
enclosed array is unspecified.
examples:
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) => #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))> (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) => #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
(array-shape (make-array 'foo '(-1 3) 5)) => ((-1 3) (0 4))
Array-dimensions is similar to array-shape but replaces
elements with a 0 minimum with one greater than the maximum. So:
(array-dimensions (make-array 'foo '(-1 3) 5)) => ((-1 3) 5)
0 is returned.
array-copy! but guaranteed to copy in row-major order.
#t iff all arguments are arrays with the same shape, the
same type, and have corresponding elements which are either
equal? or array-equal?. This function differs from
equal? in that a one dimensional shared array may be
array-equal? but not equal? to a vector or uniform vector.
array-contents returns that shared array, otherwise it returns
#f. All arrays made by make-array and
make-uniform-array may be unrolled, some arrays made by
make-shared-array may not be.
If the optional argument strict is provided, a shared array will be returned only if its elements are stored internally contiguous in memory.
If array1, ... are arrays, they must have the same number of dimensions as array0 and have a range for each index which includes the range for the corresponding index in array0. If they are scalars, that is, not arrays, vectors, or strings, then they will be converted internally to arrays of the appropriate shape. proc is applied to each tuple of elements of array1 ... and the result is stored as the corresponding element in array0. The value returned is unspecified. The order of application is unspecified.
One can implement array-indexes as
(define (array-indexes array)
(let ((ra (apply make-array #f (array-shape array))))
(array-index-map! ra (lambda x x))
ra))
Another example:
(define (apl:index-generator n)
(let ((v (make-uniform-vector n 1)))
(array-index-map! v (lambda (i) i))
v))
eqv? to scalar.
If the optional argument prototype is supplied it will be used
as the prototype for the returned array. Otherwise the returned array
will be of the same type as array if that is possible, and
a conventional array if it is not. This function is used internally
by array-map! and friends to handle scalar arguments.
Uniform Arrays and vectors are arrays whose elements are all of the same type. Uniform vectors occupy less storage than conventional vectors. Uniform Array procedures also work on vectors, uniform-vectors, bit-vectors, and strings.
prototype arguments in the following procedures are interpreted according to the table:
prototype type display prefix #t boolean (bit-vector) #b #\a char (string) #a integer >0 unsigned integer #u integer <0 signed integer #e 1.0 float (single precision) #s 1/3 double (double precision float) #i +i complex (double precision) #c () conventional vector #
Unshared uniform character 0-based arrays of rank 1 (dimension) are equivalent to (and can't be distinguished from) strings.
(make-uniform-array #\a 3) => "$q2"
Unshared uniform boolean 0-based arrays of rank 1 (dimension) are equivalent to (and can't be distinguished from) section Bit Vectors.
(make-uniform-array #t 3) => #*000 == #b(#f #f #f) => #*000 == #1b(#f #f #f) => #*000
Other uniform vectors are written in a form similar to that of vectors,
except that a single character from the above table is put between
# and (. For example, '#e(3 5 9) returns a uniform
vector of signed integers.
uniform-vector-set! is
unspecified.
#t if the obj is an array of type corresponding to
prototype, and #f if not.
make-uniform-array.
uniform-array-read! returns the number of objects read.
port may be omitted, in which case it defaults to the value
returned by (current-input-port).
(current-output-port).
Bit vectors can be written and read as a sequence of 0s and
1s prefixed by #*.
#b(#f #f #f #t #f #t #f) => #*0001010
Some of these operations will eventually be generalized to other uniform-arrays.
#f is returned.
#t, uve is OR'ed into bv; If bool is #f, the
inversion of uve is AND'ed into bv.
If uve is a unsigned integer vector all the elements of uve must be
between 0 and the LENGTH of bv. The bits of bv
corresponding to the indexes in uve are set to bool.
The return value is unspecified.
(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
bv is not modified.
If 'i/o-extensions is provided (by linking in `ioext.o'),
section `Line I/O' in SLIB, and the following functions are defined:
#t if port is input or output to a serial non-file device.
#f is returned.
The elements of the returned vector are as follows:
file-set-position is unspecified. The result of
file-set-position is unspecified.
reopen-file returns #t if successful,
#f if not.
redirect-port! returns to-port if
successful, #f if not. If unsuccessful, to-port is not
closed.
#f.
readdir returns a
#f.
readdir with
dir will return the first entry in the directory again.
#t. If dir is already
closed,, closedir returns a #f.
mkdir function creates a new, empty directory whose name is
path. The integer argument mode specifies the file
permissions for the new directory. See section `The Mode Bits for Access Permission' in Gnu C Library, for more information about this.
mkdir returns if successful, #f if not.
rmdir function deletes the directory path. The
directory must be empty before it can be removed. rmdir returns
if successful, #f if not.
#f is returned. Otherwise, #t is
returned.
getcwd returns a string containing the absolute file
name representing the current working directory. If this string cannot
be obtained, #f is returned.
#t is returned. Otherwise,
#f is returned.
chmod sets the access permission bits for the file
named by file to mode. The file argument may be a
string containing the filename or a port open to the file.
chmod returns if successful, #f if not.
utime returns if successful, #f if not.
umask sets the file creation mask of the current
process to mask, and returns the previous value of the file
creation mask.
#f is returned.
#t if the file named by pathname can be accessed in
the way specified by the how argument. The how argument can
be the logior of the flags:
Or the how argument can be a string of 0 to 3 of the following
characters in any order. The test performed is the and of the
associated tests and file-exists?.
execl, command must be an exact
pathname of an executable file. execlp searches for
command in the list of directories specified by the environment
variable PATH. The convention is that arg0 is the same name
as command.
If successful, this procedure does not return. Otherwise an error
message is printed and the integer errno is returned.
execl and execlp except that the set of arguments to
command is arglist.
Names of environment variables are case-sensitive and must not contain
the character =. System-defined environment variables are
invariably uppercase.
Putenv is used to set up the environment before calls to
execl, execlp, execv, execvp, system,
or open-pipe (see section I/O-Extensions).
To access environment variables, use getenv (see section `System Interface' in SLIB).
If 'posix is provided (by linking in `posix.o'), the
following functions are defined:
#f is
returned.
#f is returned.
#f is returned.
(cons rd wd) where rd and wd are
the read and write (port) ends of a pipe respectively.
fork. Both processes
return from fork, but the calling (parent) process's
fork returns the child process's ID whereas the child
process's fork returns 0.
For a discussion of IDs See section `Process Persona' in libc.
#t if successful, #f if not.
#t if successful, #f if not.
#t if successful, #f if not.
#t if successful, #f if not.
kill function sends the signal signum to the process or
process group specified by pid. Besides the signals listed in
section `Standard Signals' in GNU C Library, signum can also
have a value of zero to check the validity of the pid.
The pid specifies the process or process group to receive the signal:
(abs pid).
A process can send a signal to itself with (kill (getpid)
signum). If kill is used by a process to send a signal to
itself, and the signal is not blocked, then kill delivers at
least one signal (which might be some other pending unblocked signal
instead of the signal signum) to that process before it returns.
The return value from kill is zero if the signal can be sent
successfully. Otherwise, no signal is sent, and a value of -1 is
returned. If pid specifies sending a signal to several processes,
kill succeeds if it can send the signal to at least one of them.
There's no way you can tell which of the processes got the signal or
whether all of them did.
The waitpid function suspends execution of the current process
until a child as specified by the pid argument has exited, or until a
signal is deliverd whose action is to terminate the current process or
to call a signal handling function. If a child as requested by pid has
already exited by the time of the call (a so-called zombie
process), the function returns immediately. Any system resources used
by the child are freed.
The value of pid can be one of:
(abs pid).
The value of options is one of the following:
WNOHANG) which means to return immediately if no child is there
to be waited for.
WUNTRACED) which means to also return for children which are
stopped, and whose status has not been reported.
The return value is normally the process ID of the child process whose
status is reported. If the WNOHANG option was specified and no
child process is waiting to be noticed, the value is zero. A value of
#f is returned in case of error and errno is set. For
information about the errno codes See section `Process Completion' in libc.
uname procedure to find out some information
about the type of computer your program is running on.
Returns a vector of strings. These strings are:
NAME,
UID, or the next entry if no argument is given. The
information is:
#f, in
which case the interpretation is system-dependent.
#f, indicating that the system default should be used.
NAME,
UID, or the next entry if no argument is given. The
information is:
link function makes a new link to the existing file named by
oldname, under the new name newname.
link returns a value of #t if it is successful and
#f on failure.
chown function changes the owner of the file filename
to owner, and its group owner to group.
chown returns a value of #t if it is successful and
#f on failure.
#f.
If 'unix is provided (by linking in `unix.o'), the following
functions are defined:
These priveledged and symbolic link functions are not in Posix:
symlink function makes a symbolic link to oldname named
newname.
symlink returns a value of #t if it is successful and
#f on failure.
#f for
failure.
lstat function is like stat, except that it does not
follow symbolic links. If filename is the name of a symbolic
link, lstat returns information about the link itself; otherwise,
lstat works like stat. See section I/O-Extensions.
chown returns a value of #t if it is successful and
#f on failure.
#f causes
accounting to be turned off.
acct returns a value of #t if it is successful and
#f on failure.
mknod function makes a special file with name filename
and modes mode for device number dev.
mknod returns a value of #t if it is successful and
#f on failure.
sync first commits inodes to buffers, and then buffers to disk.
sync() only schedules the writes, so it may return before the actual
writing is done. The value returned is unspecified.
These functions are defined in `rgx.c' using a POSIX or GNU regex library. If your computer does not support regex, a package is available via ftp from `prep.ai.mit.edu:/pub/gnu/regex-0.12.tar.gz'. For a description of regular expressions, See section `syntax' in "regex" regular expression matching library.
regerror.
flags in regcomp is a string of option letters used to
control the compilation of the regular expression. The letters may
consist of:
. or hat lists; ( [^...] )
regcomp fails.
#f or a vector of integers. These integers are in
doublets. The first of each doublet is the index of string of
the start of the matching expression or sub-expression (delimited by
parentheses in the pattern). The last of each doublet is index of
string of the end of that expression. #f is returned if
the string does not match.
#t if the pattern such that regexp = (regcomp
pattern) matches string as a POSIX extended regular
expressions. Returns #f otherwise.
Regsearch searches for the pattern within the string.
Regmatch anchors the pattern and begins matching it against
string.
Regsearch returns the character position where re starts,
or #f if not found.
Regmatch returns the number of characters matched, #f if
not matched.
Regsearchv and regmatchv return the match vector is
returned if re is found, #f otherwise.
regcomp;
String-split splits a string into substrings that are separated
by re, returning a vector of substrings.
String-splitv returns a vector of string positions that indicate
where the substrings are located.
sed.
string-edit to perform. If
#t, all occurances of re will be replaced. The default is
to perform one substitution.
These procedures provide input line editing and recall.
These functions are defined in `edline.c' and `Iedline.scm' using the editline or GNU readline (see section `Overview' in GNU Readline Library) libraries available from:
When `Iedline.scm' is loaded, if the current input port is the default input port and the environment variable EMACS is not defined, line-editing mode will be entered.
current-input-port SCM was invoked with
(stdin).
current-output-port SCM was invoked with
(stdout).
#f.
(line-editing). If bool is true, sets the current
input and output ports to an edited line port and returns the previous
value of (line-editing).
These functions are defined in `crs.c' using the curses
library. Unless otherwise noted these routines return #t for
successful completion and #f for failure.
endwin before exiting or escaping from
curses mode temporarily, to do a system call, for example. This routine
will restore termio modes, move the cursor to the lower left corner of
the screen and reset the terminal into the proper non-visual mode. To
resume after a temporary escape, call section Window Manipulation.
These routines set options within curses that deal with output. All
options are initially #f, unless otherwise stated. It is not
necessary to turn these options off before calling endwin.
#t), the next call to force-output
or refresh with win will clear the screen completely and
redraw the entire screen from scratch. This is useful when the contents
of the screen are uncertain, or in some cases for a more pleasing visual
effect.
#t), curses will consider using the
hardware "insert/delete-line" feature of terminals so equipped. If
disabled (bf is #f), curses will very seldom use this
feature. The "insert/delete-character" feature is always considered.
This option should be enabled only if your application needs
"insert/delete-line", for example, for a screen editor. It is
disabled by default because
"insert/delete-line" tends to be visually annoying when used in applications where it is not really needed. If "insert/delete-line" cannot be used, curses will redraw the changed portions of all lines.
#f), the cursor is left on the
bottom line at the location where the offending character was entered.
If enabled (bf is #t), force-output is called on the
window win, and then the physical terminal and window win
are scrolled up one line.
Note: in order to get the physical scrolling effect on the
terminal, it is also necessary to call idlok.
These routines set options within curses that deal with input. The
options involve using ioctl(2) and therefore interact with curses
routines. It is not necessary to turn these options off before
calling endwin. The routines in this section all return an
unspecified value.
CBREAK mode,
respectively. In CBREAK mode, characters typed by the user are
immediately available to the program and erase/kill character
processing is not performed. When in NOCBREAK mode, the tty driver
will buffer characters typed until a LFD or RET is typed.
Interrupt and flowcontrol characters are unaffected by this mode.
Initially the terminal may or may not be in CBREAK mode, as it is
inherited, therefore, a program should call cbreak or nocbreak
explicitly. Most interactive programs using curses will set CBREAK
mode.
Note: cbreak overrides raw. For a discussion of
how these routines interact with echo and noecho
See section Input.
RAW mode. RAW mode
is similar to CBREAK mode, in that characters typed are
immediately passed through to the user program. The differences are
that in RAW mode, the interrupt, quit, suspend, and flow control
characters are passed through uninterpreted, instead of generating a
signal. RAW mode also causes 8-bit input and output. The
behavior of the BREAK key depends on other bits in the terminal
driver that are not set by curses.
read-char as they are typed. Echoing by the tty driver is
always disabled, but initially read-char is in ECHO mode,
so characters typed are echoed. Authors of most interactive programs
prefer to do their own echoing in a controlled area of the screen, or
not to echo at all, so they disable echoing by calling noecho.
For a discussion of how these routines interact with echo and
noecho See section Input.
LFD on output, and whether RET is translated into
LFD on input. Initially, the translations do occur. By disabling
these translations using nonl, curses is able to make better use
of the linefeed capability, resulting in faster cursor motion.
savetty saves the current state of the terminal in a buffer and
resetty restores the state to what it was at the last call to
savetty.
LINES-begy and COLS-begx. A new full-screen
window is created by calling newwin(0,0,0,0).
touchwin or touchline on orig
before calling force-output.
force-output copies
the window win to the physical terminal screen, taking into
account what is already there in order to minimize the amount of
information that's sent to the terminal (called optimization). Unless
leaveok has been enabled, the physical cursor of the terminal is
left at the location of window win's cursor. With refresh,
the number of characters output to the terminal is returned.
These routines overlay srcwin on top of dstwin; that is, all
text in srcwin is copied into dstwin. srcwin and
dstwin need not be the same size; only text where the two windows
overlap is copied. The difference is that overlay is
non-destructive (blanks are not copied), while overwrite is
destructive.
touchline only pretends that
count lines have been changed, beginning with line start.
refresh (or force-output) is called. The position
specified is relative to the upper left corner of the window win,
which is (0, 0).
These routines are used to draw text on windows
If ch is a TAB, LFD, or backspace, the cursor will be
moved appropriately within the window win. A LFD also does a
wclrtoeol before moving. TAB characters are considered to
be at every eighth column. If ch is another control character, it
will be drawn in the C-x notation. (Calling winch after
adding a control character will not return the control character, but
instead will return the representation of the control character.)
Video attributes can be combined with a character by or-ing them into
the parameter. This will result in these attributes also being set.
The intent here is that text, including attributes, can be copied from
one place to another using inch and display. See standout,
below.
Note: For wadd ch can be an integer and will insert
the character of the corresponding value.
werase, but it also calls section Output Options Setting, arranging that the screen will be cleared
completely on the next call to refresh or force-output for
window win, and repainted from scratch.
cbreak, this will be
after one character (CBREAK mode), or after the first newline
(NOCBREAK mode). Unless noecho has been set, the
character will also be echoed into win.
When using read-char, do not set both NOCBREAK mode
(nocbreak) and ECHO mode (echo) at the same time.
Depending on the state of the terminal driver when each character is
typed, the program may produce undesirable results.
These functions set the current attributes of the window win. The current attributes of win are applied to all characters that are written into it. Attributes are a property of the character, and move with the character through any scrolling and insert/delete line/character operations. To the extent possible on the particular terminal, they will be displayed as the graphic rendition of characters put on the screen.
wstandout sets the current attributes of the window win to
be visibly different from other text. wstandend turns off the
attributes.
ACS_VLINE and ACS_HLINE, will be used.
Note: vertch and horch can be an integers and will insert the character (with attributes) of the corresponding values.
These procedures (defined in `socket.c') provide a Scheme interface to most of the C socket library. For more information on sockets, See section `Sockets' in The GNU C Library Reference Manual.
HOST-SPEC or the
next entry if HOST-SPEC isn't given. The information is:
AF_INET)
#f queries will be be done
using UDP datagrams. Otherwise, a connected TCP socket
will be used. When called without an argument, the host table is
closed.
AF_INET)
#f the table will be closed
between calls to getnet. Otherwise, the table stays open. When
called without an argument, the network table is closed.
#f the table will be closed
between calls to getproto. Otherwise, the table stays open. When
called without an argument, the protocol table is closed.
#f the table will be closed
between calls to getserv. Otherwise, the table stays open. When
called without an argument, the service table is closed.
#f if not found.
#f if not found.
#f if not found.
The type socket-name is used for inquiries about open sockets in the following procedures:
#f if
unsuccessful or socket is closed.
#f if unsuccessful or socket is closed.
When a port is returned from one of these calls it is unbuffered. This allows both reading and writing to the same port to work. If you want buffered ports you can (assuming sock-port is a socket i/o port):
(require 'i/o-extensions) (define i-port (duplicate-port sock-port "r")) (define o-port (duplicate-port sock-port "w"))
Returns a SOCK_STREAM socket of type family using
protocol. If family has the value AF_INET,
SO_REUSEADDR will be set. The integer argument protocol
corresponds to the integer protocol numbers returned (as vector
elements) from (getproto). If the protocol argument is not
supplied, the default (0) for the specified family is used. SCM
sockets look like ports opened for neither reading nor writing.
Returns a pair (cons) of connected SOCK_STREAM (socket) ports of
type family using protocol. Many systems support only
socketpairs of the af-unix family. The integer argument
protocol corresponds to the integer protocol numbers returned (as
vector elements) from (getproto). If the protocol argument is
not supplied, the default (0) for the specified family is used.
Socket:shutdown returns socket if successful, #f if
not.
#f if not
successful.
#f if not successful. Binding a
unix-socket creates a socket in the file system that must be
deleted by the caller when it is no longer needed (using
delete-file).
#f if not.
socket:listen can
be polled for connections by char-ready? (see section Files and Ports). This avoids blocking on connections by
socket:accept.
The following example is not too complicated, yet shows the use of sockets for multiple connections without input blocking.
;;;; Scheme chat server
;;; This program implements a simple `chat' server which accepts
;;; connections from multiple clients, and sends to all clients any
;;; characters received from any client.
;;; To connect to chat `telnet localhost 8001'
(require 'socket)
(require 'i/o-extensions)
(let ((listener-socket (socket:bind (make-stream-socket af_inet) 8001))
(connections '()))
(socket:listen listener-socket 5)
(do () (#f)
(cond ((char-ready? listener-socket)
(let ((con (socket:accept listener-socket)))
(display "accepting connection from ")
(display (getpeername con))
(newline)
(set! connections (cons con connections))
(display "connected" con)
(newline con))))
(set! connections
(let next ((con-list connections))
(cond ((null? con-list) '())
(else
(let ((con (car con-list)))
(cond ((char-ready? con)
(let ((c (read-char con)))
(cond ((eof-object? c)
(display "closing connection from ")
(display (getpeername con))
(newline)
(close-port con)
(next (cdr con-list)))
(else
(for-each (lambda (con)
(file-set-position con 0)
(write-char c con)
(file-set-position con 0))
connections)
(cons con (next (cdr con-list)))))))
(else (cons con (next (cdr con-list))))))))))))
You can use `telnet localhost 8001' to connect to the chat server, or you can use a client written in scheme:
;;;; Scheme chat client
;;; this program connects to socket 8001. It then sends all
;;; characters from current-input-port to the socket and sends all
;;; characters from the socket to current-output-port.
(require 'socket)
(require 'i/o-extensions)
(define con (make-stream-socket af_inet))
(set! con (socket:connect con (inet:string->address "localhost") 8001))
(do ((cs #f (and (char-ready? con) (read-char con)))
(ct #f (and (char-ready?) (read-char))))
((or (eof-object? cs) (eof-object? ct))
(close-port con))
(cond (cs (display cs)))
(cond (ct (file-set-position con 0)
(display ct con)
(file-set-position con 0))))
In the descriptions below it is assumed that long ints are 32
bits in length. Acutally, SCM is written to work with any long
int size larger than 31 bits. With some modification, SCM could work
with word sizes as small as 24 bits.
All SCM objects are represented by type SCM. Type SCM come
in 2 basic flavors, Immediates and Cells:
An immediate is a data type contained in type SCM
(long int). The type codes distinguishing immediate types from
each other vary in length, but reside in the low order bits.
SCM object x is an immediate or
non-immediate type, respectively.
1 in
the second to low order bit position. The high order 30 bits are used
for the integer's value.
SCM x is an immediate integer or not
an immediate integer, respectively.
long integer corresponding to SCM x.
SCM inum corresponding to C long integer x.
MAKINUM(0).
Computations on INUMs are performed by converting the arguments to C integers (by a shift), operating on the integers, and converting the result to an inum. The result is checked for overflow by converting back to integer and checking the reverse operation.
The shifts used for conversion need to be signed shifts. If the C
implementation does not support signed right shift this fact is detected
in a #if statement in `scmfig.h' and a signed right shift,
SRS, is constructed in terms of unsigned right shift.
SCM object x is a character.
unsigned char.
char x, returns SCM character.
#t
#f
(). If SICP is #defined, EOL is
#defined to be identical with BOOL_F. In this case, both
print as #f.
#<eof>.
#<undefined> used for variables which have not been defined and
absent optional arguments.
#<unspecified> is returned for those procedures whose return
values are not specified.
isymnames[].
char *
representation (from isymnames[]).
SCM ispcsym n.
SCM iisym n.
SCM iflag n.
and, begin, case, cond, define,
do, if, lambda, let, let*,
letrec, or, quote, set!, #f,
#t, #<undefined>, #<eof>, (), and
#<unspecified>.
0.
There is one exception to this rule, CAR Immediates, described next.
A CAR Immediate is an Immediate point which can only occur in the
CARs of evaluated code (as a result of ceval's memoization
process).
Cells represent all SCM objects other than immediates. A cell has
a CAR and a CDR. Low-order bits in CAR identify
the type of object. The rest of CAR and CDR hold object
data. The number after tc specifies how many bits are in the
type code. For instance, tc7 indicates that the type code is 7
bits.
SCM local
variable x.
Care needs to be taken that stores into the new cell pointed to by x do not create an inconsistent object. See section Signals.
All of the C macros decribed in this section assume that their argument
is of type SCM and points to a cell (CELLPTR).
car and cdr of cell x, respectively.
tc3_cons or isn't, respectively.
tc3_closures have a pointer to other the body of the procedure in
the CAR and a pointer to the environment in the CDR.
tc3_closure.
Headers are Cells whose CDRs point elsewhere in memory,
such as to memory allocated by malloc.
tc7 type code
tc7_vector or if not, respectively.
SCMs holding the elements of vector
x or its length, respectively.
malloced scheme symbol (can be GCed)
tc7_ssymbol or
tc7_msymbol.
chars or as unsigned chars holding
the elements of symbol x or its length, respectively.
tc7_string or isn't,
respectively.
chars or as unsigned chars holding
the elements of string x or its length, respectively.
A cclo is similar to a vector (and is GCed like one), but can be applied as a function:
SCM data. Elements of a cclo are referenced
using VELTS(cclo)[n] just as for vectors.
A Subr is a header whose CDR points to a C code procedure.
Scheme primitive procedures are subrs. Except for the arithmetic
tc7_cxrs, the C code procedures will be passed arguments (and
return results) of type SCM.
+, -,
*, /, max, and min.
CDR should be a function which takes and returns type
double. Conversions are handled in the interpreter.
floor, ceiling, truncate, round,
$sqrt, $abs, $exp, $log, $sin,
$cos, $tan, $asin, $acos, $atan,
$sinh, $cosh, $tanh, $asinh, $acosh,
$atanh, and exact->inexact are defined this way.
If the CDR is 0 (NULL), the name string of the
procedure is used to control traversal of its list structure argument.
car, cdr, caar, cadr, cdar,
cddr, caaar, caadr, cadar, caddr,
cdaar, cdadr, cddar, cdddr, caaaar,
caaadr, caadar, caaddr, cadaar,
cadadr, caddar, cadddr, cdaaar,
cdaadr, cdadar, cdaddr, cddaar,
cddadr, cdddar, and cddddr are defined this way.
BOOL_T or BOOL_F.
UNDEFINED is passed in its place.
UNDEFINED is passed in its place.
SCM arguments.
SCM arguments.
A ptob is a port object, capable of delivering or accepting characters. See section `Ports' in Revised(4) Report on the Algorithmic Language Scheme. Unlike the types described so far, new varieties of ptobs can be defined dynamically (see section Defining Ptobs). These are the initial ptobs:
popen().
popen().
cwos() or cwis().
mksfpt() (see section Soft Ports).
FILE * stream for port x.
Ports which are particularly well behaved are called fports.
Advanced operations like file-position and reopen-file
only work for fports.
A smob is a miscellaneous datatype. The type code and GCMARK bit
occupy the lower order 16 bits of the CAR half of the cell. The
rest of the CAR can be used for sub-type or other information.
The CDR contains data of size long and is often a pointer to
allocated memory.
Like ptobs, new varieties of smobs can be defined dynamically (see section Defining Smobs). These are the initial smobs:
Inexact number data types are subtypes of type tc16_flo. If the
sub-type is:
CDR.
CDR is a pointer to a malloced double.
CDR is a pointer to a malloced pair of doubles.
Scm has large precision integers called bignums. They are stored in
sign-magnitude form with the sign occuring in the type code of the SMOBs
bigpos and bigneg. The magnitude is stored as a malloced array
of type BIGDIG which must be an unsigned integral type with size
smaller than long. BIGRAD is the radix associated with
BIGDIG.
This type implements both conventional arrays (those with arbitrary data as elements see section Conventional Arrays) and uniform arrays (those with elements of a uniform type see section Uniform Array).
Conventional Arrays have a pointer to a vector for their CDR.
Uniform Arrays have a pointer to a Uniform Vector type (string, bvect,
ivect, uvect, fvect, dvect, or cvect) in their CDR.
IMMEDIATE: B,D,E,F=data bit, C=flag code, P=pointer address bit
................................
inum BBBBBBBBBBBBBBBBBBBBBBBBBBBBBB10
ichr BBBBBBBBBBBBBBBBBBBBBBBB11110100
iflag CCCCCCC101110100
isym CCCCCCC001110100
IMCAR: only in car of evaluated code, cdr has cell's GC bit
ispcsym 000CCCC00CCCC100
iloc 0DDDDDDDDDDDEFFFFFFFFFFF11111100
pointer PPPPPPPPPPPPPPPPPPPPPPPPPPPPP000
gloc PPPPPPPPPPPPPPPPPPPPPPPPPPPPP001
HEAP CELL: G=gc_mark; 1 during mark, 0 other times.
1s and 0s here indicate type. G missing means sys (not GC'd)
SIMPLE:
cons ..........SCM car..............0 ...........SCM cdr.............G
closure ..........SCM code...........011 ...........SCM env.............G
HEADERs:
ssymbol .........long length....G0000101 ..........char *chars...........
msymbol .........long length....G0000111 ..........char *chars...........
string .........long length....G0001101 ..........char *chars...........
vector .........long length....G0001111 ...........SCM **elts...........
bvect .........long length....G0010101 ..........long *words...........
spare G0010111
ivect .........long length....G0011101 ..........long *words...........
uvect .........long length....G0011111 ......unsigned long *words......
spare G0100101
spare G0100111
fvect .........long length....G0101101 .........float *words...........
dvect .........long length....G0101111 ........double *words...........
cvect .........long length....G0110101 ........double *words...........
contin .........long length....G0111101 .............*regs..............
cclo .........long length....G0111111 ...........SCM **elts...........
SUBRs:
spare 010001x1
spare 010011x1
subr_0 ..........int hpoff.....01010101 ...........SCM (*f)()...........
subr_1 ..........int hpoff.....01010111 ...........SCM (*f)()...........
cxr ..........int hpoff.....01011101 .........double (*f)()..........
subr_3 ..........int hpoff.....01011111 ...........SCM (*f)()...........
subr_2 ..........int hpoff.....01100101 ...........SCM (*f)()...........
asubr ..........int hpoff.....01100111 ...........SCM (*f)()...........
subr_1o ..........int hpoff.....01101101 ...........SCM (*f)()...........
subr_2o ..........int hpoff.....01101111 ...........SCM (*f)()...........
lsubr_2 ..........int hpoff.....01110101 ...........SCM (*f)()...........
rpsubr ..........int hpoff.....01111101 ...........SCM (*f)()...........
PTOBs:
port 0bwroxxxxxxxxG1110111 ..........FILE *stream..........
socket ttttttt 00001xxxxxxxxG1110111 ..........FILE *stream..........
inport uuuuuuuuuuU00011xxxxxxxxG1110111 ..........FILE *stream..........
outport 0000000000000101xxxxxxxxG1110111 ..........FILE *stream..........
ioport uuuuuuuuuuU00111xxxxxxxxG1110111 ..........FILE *stream..........
fport 00 00000000G1110111 ..........FILE *stream..........
pipe 00 00000001G1110111 ..........FILE *stream..........
strport 00 00000010G1110111 ..........FILE *stream..........
sfport 00 00000011G1110111 ..........FILE *stream..........
SMOBs:
free_cell
000000000000000000000000G1111111 ...........*free_cell........000
flo 000000000000000000000001G1111111 ...........float num............
dblr 000000000000000100000001G1111111 ..........double *real..........
dblc 000000000000001100000001G1111111 .........complex *cmpx..........
bignum ...int length...0000001 G1111111 .........short *digits..........
bigpos ...int length...00000010G1111111 .........short *digits..........
bigneg ...int length...00000011G1111111 .........short *digits..........
xxxxxxxx = code assigned by newsmob();
promise 000000000000000fxxxxxxxxG1111111 ...........SCM val..............
arbiter 000000000000000lxxxxxxxxG1111111 ...........SCM name.............
macro 000000000000000mxxxxxxxxG1111111 ...........SCM name.............
array ...short rank..cxxxxxxxxG1111111 ............*array..............
The garbage collector is in the latter half of `sys.c'. The primary goal of garbage collection (or GC) is to recycle those cells no longer in use. Immediates always appear as parts of other objects, so they are not subject to explicit garbage collection.
All cells reside in the heap (composed of heap segments). Note that this is different from what Computer Science usually defines as a heap.
The first step in garbage collection is to mark all heap objects
in use. Each heap cell has a bit reserved for this purpose. For pairs
(cons cells) the lowest order bit (0) of the CDR is used. For other
types, bit 8 of the CAR is used. The GC bits are never set except
during garbage collection. Special C macros are defined in `scm.h'
to allow easy manipulation when GC bits are possibly set. CAR,
TYP3, and TYP7 can be used on GC marked cells as they are.
We need to (recursively) mark only a few objects in order to assure that
all accessible objects are marked. Those objects are
sys_protects[] (for example, dynwinds), the current
C-stack and the hash table for symbols, symhash.
gc_mark() is used for marking SCM cells. If
obj is marked, gc_mark() returns. If obj is
unmarked, gc_mark sets the mark bit in obj, then calls
gc_mark() on any SCM components of obj. The last call to
gc_mark() is tail-called (looped).
mark_locations is used for marking segments of
C-stack or saved segments of C-stack (marked continuations). The
argument len is the size of the stack in units of size
(STACKITEM).
Each longword in the stack is tried to see if it is a valid cell pointer
into the heap. If it is, the object itself and any objects it points to
are marked using gc_mark. If the stack is word rather than
longword aligned (#define WORD_ALIGN), both alignments are tried.
This arrangement will occasionally mark an object which is no longer
used. This has not been a problem in practice and the advantage of
using the c-stack far outweighs it.
After all found objects have been marked, the heap is swept.
The storage for strings, vectors, continuations, doubles, complexes, and bignums is managed by malloc. There is only one pointer to each malloc object from its type-header cell in the heap. This allows malloc objects to be freed when the associated heap object is garbage collected.
gc_sweep scans through all heap segments. The mark
bit is cleared from marked cells. Unmarked cells are spliced into
freelist, where they can again be returned by invocations of
NEWCELL.
If a type-header cell pointing to malloc space is unmarked, the malloc
object is freed. If the type header of smob is collected, the smob's
free procedure is called to free its storage.
SIGINT and
SIGALRM if they are supported by the C implementation. All of
the signal handlers immediately reestablish themselves by a call to
signal().
SIGINT and SIGALRM.
If an interrupt handler is defined when the interrupt is received, the
code is interpreted. If the code returns, execution resumes from where
the interrupt happened. Call-with-current-continuation allows
the stack to be saved and restored.
SCM does not use any signal masking system calls. These are not a
portable feature. However, code can run uninterrupted by use of the C
macros DEFER_INTS and ALLOW_INTS.
ints_disabled to 1. If an interrupt
occurs during a time when ints_disabled is 1 one of the global
variables sig_deferred or alrm_deferred is set to 1 and
the handler returns.
Calls to DEFER_INTS can not be nested. An ALLOW_INTS must
happen before another DEFER_INTS can be done. In order to check
that this constraint is satisfied #define CAREFUL_INTS in
`scmfig.h'.
ARGn (> 5 or unknown ARG number)
ARG1
ARG2
ARG3
ARG4
ARG5
WNA (wrong number of args)
OVFLOW
OUTOFRANGE
NALLOC
EXIT
HUP_SIGNAL
INT_SIGNAL
FPE_SIGNAL
BUS_SIGNAL
SEGV_SIGNAL
ALRM_SIGNAL
(char *)
Error checking is not done by ASSERT if the flag RECKLESS
is defined. An error condition can still be signaled in this case with
a call to wta(arg, pos, subr).
goto label if the expression (cond) is 0. Like
ASSERT, ASRTGO does is not active if the flag
RECKLESS is defined.
When writing C-code for SCM, a precaution is recommended. If your
routine allocates a non-cons cell which will not be incorporated
into a SCM object which is returned, you need to make sure that a
SCM variable in your routine points to that cell as long as part
of it might be referenced by your code.
In order to make sure this SCM variable does not get optimized
out you can put this assignment after its last possible use:
SCM_dummy1 = foo;
or put this assignment somewhere in your routine:
SCM_dummy1 = (SCM) &foo;
SCM_dummy variables are not currently defined. Passing the
address of the local SCM variable to any procedure also
protects it.
Also, if you maintain a static pointer to some (non-immediate)
SCM object, you must either make your pointer be the value cell
of a symbol (see errobj for an example) or make your pointer be
one of the sys_protects (see dynwinds for an example).
The former method is prefered since it does not require any changes to
the SCM distribution.
To add a C routine to scm:
make_subr or make_gsubr call to init_scm. Or
put an entry into the appropriate iproc structure.
To add a package of new procedures to scm (see `crs.c' for example):
static char s_twiddle_bits[]="twiddle-bits!"; static char s_bitsp[]="bits?";
iproc structure for each subr type used in `foo.c'
static iproc subr3s[]= {
{s_twiddle-bits,twiddle-bits},
{s_bitsp,bitsp},
{0,0} };
init_<name of file> routine at the end of the file
which calls init_iprocs with the correct type for each of the
iprocs created in step 5.
void init_foo()
{
init_iprocs(subr1s, tc7_subr_1);
init_iprocs(subr3s, tc7_subr_3);
}
If your package needs to have a finalization routine called to
free up storage, close files, etc, then also have a line in
init_foo like:
add_final(final_foo);
final_foo should be a (void) procedure of no arguments. The
finals will be called in opposite order from their definition.
The line:
add_feature("foo");
will append a symbol 'foo to the (list) value of
*features*.
if into `Init.scm' which loads `Ifoo.scm' if
your package is included:
(if (defined? twiddle-bits!)
(load (in-vicinity (implementation-vicinity)
"Ifoo"
(scheme-file-suffix))))
or use (provided? 'foo) instead of (defined?
twiddle-bits!) if you have added the feature.
init_foo\(\)\; to the INITS=...
line at the beginning of the makefile.
These steps should allow your package to be linked into SCM with a minimum of difficulty. Your package should also work with dynamic linking if your SCM has this capability.
Special forms (new syntax) can be added to scm.
MAKISYM in `scm.h' and increment
NUM_ISYMS.
isymnames in `repl.c'.
case: clause to ceval() near i_quasiquote (in
`eval.c').
New syntax can now be added without recompiling SCM by the use of the
procedure->syntax, procedure->macro,
procedure->memoizing-macro, and defmacro. For details,
See section Syntax Extensions.
If CCLO is #defined when compiling, the compiled closure
feature will be enabled. It is automatically enabled if dynamic linking
is enabled.
The SCM interpreter directly recognizes subrs taking small numbers of arguments. In order to create subrs taking larger numbers of arguments use:
char *
name which takes int req required arguments,
int opt optional arguments, and a list of rest arguments if
int rest is 1 (0 for not).
SCM (*fcn)() is a pointer to a C function to do the work.
The C function will always be called with req + opt +
rest arguments, optional arguments not supplied will be passed
UNDEFINED. An error will be signaled if the subr is called with
too many or too few arguments. Currently a total of 10 arguments may be
specified, but increasing this limit should not be difficult.
/* A silly example, taking 2 required args,
1 optional, and a list of rest args */
#include <scm.h>
SCM gsubr_21l(req1,req2,opt,rst)
SCM req1,req2,opt,rst;
{
lputs("gsubr-2-1-l:\n req1: ", cur_outp);
display(req1,cur_outp);
lputs("\n req2: ", cur_outp);
display(req2,cur_outp);
lputs("\n opt: ", cur_outp);
display(opt,cur_outp);
lputs("\n rest: ", cur_outp);
display(rst,cur_outp);
newline(cur_outp);
return UNSPECIFIED;
}
void init_gsubr211()
{
make_gsubr("gsubr-2-1-l", 2, 1, 1, gsubr_21l);
}
Here is an example of how to add a new type named foo to SCM.
The following lines need to be added to your code:
long tc16_foo;
static smobfuns foosmob = {markfoo,freefoo,printfoo,equalpfoo};
typedef struct {
SCM (*mark)P((SCM));
sizet (*free)P((CELLPTR));
int (*print)P((SCM exp, SCM port, int writing));
SCM (*equalp)P((SCM, SCM));
} smobfuns;
smob.mark
SCM (the cell to mark) and
returns type SCM which will then be marked. If no further
objects need to be marked then return an immediate object such as
BOOL_F. 2 functions are provided:
markcdr(ptr)
CDR(ptr).
mark0(ptr)
BOOL_F.
smob.free
CELLPTR (the cell to
collected) and returns type sizet which is the number of
malloced bytes which were freed. Smob.free should free
any malloced storage associated with this object. The function
free0(ptr) is provided which does not free any storage and returns 0.
smob.print
SCM, is
the smob object. The second, of type SCM, is the stream on which
to write the result. The third, of type int, is 1 if the object should
be writen, 0 if it should be displayed. This function
should return non-zero if it printed, and zero otherwise (in which case
a hexadecimal number will be printed).
smob.equalp
SCM arguments. Both of these arguments
will be of type tc16foo. This function should return
BOOL_T if the smobs are equal, BOOL_F if they are not. If
smob.equalp is 0, equal? will return BOOL_F if they
are not eq?.
tc16_foo = newsmob(&foosmob);
foosmob. This
line goes in an init_ routine.
Promises and macros in `eval.c' and arbiters in `repl.c' provide examples of SMOBs. There are a maximum of 256 SMOBs.
ptobs are similar to smobs but define new types of port to which
SCM procedures can read or write. The following functions are defined
in the ptobfuns:
typedef struct {
SCM (*mark)P((SCM ptr));
int (*free)P((FILE *p));
int (*print)P((SCM exp, SCM port, int writing));
SCM (*equalp)P((SCM, SCM));
int (*fputc)P((int c, FILE *p));
int (*fputs)P((char *s, FILE *p));
sizet (*fwrite)P((char *s, sizet siz, sizet num, FILE *p));
int (*fflush)P((FILE *stream));
int (*fgetc)P((FILE *p));
int (*fclose)P((FILE *p));
} ptobfuns;
The .free component to the structure takes a FILE * or
other C construct as its argument, unlike .free in a smob, which
takes the whole smob cell. Often, .free and .fclose can be
the same function. See fptob and pipob in `sys.c'
for examples of how to define ptobs.
To use SCM as a whole from another program call init_scm or
run_scm as is done in main() in `scm.c'.
In order to call indivdual Scheme procedures from C code more is required; SCM's storage system needs to be initialized. The simplest way to do this for a statically linked single-thread program is to:
#define RTL flag when compiling `scm.c' to elide
SCM's main().
main(), call run_scm with arguments (argc
and argv) to invoke your code's startup routine.
For a dynamically linked single-thread program:
init_ procedure for your code which will set up any Scheme
definitions you need and then call your startup routine
(see section Changing Scm).
init_ procedure will be called, and
hence your startup routine.
Now use apply (and perhaps intern) to call Scheme
procedures from your C code. For example:
/* If this apply fails, SCM will catch the error */
apply(CDR(intern("srv:startup",sizeof("srv:startup")-1)),
mksproc(srvproc),
listofnull);
func = CDR(intern(rpcname,strlen(rpcname)));
retval = apply(func, cons(mksproc(srvproc), args), EOL);
SCM now has routines to make calling back to Scheme procedures easier. The source code for these routines are found in `rope.c'.
(in-vicinity (program-vicinity)
file). Returns 0 if successful, non-0 if not.
This function is useful for compiled code init_ functions to load
non-compiled Scheme (source) files. program-vicinity is the
directory from which the calling code was loaded (see section `Vicinity' in SLIB).
If you wish to catch errors during execution of Scheme code, then you can use a wrapper like this for your Scheme procedures:
(define (srv:protect proc)
(lambda args
(define result #f) ; put default value here
(call-with-current-continuation
(lambda (cont)
(dynamic-wind (lambda () #t)
(lambda ()
(set! result (apply proc args))
(set! cont #f))
(lambda ()
(if cont (cont #f))))))
result))
Calls to procedures so wrapped will return even if an error occurs.
These type conversion functions are very useful for connecting SCM and C code. Most are defined in `rope.c'.
SCM corresponding to the long or
unsigned long argument n. If n cannot be converted,
BOOL_F is returned. Which numbers can be converted depends on
whether SCM was compiled with the BIGDIG or FLOATS flags.
To convert integer numbers of smaller types (short or
char), use the macro MAKINUM(n).
SCM arguments to
the named C type. The first argument num is checked to see it it
is within the range of the destination type. If so, the converted
number is returned. If not, the ASSERT macro calls wta
with num and strings pos and s_caller. For a listing
of useful predefined pos macros, See section C Macros.
Note: Inexact numbers are accepted only by num2long and
num2ulong (for when SCM is compiled without bignums). To
convert inexact numbers to exact numbers, See section `Numerical operations' in Revised(4) Scheme.
unsigned long) to the storage
corresponding to the location accessed by
aref(CAR(args),CDR(args)). The string s_name is used in
any messages from error calls by scm_addr.
scm_addr is useful for performing C operations on strings or
other uniform arrays (see section Uniform Array).
Note: While you use a pointer returned from scm_addr you
must keep a pointer to the associated SCM object in a stack
allocated variable or GC-protected location in order to assure that SCM
does not reuse that storage before you are done with it.
SCM object copy of the
null-terminated string src or the string src of length
len, respectively.
SCM list of strings corresponding to
the argc length array of null-terminated strings argv. If
argv is less than 0, argv is assumed to be
NULL terminated. makfromstrs is used by run_scm to
convert the arguments SCM was called with to a SCM list which is
the value of SCM procedure calls to program-arguments
(see section SCM Session).
NULL terminated list of null-terminated strings copied
from the SCM list of strings args. The string s_name
is used in messages from error calls by makargvfrmstrs.
makargvfrmstrs is useful for constructing argument lists suitable
for passing to main functions.
makargvfrmstrs.
The source files `continue.h' and `continue.c' are designed to function as an independent resource for programs wishing to use continuations, but without all the rest of the SCM machinery. The concept of continuations is explained in section `Control features' in Revised(4) Scheme.
The C constructs jmp_buf, setjmp, and longjmp
implement escape continuations. On VAX and Cray platforms, the setjmp
provided does not save all the registers. The source files
`setjump.mar', `setjump.s', and `ugsetjump.s' provide
implementations which do meet this criteria.
SCM uses the names jump_buf, setjump, and longjump
in lieu of jmp_buf, setjmp, and longjmp to prevent
name and declaration conflicts.
typedefed structure holding all the information needed to
represent a continuation. The other slot can be used to hold any
data the user wishes to put there by defining the macro
CONTINUATION_OTHER.
SHORT_ALIGN is #defined (in `scmfig.h'), then the
it is assumed that pointers in the stack can be aligned on short
int boundaries.
SHORT_ALIGN
being #defined or not.
CHEAP_CONTINUATIONS is #defined (in `scmfig.h')
each CONTINUATION has size sizeof CONTINUATION.
Otherwise, all but root CONTINUATIONs have additional
storage (immediately following) to contain a copy of part of the stack.
Note: On systems with nonlinear stack disciplines (multiple
stacks or non-contiguous stack frames) copying the stack will not work
properly. These systems need to #define CHEAP_CONTINUATIONS in
`scmfig.h'.
#defined or not.
throw_to_continuation.
STACKITEM which fit between
start and the current top of stack. No check is done in this
routine to ensure that start is actually in the current stack
segment.
malloc) storage for a CONTINUATION of the
current extent of stack. This newly allocated CONTINUATION is
returned if successful, 0 if not. After
make_root_continuation returns, the calling routine still needs
to setjump(new_continuation->jmpbuf) in order to complete
the capture of this continuation.
CONTINUATION, copying (or
encapsulating) the stack state from parent_cont->stkbse to
the current top of stack. The newly allocated CONTINUATION is
returned if successful, 0q if not. After
make_continuation returns, the calling routine still needs to
setjump(new_continuation->jmpbuf) in order to complete the
capture of this continuation.
cont->other.
thrown_value to value and returns from the
continuation cont.
If CHEAP_CONTINUATIONS is #defined, then
throw_to_continuation does longjump(cont->jmpbuf, val).
If CHEAP_CONTINUATIONS is not #defined, the CONTINUATION
cont contains a copy of a portion of the C stack (whose bound must
be CONT(root_cont)->stkbse). Then:
longjump(cont->jmpbuf, val);
SCM uses its type representations to speed evaluation. All of the
subr types (see section Subr Cells) are tc7 types. Since the
tc7 field is in the low order bit position of the CAR it
can be retrieved and dispatched on quickly by dereferencing the SCM
pointer pointing to it and masking the result.
All the SCM Special Forms get translated to immediate symbols
(isym) the first time they are encountered by the interpreter
(ceval). The representation of these immediate symbols is
engineered to occupy the same bits as tc7. All the isyms
occur only in the CAR of lists.
If the CAR of a expression to evaluate is not immediate, then it
may be a symbol. If so, the first time it is encountered it will be
converted to an immediate type ILOC or GLOC
(see section Immediates). The codes for ILOC and GLOC lower 7
bits distinguish them from all the other types we have discussed.
Once it has determined that the expression to evaluate is not immediate,
ceval need only retrieve and dispatch on the low order 7 bits of
the CAR of that cell, regardless of whether that cell is a
closure, header, or subr, or a cons containing ILOC or
GLOC.
In order to be able to convert a SCM symbol pointer to an immediate ILOC
or GLOC, the evaluator must be holding the pointer to the list in which
that symbol pointer occurs. Turning this requirement to an advantage,
ceval does not recursively call itself to evaluate symbols in
lists; It instead calls the macro EVALCAR. EVALCAR does
symbol lookup and memoization for symbols, retrieval of values for ILOCs
and GLOCs, returns other immediates, and otherwise recursively calls
itself with the CAR of the list.
ceval inlines evaluation (using EVALCAR) of almost all
procedure call arguments. When ceval needs to evaluate a list of
more than length 3, the procedure eval_args is called. So
ceval can be said to have one level lookahead. The avoidance of
recursive invocations of ceval for the most common cases (special
forms and procedure calls) results in faster execution. The speed of
the interpreter is currently limited on most machines by interpreter
size, probably having to do with its cache footprint. In order to keep
the size down, certain EVALCAR calls which don't need to be fast
(because they rarely occur or because they are part of expensive
operations) are instead calls to the C function evalcar.
There was some discussion a year ago about a "Forth" style Scheme interpreter. This is the only improvement I know of which would beat SCM in speed.
Provided there is still type code space available in SCM, if we devote some of the IMCAR codes to "inlined" operations, we should get a significant performance boost. What is eliminated is the having to look up a
GLOCorILOCand then dispatch on the subr type. The IMCAR operation would be dispatched to directly. Another way to view this is that we make available special form versions ofCAR,CDR, etc. Since the actual operation code is localized in the interpreter, it is much easier than uncompilation and then recompilation to handle(trace car); For instance a switch gets set which tells the interpreter to instead always look up the values of the associated symbols.
symhash table.
symhash is an array of lists of ISYMs and pairs of symbols
and values.
ILOC) which specifies how many environment frames down and how
far in to go for the value. When this immediate object is subsequently
encountered, the value can be retrieved quickly.
GLOC. The low order bit is normally reserved for
GCmark; But, since references to variables in the code always occur in
the CAR position and the GCmark is in the CDR, there is no
conflict.
If the compile FLAG CAUTIOUS is #defined then the number of
arguments is always checked for application of closures. If the compile
FLAG RECKLESS is #defined then they are not checked. Otherwise,
number of argument checks for closures are made only when the function
position (whose value is the closure) of a combination is not an
ILOC or GLOC. When the function position of a combination
is a symbol it will be checked only the first time it is evaluated
because it will then be replaced with an ILOC or GLOC.
EVAL Returns the result of evaluating expression in
env. SIDEVAL evaluates expression in env when
the value of the expression is not used.
Both of these macros alter the list structure of expression as it
is memoized and hence should be used only when it is known that
expression will not be referenced again. The C function
eval is safe from this problem.
eval copies expression so that memoization
does not modify expression.
Where should software reside? Although individually a minor annoyance, cumulatively this question represents many thousands of frustrated user hours spent trying to find support files or guessing where packages need to be installed. Even simple programs require proper habitat; games need to find their score files.
Aren't there standards for this? Some Operating Systems have devised regimes of software habitats -- only to have them violated by large software packages and imports from other OS varieties.
In some programs, the expected locations of support files are fixed at time of compilation. This means that the program may not run on configurations unanticipated by the authors. Compiling locations into a program also can make it immovable -- necessitating recompilation to install it.
Programs of the world unite! You have nothing to lose but loss itself.
The function scm_find_impl_file in `scm.c' is an attempt to
create a utility (for inclusion in programs) which will hide the details
of platform-dependent file habitat conventions. It takes as input the
pathname of the executable file which is running. If there are systems
for which this information is either not available or unrelated to the
locations of support files, then a higher level interface will be
needed.
For purposes of finding `Init.scm', dumping an executable, and dynamic linking, a SCM session needs the pathname of its executable image.
When a program is executed by MS-DOS, the full pathname of that
executable is available in argv[0]. This value can be passed
directly to scm_find_impl_file (see section File-System Habitat).
In order to find the habitat for a unix program, we first need to know the full pathname for the associated executable file.
dld_find_executable returns the absolute path name of the file
that would be executed if command were given as a command. It
looks up the environment variable PATH, searches in each of the
directory listed for command, and returns the absolute path name
for the first occurrence. Thus, it is advisable to invoke
dld_init as:
main (int argc, char **argv)
{
...
if (dld_init (dld_find_executable (argv[0]))) {
...
}
...
}
Note: If the current process is executed using the
execvecall without passing the correct path name as argument 0,dld_find_executable (argv[0])will also fail to locate the executable file.
dld_find_executable returns zero if command is not found
in any of the directories listed in PATH.
Source code for these C functions is in the file `script.c'. section Shell Scripts for a description of script argument processing.
script_find_executable is only defined on unix systems.
script_find_executable returns the path name of the
executable which will is invoked by the script file name;
name if it is a binary executable (not a script); or 0 if
name does not exist or is not executable.
script_process_argv returns a newly
allocated argument vector in which the second line of the script being
invoked is substituted for the corresponding meta-argument.
If the script does not have a meta-argument, or if the file named by the argument following a meta-argument cannot be opened for reading, then 0 is returned.
script_process_argv correctly processes argument vectors of
nested script invocations.
lgcd() needs to generate at most one bignum, but currently
generates more.
divide() could use shifts instead of multiply and divide when
scaling.
dumping an executable does not preserve ports. When
loading a dumped executable, disk files could be reopened to the
same file and position as they had when the executable was dumped.
malloced objects by freeing and
reallocing all the malloc objects encountered in a scan of the heap.
Whether compactions would actually occur is system depenedent.
must- or make- routines need some sort of C macros or
conditionalization so that they check:
LENGTH field fits into a size_t (as is checked
now) for platforms with (sizeof(size_t) < sizeof(SCM)).
LENGTH field fits into 24 (or 56) bits on machines where
size_t is 32 bits or more.
LENGTH field restriction. Putting the 24 bit test into
must_malloc() should be tested for speed impact.
Scott Schwartz <schwartz@galapagos.cse.psu.edu> suggests: One way to tidy up the dynamic loading stuff would be to grab the code from perl5.
George Carrette (gjc@mitech.com) outlines how to dynamically link on VMS. There is already some code in `dynl.c' to do this, but someone with a VMS system needs to finish and debug it.
main()
{init_lisp();
lisp_repl();}
eval.c and there are some toplevel non-static variables in use
called the_heap, the_environment, and some read-only
toplevel structures, such as the_subr_table.
$ LINK/SHARE=LISPRTL.EXE/DEBUG REPL.OBJ,GC.OBJ,EVAL.OBJ,LISPRTL.OPT/OPT
SYS$LIBRARY:VAXCRTL/SHARE UNIVERSAL=init_lisp UNIVERSAL=lisp_repl PSECT_ATTR=the_subr_table,SHR,NOWRT,LCL PSECT_ATTR=the_heap,NOSHR,LCL PSECT_ATTR=the_environment,NOSHR,LCLNotice: The psect (Program Section) attributes.
LCL
SHR,NOWRT
NOSHR,LCL
$SEARCH/OUT=LISPRTL.LOSERS LISPRTL.MAP ", SHR,NOEXE, RD, WRT"And use an emacs keyboard macro to muck the result into the proper form. Of course only the programmer can tell if things can be made read-only. I have a DCL command procedure to do this if you want it.
$ DEFINE LISPRTL USER$DISK:[JAFFER]LISPRTL.EXE $LINK MAIN.OBJ,SYS$INPUT:/OPT SYS$LIBRARY:VAXCRTL/SHARE LISPRTL/SHARENote the definition of the
LISPRTL logical name. Without such a
definition you will need to copy `LISPRTL.EXE' over to
`SYS$SHARE:' (aka `SYS$LIBRARY:') in order to invoke the main
program once it is linked.
INIT_MYSUBRS that must be called before using it.
$ CC MYSUBRS.C $ LINK/SHARE=MYSUBRS.EXE MYSUBRS.OBJ,SYS$INPUT:/OPT SYS$LIBRARY:VAXCRTL/SHARE LISPRTL/SHARE UNIVERSAL=INIT_MYSUBRSOk. Another hint is that you can avoid having to add the
PSECT
declaration of NOSHR,LCL by declaring variables status in
the C language source. That works great for most things.
{void (*init_fcn)();
long retval;
retval = lib$find_image_symbol("MYSUBRS","INIT_MYSUBRS",&init_fcn,
"SYS$DISK:[].EXE");
if (retval != SS$_NORMAL) error(...);
(*init_fcn)();}
But of course all string arguments must be (struct dsc$descriptor
*) and the last argument is optional if MYSUBRS is defined as a
logical name or if `MYSUBRS.EXE' has been copied over to
`SYS$SHARE'. The other consideration is that you will want to turn
off C-c or other interrupt handling while you are inside most
lib$ calls.
As far as the generation of all the UNIVERSAL=...
declarations. Well, you could do well to have that automatically
generated from the public `LISPRTL.H' file, of course.
VMS has a good manual called the Guide to Writing Modular
Procedures or something like that, which covers this whole area rather
well, and also talks about advanced techniques, such as a way to declare
a program section with a pointer to a procedure that will be
automatically invoked whenever any shared image is dynamically
activated. Also, how to set up a handler for normal or abnormal program
exit so that you can clean up side effects (such as opening a database).
But for use with LISPRTL you probably don't need that hair.
One fancier option that is useful under VMS for `LISPLIB.EXE' is to
define all your exported procedures through an call vector instead
of having them just be pointers into random places in the image, which
is what you get by using UNIVERSAL.
If you set up the call vector thing correctly it will allow you to
modify and relink `LISPLIB.EXE' without having to relink programs
that have been linked against it.
George Carrette (gjc@mitech.com) outlines how to dynamically link on Windows NT:
LISPLIB.exp:
LISPLIB.lib: LISPLIB.def
$(implib) -machine:$(CPU) -def:LISPLIB.def -out:LISPLIB.lib
LISPLIB.DLL : $(LISPLIB_OBJS) LISPLIB.EXP
$(link) $(linkdebug) \
-dll \
-out:LISPLIB.DLL \
LISPLIB.EXP $(LISPLIB_OBJS) $(conlibsdll)
LIBRARY lisplib EXPORT init_lisp init_repl
CLINK = $(link) $(ldebug) $(conflags) -out:$*.exe $** $(conlibsdll) MAIN.EXE : MAIN.OBJ LISPLIB.LIB $(CLINK)
mysubrs.exp:
mysubrs.lib: mysubrs.def
$(implib) -machine:$(CPU) -def:MYSUBRS.def -out:MYSUBRS.lib
mysubrs.dll : mysubrs.obj mysubrs.exp mysubrs.lib
$(link) $(linkdebug) \
-dll \
-out:mysubrs.dll \
MYSUBRS.OBJ MYSUBRS.EXP LISPLIB.LIB $(conlibsdll)
LIBRARY mysubrs EXPORT INIT_MYSUBRS
LoadLibrary and GetProcAddress.
LISP share_image_load(LISP fname)
{long iflag;
LISP retval,(*fcn)(void);
HANDLE hLib;
DWORD err;
char *libname,fcnname[64];
iflag = nointerrupt(1);
libname = c_string(fname);
_snprintf(fcnname,sizeof(fcnname),"INIT_%s",libname);
if (!(hLib = LoadLibrary(libname)))
{err = GetLastError();
retval = list2(fname,LSPNUM(err));
serror1("library failed to load",retval);}
if (!(fcn = (LISP (*)(void)) GetProcAddress(hLib,fcnname)))
{err = GetLastError();
retval = list2(fname,LSPNUM(err));
serror1("could not find library init procedure",retval);}
retval = (*fcn)();
nointerrupt(iflag);
return(retval);}
This is an alphabetical list of all the procedures and macros in SCM.
This is an alphabetical list of all the global variables in SCM.
This is an alphabetical list of data types and feature names in SCM.
This document was generated on 13 December 1997 using the texi2html translator version 1.51.