diff options
Diffstat (limited to 'scm.texi')
| -rw-r--r-- | scm.texi | 1947 |
1 files changed, 1150 insertions, 797 deletions
@@ -2,6 +2,7 @@ @c %**start of header @setfilename scm.info @settitle SCM +@include version.txi @setchapternewpage on @c Choices for setchapternewpage are {on,off,odd}. @paragraphindent 0 @@ -24,13 +25,12 @@ @titlepage @title SCM @subtitle Scheme Implementation -@subtitle Version 5c3 -@subtitle April 1998 +@subtitle Version @value{SCMVERSION} @author by Aubrey Jaffer @page @vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation +Copyright @copyright{} 1990-1999 Free Software Foundation Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -51,13 +51,14 @@ by the author. @ifinfo -This manual documents the SCM Scheme implementation. The most recent +This manual documents the SCM Scheme implementation. SCM version +@value{SCMVERSION} was released @value{SCMDATE}. The most recent information about SCM can be found on SCM's @dfn{WWW} home page: @center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html} -Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation +Copyright (C) 1990-1999 Free Software Foundation Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -102,7 +103,14 @@ machine independent platform for [JACAL], a symbolic algebra system. @noindent The most recent information about SCM can be found on SCM's @dfn{WWW} home page: + +@ifset html +<A HREF="http://swissnet.ai.mit.edu/~jaffer/SCM.html"> +@end ifset @center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html} +@ifset html +</A> +@end ifset @end iftex @menu @@ -152,7 +160,7 @@ Cambridge, MA 02138 @center Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 @center Free Software Foundation, Inc. -@center 675 Mass Ave, Cambridge, MA 02139, USA +@center 59 Temple Place, Suite 330, Boston, MA 02111, USA @noindent Permission to use, copy, modify, distribute, and sell this software and @@ -190,10 +198,10 @@ OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. @itemize @bullet @item -Conforms to Revised^4 Report on the Algorithmic Language Scheme [R4RS] +Conforms to Revised^5 Report on the Algorithmic Language Scheme [R5RS] and the [IEEE] P1178 specification. @item -Support for [SICP], [R2RS], [R3RS], and (proposed) [R5RS] scheme code. +Support for [SICP], [R2RS], [R3RS], and [R5RS] scheme code. @item Runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, NOS/VE, Unicos, VMS, Unix and similar systems. Supports ASCII and EBCDIC character sets. @@ -239,10 +247,11 @@ timing information printed interactively (the @code{verbose} function). @section Authors @table @b -@item Aubrey Jaffer (jaffer@@ai.mit.edu) +@item Aubrey Jaffer (jaffer @@ ai.mit.edu) Most of SCM. @item Radey Shouman -Arrays. @code{gsubr}s, compiled closures, and records. +Arrays. @code{gsubr}s, compiled closures, records, Ecache, syntax-rules +macros, and @dfn{safeport}s. @item Jerry D. Hedden Real and Complex functions. Fast mixed type arithmetics. @item Hugh Secker-Walker @@ -264,12 +273,12 @@ file @file{ChangeLog}, a log of changes that have been made to scm. @table @asis @item [IEEE] -@pindex IEEE +@cindex IEEE @cite{IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming Language.} IEEE, New York, 1991. @item [Simply] -@pindex Simply +@cindex Simply Brian Harvey and Matthew Wright. @ifset html <A HREF="http://HTTP.CS.Berkeley.EDU/~bh/simply-toc.html"> @@ -281,13 +290,13 @@ Brian Harvey and Matthew Wright. MIT Press, 1994 ISBN 0-262-08226-8 @item [SICP] -@pindex SICP +@cindex SICP Harold Abelson and Gerald Jay Sussman with Julie Sussman. @cite{Structure and Interpretation of Computer Programs.} MIT Press, Cambridge, 1985. @item [R4RS] -@pindex R4RS +@cindex R4RS William Clinger and Jonathan Rees, Editors. @ifset html <A HREF="r4rs_toc.html"> @@ -304,8 +313,40 @@ pp. 1-55. Scheme}. @end ifinfo +@item [R5RS] +@cindex R5RS +Richard Kelsey and William Clinger and Jonathan (Rees, editors) +@ifset html +<A HREF="r5rs_toc.html"> +@end ifset +Revised(5) Report on the Algorithmic Language Scheme. +@ifset html +</A> +@end ifset +@cite{Higher-Order and Symbolic Computation} Volume 11, Number 1 (1998), +pp. 7-105, and +@cite{ACM SIGPLAN Notices} 33(9), September 1998. +@ifinfo + +@ref{Top, , , r5rs, Revised(5) Report on the Algorithmic Language +Scheme}. +@end ifinfo + +@item [Exrename] +@cindex Exrename +William Clinger +@ifset html +<A HREF="http://www.cs.indiana.edu/scheme-repository/doc.proposals.html"> +@end ifset +Hygienic Macros Through Explicit Renaming +@ifset html +</A> +@end ifset +@cite{Lisp Pointers} Volume IV, Number 4 (December 1991), +pp 17-23. + @item [GUILE] -@pindex GUILE +@cindex GUILE Tom Lord. @ifset html <A HREF="http://www.cygnus.com/library/ctr/guile.html"> @@ -317,7 +358,7 @@ The Guile Architecture for Ubiquitous Computing. @cite{Usenix Symposium on Tcl/Tk}, 1995. @item [SLIB] -@pindex SLIB +@cindex SLIB Todd R. Eigenschink, Dave Love, and Aubrey Jaffer. @ifset html <A HREF="slib_toc.html"> @@ -326,14 +367,14 @@ SLIB, The Portable Scheme Library. @ifset html </A> @end ifset -Version 2a3, June 1995. +Version 2c5, Jan 1999. @ifinfo @ref{Top, , , slib, SLIB}. @end ifinfo @item [JACAL] -@pindex JACAL +@cindex JACAL Aubrey Jaffer. @ifset html <A HREF="jacal_toc.html"> @@ -342,7 +383,7 @@ JACAL Symbolic Mathematics System. @ifset html </A> @end ifset -Version 1a5, April 1994. +Version 1a9, Jan 1999. @ifinfo @ref{Top, , , jacal, JACAL}. @@ -355,6 +396,9 @@ Version 1a5, April 1994. Documentation of @code{scm} extensions (beyond Scheme standards). Documentation on the internal representation and how to extend or include @code{scm} in other programs. +@item Xlibscm.texi +@itemx Xlibscm.info +Documentation of the Xlib - SCM Language X Interface. @end table @node Installing SCM, Operational Features, Overview, Top @@ -401,7 +445,7 @@ script to build SCM; Create your own script or @file{Makefile}. @item -Buy a SCM executable from jaffer@@ai.mit.edu. See the end of the +Buy a SCM executable from jaffer @@ ai.mit.edu. See the end of the @file{ANNOUNCE} file in the distribution for details. @item @@ -430,41 +474,41 @@ low priority. SLIB is available from the same sites as SCM: @ifclear html @itemize @bullet @item -swissnet.ai.mit.edu:/pub/scm/slib2c3.tar.gz -@item -prep.ai.mit.edu:/pub/gnu/jacal/slib2c3.tar.gz +swissnet.ai.mit.edu:/pub/scm/slib2c7.tar.gz @item -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz +ftp.gnu.org:/pub/gnu/jacal/slib2c7.tar.gz @item -ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c3.tar.gz +ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c7.tar.gz @end itemize @end ifclear @ifset html -<A HREF="file://swissnet.ai.mit.edu/pub/scm/slib2c3.tar.gz"> -swissnet.ai.mit.edu:/pub/scm/slib2c3.tar.gz -</A> -<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2c3.tar.gz"> -prep.ai.mit.edu:/pub/gnu/jacal/slib2c3.tar.gz +@itemize @bullet +@item +<A HREF="http://swissnet.ai.mit.edu/ftpdir/scm/slib2c7.zip"> +http://swissnet.ai.mit.edu/ftpdir/scm/slib2c7.zip </A> -<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2c3.tar.gz"> -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz +@item +<A HREF="ftp://ftp.gnu.org/pub/gnu/jacal/slib2c7.tar.gz"> +ftp.gnu.org:/pub/gnu/jacal/slib2c7.tar.gz </A> -<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c3.tar.gz"> -ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c3.tar.gz +@item +<A HREF="ftp://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c7.tar.gz"> +ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c7.tar.gz </A> +@end itemize @end ifset @noindent -Unpack SLIB (@samp{tar xzf slib2c3.tar.gz} or @samp{unzip -ao -slib2c3.zip}) in an appropriate directory for your system; both +Unpack SLIB (@samp{tar xzf slib2c7.tar.gz} or @samp{unzip -ao +slib2c7.zip}) in an appropriate directory for your system; both @code{tar} and @code{unzip} will create the directory @file{slib}. @noindent Then create a file @file{require.scm} in the SCM @dfn{implementation-vicinity} (this is the same directory as where the -file @file{Init5c3.scm} is installed). @file{require.scm} should have the -contents: +file @file{Init@value{SCMVERSION}.scm} is installed). +@file{require.scm} should have the contents: @example (define (library-vicinity) "/usr/local/lib/slib/") @@ -501,7 +545,7 @@ The file @dfn{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. +additions to jaffer @@ ai.mit.edu. @menu * Invoking Build:: @@ -542,7 +586,7 @@ bash$ ./build.scm @print{} #!/bin/sh rm -f scmflags.h -echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h +echo '#define IMPLINIT "/home/jaffer/scm/Init@value{SCMVERSION}.scm"'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h @@ -554,8 +598,8 @@ gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \ @noindent To cross compile for another platform, invoke build with the @samp{-p} -or @samp{---platform=} option. This will create a script for the -platform named in the @samp{-p} or @samp{---platform=} option. +or @samp{--platform=} option. This will create a script for the +platform named in the @samp{-p} or @samp{--platform=} option. @example bash$ ./build.scm -p vms @@ -563,7 +607,7 @@ bash$ ./build.scm -p vms $DELETE scmflags.h $CREATE scmflags.h $DECK -#define IMPLINIT "/home/jaffer/scm/Init5c3.scm" +#define IMPLINIT "/home/jaffer/scm/Init@value{SCMVERSION}.scm" #define BIGNUMS #define FLOATS #define ARRAYS @@ -594,40 +638,7 @@ are all lower-case. The platforms defined by table @dfn{platform} in @file{build.scm} are: @end deffn @example -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 +@include platform.txi @end example @deffn {Build Option} -o @var{filename} @@ -666,10 +677,10 @@ specifies that that @var{flag} will be put on linker command-lines. @deffn {Build Option} -s @var{pathname} @deffnx {Build Option} ---scheme-initial=@var{pathname} specifies that @var{pathname} should be the default location of the SCM -initialization file @file{Init5c3.scm}. SCM tries several likely locations -before resorting to @var{pathname} (@pxref{File-System Habitat}). -If not specified, the current directory (where build is building) is -used. +initialization file @file{Init@value{SCMVERSION}.scm}. SCM tries +several likely locations before resorting to @var{pathname} +(@pxref{File-System Habitat}). If not specified, the current directory +(where build is building) is used. @end deffn @deffn {Build Option} -c @var{pathname} @dots{} @@ -720,6 +731,8 @@ dos @item vms @item +amigados +@item system This option executes the compilation and linking commands through the @@ -743,137 +756,11 @@ specifies to build the given features into the executable. The defined features are: @table @dfn -@item lit -@itemx none -Lightweight -- no features - -@item cautious -Normally, the number of arguments arguments to interpreted closures - (from LAMBDA) are checked if the function part of a form is not a -symbol or only the first time the form is executed if the function part -is a symbol. defining @samp{reckless} disables any checking. If you -want to have SCM always check the number of arguments to interpreted -closures define feature @samp{cautious}. - -@item careful-interrupt-masking -Define this for extra checking of interrupt masking. This is for -debugging C code in @file{sys.c} and @file{repl.c}. - -@item debug -Turns on features @samp{cautious} @samp{careful-interrupt-masking} -@samp{stack-limit} and uses @code{-g} flags for debugging SCM source -code. - -@item reckless -If your scheme code runs without any errors you can disable almost all -error checking by compiling all files with @samp{reckless}. - -@item stack-limit -Use to enable checking for stack overflow. Define value of the C -preprocessor variable @var{STACK_LIMIT} to be the size to which SCM -should allow the stack to grow. STACK_LIMIT should be less than the -maximum size the hardware can support, as not every routine checks the -stack. - -@item bignums -Large precision integers. - -@item arrays -Use if you want arrays, uniform-arrays and uniform-vectors. - -@item array-for-each -array-map! and array-for-each (arrays must also be defined). - -@item inexact -Use if you want floating point numbers. - -@item engineering-notation -Use if you want floats to display in engineering notation (exponents -always multiples of 3) instead of scientific notation. - -@item single-precision-only -Use if you want all inexact real numbers to be single precision. This -only has an effect if SINGLES is also defined (which is the default). -This does not affect complex numbers. - -@item sicp -Use if you want to run code from: - -H. Abelson, G. J. Sussman, and J. Sussman, -Structure and Interpretation of Computer Programs, -The MIT Press, Cambridge, Massachusetts, USA - -@code{(eq? '() '#f)} is the major difference. +@c @itemx none +@c @cindex none +@c Lightweight -- no features -@item rev2-procedures -These procedures were specified in the @cite{Revised^2 Report on Scheme} -but not in @cite{R4RS}. - -@item record -The Record package provides a facility for user to define their own -record data types. See SLIB for documentation. - -@item compiled-closure -Use if you want to use compiled closures. - -@item generalized-c-arguments -@code{make_gsubr} for arbitrary (< 11) arguments to C functions. - -@item tick-interrupts -Use if you want the ticks and ticks-interrupt functions. - -@item i/o-extensions -Commonly available I/O extensions: @dfn{exec}, line I/O, file -positioning, file delete and rename, and directory functions. - -@item turtlegr -@dfn{Turtle} graphics calls for both Borland-C and X11 from -sjm@@ee.tut.fi. - -@item curses -For the @dfn{curses} screen management package. - -@item edit-line -interface to the editline or GNU readline library. - -@item regex -String regular expression matching. - -@item socket -BSD @dfn{socket} interface. - -@item posix -Posix functions available on all @dfn{Unix-like} systems. fork and -process functions, user and group IDs, file permissions, and @dfn{link}. - -@item unix -Those unix features which have not made it into the Posix specs: nice, -acct, lstat, readlink, symlink, mknod and sync. - -@item windows -Microsoft Windows executable. - -@item dynamic-linking -Be able to load compiled files while running. - -@item dump -Convert a running scheme program into an executable file. - -@item heap-can-shrink -Use if you want segments of unused heap to not be freed up after garbage -collection. This may reduce time in GC for *very* large working sets. - -@item cheap-continuations -If you only need straight stack continuations, executables compile with -this feature will run faster and use less storage than not having it. -Machines with unusual stacks @emph{need} this. Also, if you incorporate -new C code into scm which uses VMS system services or library routines -(which need to unwind the stack in an ordrly manner) you may need to -use this feature. - -@item macro -C level support for hygienic and referentially transparent macros (R4RS -macros). +@include features.txi @end table @end deffn @@ -894,6 +781,7 @@ or both? @noindent (@pxref{Changing Scm} has instructions describing the C code format). @cindex foo.c +@cindex Extending Scm Suppose a C file @dfn{foo.c} has functions you wish to add to SCM. To compile and link your file at compile time, use the @samp{-c} and @samp{-i} options to build: @@ -903,7 +791,7 @@ bash$ build -c foo.c -i init_foo @print{} #!/bin/sh rm -f scmflags.h -echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h +echo '#define IMPLINIT "/home/jaffer/scm/Init@value{SCMVERSION}.scm"'>>scmflags.h echo '#define COMPILED_INITS init_foo();'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h @@ -922,7 +810,7 @@ bash$ build -t dll -c foo.c @print{} #!/bin/sh rm -f scmflags.h -echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h +echo '#define IMPLINIT "/home/jaffer/scm/Init@value{SCMVERSION}.scm"'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h @@ -934,7 +822,7 @@ gcc -shared -o foo.so foo.o -lm -lc @noindent Once @file{foo.c} compiles correctly (and your SCM build supports dynamic-loading), you can load the compiled file with the Scheme command -@code{(load "./foo.so")}. @xref{Configure Module Catalog} for how to +@code{(load "./foo.so")}. See @ref{Configure Module Catalog} for how to add a compiled dll file to SLIB's catalog. @node Installing Dynamic Linking, Configure Module Catalog, Building SCM, Installing SCM @@ -957,13 +845,13 @@ available from: @ifclear html @itemize @bullet @item -prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz +ftp.gnu.org:pub/gnu/dld-3.3.tar.gz @end itemize @end ifclear @ifset html -<A HREF="ftp://prep.ai.mit.edu/pub/gnu/dld-3.3.tar.gz"> -prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz +<A HREF="ftp://ftp.gnu.org/pub/gnu/dld-3.3.tar.gz"> +ftp.gnu.org:pub/gnu/dld-3.3.tar.gz </A> @end ifset @@ -1081,7 +969,7 @@ the compilation command lines or add a @code{#define @var{flag}} line to ------- ---------- ARM_ULIB Huw Rogers free unix library for acorn archimedes AZTEC_C Aztec_C 5.2a -__CYGWIN32__ cygwin32(?) +__CYGWIN__ Cygwin _DCC Dice C on AMIGA __GNUC__ Gnu CC (and DJGPP) __EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0 @@ -1102,6 +990,7 @@ _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 +__FreeBSD__ FreeBSD GNUDOS DJGPP (obsolete in version 1.08) __GO32__ DJGPP (future?) hpux HP-UX @@ -1123,7 +1012,7 @@ 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 +_WIN32 MS VisualC++ 4.2 and Cygwin (Win32 API) vms (and VMS) VAX-11 C under VMS. __alpha DEC Alpha processor @@ -1143,86 +1032,104 @@ vax VAX processor @node Problems Compiling, Problems Linking, Automatic C Preprocessor Definitions, Installing SCM @section Problems Compiling -@table @asis -@item FILE: PROBLEM -HOW TO FIX -@item *.c: include file not found -Correct the status of STDC_HEADERS in @file{scmfig.h} - -fix #include statement or add #define for system type to -@file{scmfig.h}. -@item *.c: Function should return a value in @dots{} -@itemx *.c: Parameter '@dots{}' is never used in @dots{} -@itemx *.c: Condition is always false in @dots{} -@itemx *.c: Unreachable code in function @dots{} -Ignore. -@item scm.c: assignment between incompatible types -change SIGRETTYPE in @file{scm.c}. -@item time.c: CLK_TCK redefined -incompatablility between <stdlib.h> and <sys/types.h>. remove -STDC_HEADERS in @file{scmfig.h}. - -edit <sys/types.h> to remove incompatability. -@item subr.c: Possibly incorrect assignment in function lgcd -Ignore. -@item sys.c: statement not reached -@itemx sys.c: constant in conditional expression -ignore -@item sys.c: `???' undeclared, outside of functions -#undef STDC_HEADERS in @file{scmfig.h}. -@item scl.c: syntax error -#define SYSTNAME to your system type in @file{scl.c} (softtype) -@end table +@multitable @columnfractions .10 .45 .45 +@item FILE +@tab PROBLEM / MESSAGE +@tab HOW TO FIX +@item *.c +@tab include file not found. +@tab Correct the status of @t{STDC_HEADERS} in scmfig.h. +@item +@tab +@tab fix @t{#include} statement or add @t{#define} for system type to scmfig.h. +@item *.c +@tab Function should return a value. +@tab Ignore. +@item +@tab Parameter is never used. +@tab +@item +@tab Condition is always false. +@tab +@item +@tab Unreachable code in function. +@tab +@item scm.c +@tab assignment between incompatible types. +@tab Change @t{SIGRETTYPE} in scm.c. +@item time.c +@tab CLK_TCK redefined. +@tab incompatablility between <stdlib.h> and <sys/types.h>. +@item +@tab +@tab Remove @t{STDC_HEADERS} in scmfig.h. +@item +@tab +@tab Edit <sys/types.h> to remove incompatability. +@item subr.c +@tab Possibly incorrect assignment in function lgcd. +@tab Ignore. +@item sys.c +@tab statement not reached. +@tab Ignore. +@item +@tab constant in conditional expression. +@tab +@item sys.c +@tab undeclared, outside of functions. +@tab @t{#undef STDC_HEADERS} in scmfig.h. +@item scl.c +@tab syntax error. +@tab @t{#define SYSTNAME} to your system type in scl.c (softtype). +@end multitable @node Problems Linking, Problems Running, Problems Compiling, Installing SCM @section Problems Linking -@table @asis +@multitable @columnfractions .5 .5 @item PROBLEM -HOW TO FIX +@tab HOW TO FIX @item _sin etc. missing. -uncomment LIBS in makefile -@end table +@tab Uncomment @t{LIBS} in makefile. +@end multitable @node Problems Running, Testing, Problems Linking, Installing SCM @section Problems Running -@table @asis +@multitable @columnfractions .5 .5 @item PROBLEM -HOW TO FIX +@tab HOW TO FIX @item Opening message and then machine crashes. -Change memory model option to C compiler (or makefile). - -Make sure @code{sizet} definition is correct in @file{scmfig.h}. - -Reduce size of HEAP_SEG_SIZE in @file{setjump.h}. -@item Input hangs -#define NOSETBUF -@item ERROR: heap: need larger initial -Need to increase the initial heap allocation using -a<kb> or -INIT_HEAP_SIZE. -@item ERROR: Could not allocate @dots{} -Check @code{sizet} definition. - -Use 32 bit compiler mode. - -Don't try to run as subproccess -@item remove @dots{} in scmfig.h and recompile scm -@itemx add @dots{} in scmfig.h and recompile scm -Do it and recompile files. -@item ERROR: @file{Init5c3.scm} not found -Assign correct IMPLINIT in makefile or @file{scmfig.h} or define -environment variable @code{SCM_INIT_PATH} to be the full pathname of -@file{Init5c3.scm} (@pxref{Installing SCM}). -@item WARNING: require.scm not found -define environment variable @code{SCHEME_LIBRARY_PATH} to be the full -pathname of the scheme library [SLIB] or change @code{library-vicinity} in -@file{Init5c3.scm} to point to library or remove. @xref{Installation, , , slib, -SLIB}. - -Make sure the value of @code{(library-vicinity)} has a trailing file -separator (like @key{/} or @key{\}). -@end table +@tab Change memory model option to C compiler (or makefile). +@item +@tab Make sure @t{sizet} definition is correct in scmfig.h. +@item +@tab Reduce the size of @t{HEAP_SEG_SIZE} in setjump.h. +@item Input hangs. +@tab @t{#define NOSETBUF} +@item ERROR: heap: need larger initial. +@tab Increase initial heap allocation using -a<kb> or @t{INIT_HEAP_SIZE}. +@item ERROR: Could not allocate. +@tab Check @t{sizet} definition. +@item +@tab Use 32 bit compiler mode. +@item +@tab Don't try to run as subproccess. +@item remove <FLAG> in scmfig.h and recompile scm. +@tab Do so and recompile files. +@item add <FLAG> in scmfig.h and recompile scm. +@tab +@item ERROR: Init@value{SCMVERSION}.scm not found. +@tab Assign correct @t{IMPLINIT} in makefile or scmfig.h. +@item +@tab Define environment variable @t{SCM_INIT_PATH} to be the full pathname of Init@value{SCMVERSION}.scm. +@item WARNING: require.scm not found. +@tab Define environment variable @t{SCHEME_LIBRARY_PATH} to be the full pathname of the scheme library [SLIB]. +@item +@tab Change @t{library-vicinity} in Init@value{SCMVERSION}.scm to point to library or remove. +@item +@tab Make sure the value of @t{(library-vicinity)} has a trailing file separator (like @t{/} or @t{\}). +@end multitable @node Testing, Reporting Problems, Problems Running, Installing SCM @section Testing @@ -1268,33 +1175,35 @@ of SCM running @file{pi.scm}. @samp{make bench} or @samp{make benchlit} appends the performance report to the file @file{BenchLog}, facilitating tracking effects of changes to SCM on performance. -@table @asis +@multitable @columnfractions .5 .5 @item PROBLEM -HOW TO FIX +@tab HOW TO FIX @item Runs some and then machine crashes. -See above under machine crashes. -@item Runs some and then ERROR: @dots{} (after a GC has happened) -Remove optimization option to C compiler and recompile. - -@code{#define SHORT_ALIGN} in @file{scmfig.h}. +@tab See above under machine crashes. +@item Runs some and then ERROR: @dots{} (after a GC has happened). +@tab Remove optimization option to C compiler and recompile. +@item +@tab @t{#define SHORT_ALIGN} in @file{scmfig.h}. @item Some symbol names print incorrectly. -Change memory model option to C compiler (or makefile). - -Check that @code{HEAP_SEG_SIZE} fits within @code{sizet}. - -Increase size of @code{HEAP_SEG_SIZE} (or @code{INIT_HEAP_SIZE} if it is -smaller than @code{HEAP_SEG_SIZE}). +@tab Change memory model option to C compiler (or makefile). +@item +@tab Check that @t{HEAP_SEG_SIZE} fits within @t{sizet}. +@item +@tab Increase size of @t{HEAP_SEG_SIZE} (or @t{INIT_HEAP_SIZE} if it is smaller than @t{HEAP_SEG_SIZE}). @item ERROR: Rogue pointer in Heap. -See above under machine crashes. +@tab See above under machine crashes. @item Newlines don't appear correctly in output files. -Check file mode (define OPEN_@dots{} in @file{Init5c3.scm} -@item Spaces or control characters appear in symbol names -Check character defines in @file{scmfig.h}. +@tab Check file mode (define OPEN_@dots{} in @file{Init@value{SCMVERSION}.scm}). +@item Spaces or control characters appear in symbol names. +@tab Check character defines in @file{scmfig.h}. @item Negative numbers turn positive. -Check SRS in @file{scmfig.h}. -@item VMS: Couldn't unwind stack -@itemx VAX: botched longjmp -@code{#define CHEAP_CONTIUATIONS} in @file{scmfig.h}. +@tab Check SRS in @file{scmfig.h}. +@item VMS: Couldn't unwind stack. +@tab @t{#define CHEAP_CONTIUATIONS} in @file{scmfig.h}. +@item VAX: botched longjmp. +@end multitable + +@table @asis @item Sparc(SUN-4) heap is growing out of control You are experiencing a GC problem peculiar to the Sparc. The problem is that SCM doesn't know how to clear register windows. Every location @@ -1311,7 +1220,7 @@ call-with-current-continuations. @noindent 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 @code{jaffer@@ai.mit.edu}. The bug report +can send a bug report to @code{jaffer @@ ai.mit.edu}. The bug report should include: @enumerate @@ -1346,18 +1255,18 @@ vendor is recommended. * Errors:: * Memoized Expressions:: * Internal State:: -* Shell Scripts:: +* Scripting:: @end menu @node Invoking SCM, SCM Options, Operational Features, Operational Features @section Invoking SCM -@quotation +@example @exdent @b{ scm } [-a @i{kbytes}] [-ibvqmu] [-p @i{number}] @w{[-c @i{expression}]} @w{[-e @i{expression}]} @w{[-f @i{filename}]} @w{[-l @i{filename}]} @w{[-r @i{feature}]} @w{[-- | - | -s]} @w{[@i{filename}]} @w{[@i{arguments} @dots{}]} -@end quotation +@end example @noindent Upon startup @code{scm} loads the file specified by by the environment @@ -1367,9 +1276,10 @@ variable @var{SCM_INIT_PATH}. If @var{SCM_INIT_PATH} is not defined or if the file it names is not present, @code{scm} tries to find the directory containing the executable file. If it is able to locate the executable, @code{scm} -looks for the initialization file (usually @file{Init5c3.scm}) in -platform-dependent directories relative to this directory. -@xref{File-System Habitat} for a blow-by-blow description. +looks for the initialization file (usually +@file{Init@value{SCMVERSION}.scm}) in platform-dependent directories +relative to this directory. See @ref{File-System Habitat} for a +blow-by-blow description. @noindent As a last resort (if initialization file cannot be located), the C @@ -1378,15 +1288,15 @@ compile parameter @var{IMPLINIT} (defined in the makefile or @noindent Unless the option @code{-no-init-file} or @code{--no-init-file} occurs -in the command line, @file{Init5c3.scm} checks to see if there is file -@file{ScmInit.scm} in the path specified by the environment variable -@var{HOME} (or in the current directory if @var{HOME} is undefined). If -it finds such a file it is loaded. +in the command line, @file{Init@value{SCMVERSION}.scm} checks to see if +there is file @file{ScmInit.scm} in the path specified by the +environment variable @var{HOME} (or in the current directory if +@var{HOME} is undefined). If it finds such a file it is loaded. @noindent -@file{Init5c3.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. +@file{Init@value{SCMVERSION}.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. @noindent This explanation applies to SCMLIT or other builds of SCM. @@ -1410,7 +1320,7 @@ distribution sets at @code{25000*sizeof(cell)}. @end deffn @deffn {Command Option} -no-init-file -@deffnx {Command Option} --no-init-file +@deffnx {Command Option} ---no-init-file Inhibits the loading of @file{ScmInit.scm} as described above. @end deffn @@ -1426,7 +1336,7 @@ enclosed in quotes. For instance @samp{"-e(newline)"}. requires @var{feature}. This will load a file from [SLIB] if that @var{feature} is not already supported. If @var{feature} is 2, 3, 4, or 5 @code{scm} will require the features neccessary to support [R2RS], -[R3RS], [R4RS], or proposed [R5RS], respectively. +[R3RS], [R4RS], or [R5RS], respectively. @end deffn @deffn {Command Option} -l filename @@ -1455,16 +1365,16 @@ information. This is the same as @code{-p0}. @deffn {Command Option} -m specifies that subsequent loads, evaluations, and user interactions will -be with [R4RS] macro capability. To use a specific [R4RS] macro -implementation from [SLIB] (instead of [SLIB]'s default) put @code{-r} -@var{macropackage} before @code{-m} on the command line. +be with syntax-rules macro capability. To use a specific syntax-rules +macro implementation from [SLIB] (instead of [SLIB]'s default) put +@code{-r} @var{macropackage} before @code{-m} on the command line. @end deffn @deffn {Command Option} -u specifies that subsequent loads, evaluations, and user interactions will -be without [R4RS] macro capability. [R4RS] macro capability can -be restored by a subsequent @code{-m} on the command line or from Scheme -code. +be without syntax-rules macro capability. syntax-rules macro capability +can be restored by a subsequent @code{-m} on the command line or from +Scheme code. @end deffn @deffn {Command Option} -i @@ -1490,7 +1400,7 @@ treated as program aguments. @end deffn @deffn {Command Option} - -@deffnx {Command Option} -- +@deffnx {Command Option} --- specifies that there are no more options on the command line. @end deffn @@ -1509,11 +1419,11 @@ it is invoked. Otherwise the (new) command line is processed as usual when the saved image is invoked. @end deffn -@deffn {Command Option} --help +@deffn {Command Option} ---help prints usage information and URL; then exit. @end deffn -@deffn {Command Option} --version +@deffn {Command Option} ---version prints version information and exit. @end deffn @@ -1542,8 +1452,8 @@ Loads @code{pretty-print} and @code{format} and enters interactive session. @item % scm -r5 -Loads @code{dynamic-wind}, @code{values}, and [R4RS] macros and enters -interactive (with macros) session. +Loads @code{dynamic-wind}, @code{values}, and syntax-rules macros and +enters interactive (with macros) session. @item % scm -r5 -r4 Like above but @code{rev4-optional-procedures} are also loaded. @@ -1554,7 +1464,8 @@ Like above but @code{rev4-optional-procedures} are also loaded. @defvr {Environment Variable} SCM_INIT_PATH is the pathname where @code{scm} will look for its initialization -code. The default is the file @file{Init5c3.scm} in the source directory. +code. The default is the file @file{Init@value{SCMVERSION}.scm} in the +source directory. @end defvr @defvr {Environment Variable} SCHEME_LIBRARY_PATH @@ -1562,8 +1473,8 @@ is the [SLIB] Scheme library directory. @end defvr @defvr {Environment Variable} HOME -is the directory where @file{Init5c3.scm} will look for the user -initialization file @file{ScmInit.scm}. +is the directory where @file{Init@value{SCMVERSION}.scm} will look for +the user initialization file @file{ScmInit.scm}. @end defvr @defvr {Environment Variable} EDITOR @@ -1580,9 +1491,10 @@ to [SLIB] @code{getopt}. @end defvar @defvar *R4RS-macro* -controls whether loading and interaction support [R4RS] macros. Define -this in @file{ScmInit.scm} or files specified on the command line. This -can be overridden by subsequent @code{-m} and @code{-u} options. +controls whether loading and interaction support syntax-rules +macros. Define this in @file{ScmInit.scm} or files specified on the +command line. This can be overridden by subsequent @code{-m} and +@code{-u} options. @end defvar @defvar *interactive* @@ -1687,6 +1599,7 @@ Typing @samp{(e)} will invoke the editor with the file of interest. After editing, the modified file will be loaded. @end table + @node Debugging Scheme Code, Errors, Editing Scheme Code, Operational Features @section Debugging Scheme Code @@ -1700,7 +1613,7 @@ If SCM is built with the @samp{CAUTIOUS} flag, then when an error occurs, a @dfn{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. @xref{Memoized Expressions} for how to read memoized +builtin. See @ref{Memoized Expressions} for how to read memoized expressions. Also as the result of the @samp{CAUTIOUS} flag, both @code{error} and @@ -1785,8 +1698,8 @@ offers source code debugging from GNU Emacs. PSD runs slowly, so start by instrumenting only a few functions at a time. @lisp -swissnet.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz -prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz +http://swissnet.ai.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz +ftp.gnu.org: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 @end lisp @@ -1812,42 +1725,48 @@ with callback names after them can also be handled by Scheme code level, the default error handler (C code) is invoked. There are many other error messages which are not treated specially. -@enumerate 0 -@item -Wrong type in arg 0 -@item -Wrong type in arg 1 -@item -Wrong type in arg 2 -@item -Wrong type in arg 3 -@item -Wrong type in arg 4 -@item -Wrong type in arg 5 -@item +@table @dfn +@item ARGn +Wrong type in argument +@item ARG1 +Wrong type in argument 1 +@item ARG2 +Wrong type in argument 2 +@item ARG3 +Wrong type in argument 3 +@item ARG4 +Wrong type in argument 4 +@item ARG5 +Wrong type in argument 5 +@item WNA Wrong number of args -@item +@item OVFLOW numerical overflow -@item +@item OUTOFRANGE Argument out of range -@item -Could not allocate @code{(out-of-storage)} -@item -EXIT @code{(end-of-program)} -@item -hang up @code{(hang-up)} -@item -user interrupt @code{(user-interrupt)} -@item -arithmetic error @code{(arithmetic-error)} -@item +@item NALLOC +@code{(out-of-storage)} +@item THRASH +GC is @code{(thrashing)} +@item EXIT +@code{(end-of-program)} +@item HUP_SIGNAL +@code{(hang-up)} +@item INT_SIGNAL +@code{(user-interrupt)} +@item FPE_SIGNAL +@code{(arithmetic-error)} +@item BUS_SIGNAL bus error -@item +@item SEGV_SIGNAL segment violation -@item -alarm @code{(alarm-interrupt)} -@end enumerate +@item ALRM_SIGNAL +@code{(alarm-interrupt)} +@item VTALRM_SIGNAL +@code{(virtual-alarm-interrupt)} +@item PROF_SIGNAL +@code{(profile-alarm-interrupt)} +@end table @defvar errobj When SCM encounters a non-fatal error, it aborts evaluation of the @@ -1884,14 +1803,14 @@ signal warnings and errors. @defun warn arg1 arg2 arg3 @dots{} Alias for @ref{System, slib:warn, , slib, SLIB}. Outputs an error message containing the arguments. @code{warn} is defined in -@file{Init5c3.scm}. +@file{Init@value{SCMVERSION}.scm}. @end defun @defun error arg1 arg2 arg3 @dots{} Alias for @ref{System, slib:error, , slib, SLIB}. Outputs an error message containing the arguments, aborts evaluation of the current form and resumes the top level read-eval-print loop. @code{Error} is defined -in @file{Init5c3.scm}. +in @file{Init@value{SCMVERSION}.scm}. @end defun @noindent @@ -1899,7 +1818,7 @@ If SCM is built with the @samp{CAUTIOUS} flag, then when an error occurs, a @dfn{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. @xref{Memoized Expressions} for how to read memoized +builtin. See @ref{Memoized Expressions} for how to read memoized expressions. @noindent @@ -1912,8 +1831,8 @@ systems. @defun stack-trace Prints information describing the stack of partially evaluated expressions. @code{stack-trace} returns @code{#t} if any lines were -printed and @code{#f} otherwise. See @file{Init5c3.scm} for an example of -the use of @code{stack-trace}. +printed and @code{#f} otherwise. See @file{Init@value{SCMVERSION}.scm} +for an example of the use of @code{stack-trace}. @end defun @node Memoized Expressions, Internal State, Errors, Operational Features @@ -1943,7 +1862,7 @@ top-level have @r{#@@} prepended. @noindent For instance, @code{open-input-file} is defined as follows in -@file{Init5c3.scm}: +@file{Init@value{SCMVERSION}.scm}: @example (define (open-input-file str) @@ -1992,7 +1911,7 @@ open-input-file @result{} @end example -@node Internal State, Shell Scripts, Memoized Expressions, Operational Features +@node Internal State, Scripting, Memoized Expressions, Operational Features @section Internal State @defvar *interactive* @@ -2001,7 +1920,7 @@ interactive, or should quit after the command line is processed. @var{*interactive*} is controlled directly by the command-line options @samp{-b}, @samp{-i}, and @samp{-s} (@pxref{Invoking SCM}). If none of these options are specified, the rules to determine interactivity are -more complicated; see @file{Init5c3.scm} for details. +more complicated; see @file{Init@value{SCMVERSION}.scm} for details. @end defvar @defun abort @@ -2057,7 +1976,7 @@ also gives the hexadecimal heap segment and stack bounds. @end defun @defvr Constant *scm-version* -Contains the version string (e.g. @file{5c3}) of SCM. +Contains the version string (e.g. @file{@value{SCMVERSION}}) of SCM. @end defvr @subsection Executable path @@ -2085,45 +2004,65 @@ For other configuration constants and procedures @xref{Configuration, , , slib, SLIB}. -@node Shell Scripts, , Internal State, Operational Features -@section Shell Scripts +@node Scripting, , Internal State, Operational Features +@section Scripting @menu -* Unix Shell Scripts:: Same old same old -* SCSH scripts:: From Olin Shivers' Scheme Shell -* MS-DOS Compatible Scripts:: Run under both MS-DOS and Unix +* Unix Scheme Scripts:: From Olin Shivers' Scheme Shell +* MS-DOS Compatible Scripts:: Run in MS-DOS and Unix +* Unix Shell Scripts:: Use /bin/sh to run Scheme @end menu -@node Unix Shell Scripts, SCSH scripts, Shell Scripts, Shell Scripts -@subsection Unix Shell Scripts +@node Unix Scheme Scripts, MS-DOS Compatible Scripts, Scripting, Scripting +@subsection Unix Scheme Scripts @noindent In reading this section, keep in mind that the first line of a script file has (different) meanings to SCM and the operating system (@code{execve}). -@deftp file #! interpreter -@deftpx file #! interpreter arg +@deftp file #! interpreter \ @dots{} -@tindex Shell Script -@tindex Shell-Script +@tindex Scheme Script +@tindex Scheme-Script +@tindex meta-argument On unix systems, a @dfn{Shell-Script} is a file (with execute permissions) whose first two characters are @samp{#!}. The @var{interpreter} argument must be the pathname of the program to process the rest of the file. The directories named by environment variable @code{PATH} are @emph{not} searched to find @var{interpreter}. -The @var{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 -@var{interpreter} with (if present) @var{arg}, the pathname of the shell -script file, and then any arguments which the shell-script was invoked -with. +@var{interpreter} with a single argument encapsulating the rest of the +first line's contents (if if not just whitespace), the pathname of the +Scheme Script file, and then any arguments which the shell-script was +invoked with. + +Put one space character between @samp{#!} and the first character of +@var{interpreter} (@samp{/}). The @var{interpreter} name is followed by +@samp{ \}; SCM substitutes the second line of @var{file} for @samp{\} +(and the rest of the line), then appends any arguments given on the +command line invoking this Scheme-Script. + +When SCM executes the script, the Scheme variable @var{*script*} will be +set to the script pathname. The last argument before @samp{!#} on the +second line should be @samp{-}; SCM will load the script file, preserve +the unprocessed arguments, and set @var{*argv*} to a list of the script +pathname and the unprocessed arguments. + +Note that the interpreter, not the operating system, provides the +@samp{\} substitution; this will only take place if @var{interpreter} is +a SCM or SCSH interpreter. @end deftp -@deffn {Read syntax} #! ignored -When the first two characters of the file being loaded are @code{#!}, -the first line of that file will be ignored. +@c @deffn {Read syntax} #! ignored +@c When the first two characters of the file being loaded are @code{#!}, +@c the first line of that file will be ignored. + +@deffn {Read syntax} #! ignored !# +When the first two characters of the file being loaded are @code{#!} and +a @samp{\} is present before a newline in the file, all characters up +to @samp{!#} will be ignored by SCM @code{read}. @end deffn @noindent @@ -2131,167 +2070,82 @@ This combination of interpretatons allows SCM source files to be used as POSIX shell-scripts if the first line is: @example -#!/usr/local/bin/scm -@end example -or -@example -#!/usr/local/bin/scm -l +#!/usr/local/bin/scm \ @end example @noindent -When such a file is invoked, /usr/local/bin/scm is executed with the -name of this file as the first argument. -@example -#!/usr/local/bin/scm -(print (program-arguments)) -(quit) -@result{} ("scm" "./script") -@end example +The following Scheme-Script prints factorial of its argument: @example -#!/usr/local/bin/scm -l -(print (program-arguments)) -@result{} ("scm" "-l" "./script") -@end example +#! /usr/local/bin/scm \ %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 +- !# + ; -*-scheme-*- +(define (go-script) + (cond ((not *script*)) + ((and (= 1 (- (length *argv*) *optind*)) + (string->number (list-ref *argv* *optind*))) + => (lambda (n) (print (fact n)))) + (else + (print *argv*) + (display "\ +Usage: fact n + Returns the factorial of N. + +http://swissnet.ai.mit.edu/~jaffer/SLIB.html +" + (current-error-port)) + (exit #f)))) -@noindent -The following shell-script will print factorial of its argument: -@example -#!/usr/local/bin/scm -l (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(print (fact (string->number (cadddr (program-arguments))))) +(go-script) @end example @example -./fact 6 -@result{} 720 +./fact 32 +@result{} +263130836933693530167218012160000000 @end example @noindent -Shell-scripts suffer from several drawbacks: -@itemize @bullet -@item -Some Unixes limit the length of the @samp{#!} interpreter line to the -size of an object file header, which can be as small as 32 bytes. -@item -A full, explicit pathname must be specified, perhaps requiring more than -32 bytes and making scripts vulnerable to breakage when programs are -moved. -@item -At most one argument is parsed from the first line of the shell-script. -Its position is fixed between the interpreter and any command line -arguments. -@end itemize - -@noindent -The following approach solves these problems at the expense of slower -startup. Make @samp{#!/bin/sh} the first line and prepend every -subsequent line to be executed by the shell with @code{:;} (@code{type;} -in older versions). The last line to be executed by the shell should -contain an @dfn{exec} command; @code{exec} tail-calls its argument. - -@noindent -@code{/bin/sh} is thus invoked with the name of the script file, which -it executes as a *sh script. Usually the second line starts -@samp{:;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. - -@noindent -The second line of the script file does not have the length restriction -mentioned above. Also, @code{/bin/sh} searches the directories listed -in the `PATH' environment variable for @samp{scm}, eliminating the need -to use absolute locations in order to invoke a program. +If the wrong number of arguments is given, @code{fact} prints its +@var{argv} with usage information. @example -#!/bin/sh -:;exec scm -l$0 $* -(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(print (fact (string->number (caddr (program-arguments))))) -@end example - -@example -./fact 6 -@result{} 720 -@end example - -@node SCSH scripts, MS-DOS Compatible Scripts, Unix Shell Scripts, Shell Scripts -@subsection SCSH scripts - -@noindent -Olin Shivers' @dfn{Scheme Shell} project solves the one-argument -limitation by introducing @samp{\} as a @dfn{meta-argument}. This -extensions is also supported by SCM. - -@deftp file #! interpreter \ - -@tindex Shell Script -@tindex shell-script -@tindex meta-argument -This is an enhancement to the shell-script format. When the optional -@var{arg} is @samp{\}, the @var{interpreter} substitutes the second -line of @var{file} for @samp{\}, then appends any arguments given on -the command line invoking this shell-script. -@end deftp - -@deffn {Read syntax} #! ignored !# -When the first two characters of the file being loaded are @code{#!} and -a @samp{\} is present before a newline in the file, all characters up -to @samp{!#} will be ignored by SCM @code{read}. -@end deffn - -@noindent -This combination of interpretatons allows SCM source files to be used as -POSIX shell-scripts if the first line is: - -@example -#!/usr/local/bin/scm \ -@end example - -@noindent -The following shell-script will print its expanded argument list, then -factorial of its argument: - -@example -#!/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*)))) -@end example +./fact 3 2 +@print{} +("./fact" "3" "2") +Usage: fact n + Returns the factorial of N. -@example -./fact 5 -@result{} ("scm" "-p0" "-l" "./fact" "5") -120 +http://swissnet.ai.mit.edu/~jaffer/SLIB.html @end example -@node MS-DOS Compatible Scripts, , SCSH scripts, Shell Scripts +@node MS-DOS Compatible Scripts, Unix Shell Scripts, Unix Scheme Scripts, Scripting @subsection MS-DOS Compatible Scripts @noindent -It turns out that we can create shell-scripts which run both under unix +It turns out that we can create scheme-scripts which run both under unix and MS-DOS. To implement this, I have written the MS-DOS programs: @code{#!.bat} and @code{!#.exe}. -@pindex !# -@pindex !#.exe -@pindex #! -@pindex #!.bat +@cindex !# +@cindex !#.exe +@cindex #! +@cindex #!.bat @noindent With these two programs installed in a @code{PATH} directory, we have the following syntax for @var{<program>.BAT} files. -@deftp file #! interpreter \ %0 %1 %2 %3 %4 %5 %6 %7 %8 +@deftp file #! interpreter \ %0 %1 %2 %3 %4 %5 %6 %7 %8 %9 -@tindex Shell Script -@tindex shell-script -The first two characters of the shell-script are @samp{#!}. The +@tindex Scheme Script +@tindex Scheme-Script +The first two characters of the Scheme-Script are @samp{#!}. The @var{interpreter} can be either a unix style program path (using @samp{/} between filename components) or a DOS program name or path. -The rest of the first line of the shell-script should be literally -@samp{\ %0 %1 %2 %3 %4 %5 %6 %7 %8}, as shown. +The rest of the first line of the Scheme-Script should be literally +@w{@samp{\ %0 %1 %2 %3 %4 %5 %6 %7 %8 %9}}, as shown. If @var{interpreter} has @samp{/} in it, @var{interpreter} is converted to a DOS style filename (@samp{/} @result{} @samp{\}). @@ -2307,22 +2161,85 @@ Once the @var{interpreter} executable path is found, arguments are processed in the manner of scheme-shell, with the all the text after the @samp{\} taken as part of the meta-argument. More precisely, @code{#!} calls @var{interpreter} with any options on the second line of the -shell-script up to @samp{!#}, the name of the shell-script file, and +Scheme-Script up to @samp{!#}, the name of the Scheme-Script file, and then any of at most 8 arguments given on the command line invoking this -shell-script. +Scheme-Script. @end deftp @noindent -The following shell-script will print its expanded argument list, then -factorial of its argument. This shell-script in both MS-DOS and unix +The previous example Scheme-Script works in both MS-DOS and unix systems. + + +@node Unix Shell Scripts, , MS-DOS Compatible Scripts, Scripting +@subsection Unix Shell Scripts + +@noindent +Scheme-scripts suffer from two drawbacks: +@itemize @bullet +@item +Some Unixes limit the length of the @samp{#!} interpreter line to the +size of an object file header, which can be as small as 32 bytes. +@item +A full, explicit pathname must be specified, perhaps requiring more than +32 bytes and making scripts vulnerable to breakage when programs are +moved. +@end itemize + +@noindent +The following approach solves these problems at the expense of slower +startup. Make @samp{#!/bin/sh} the first line and prepend every +subsequent line to be executed by the shell with @code{:;}. The last +line to be executed by the shell should contain an @dfn{exec} command; +@code{exec} tail-calls its argument. + +@noindent +@code{/bin/sh} is thus invoked with the name of the script file, which +it executes as a *sh script. Usually the second line starts +@samp{:;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. + +@noindent +The second line of the script file does not have the length restriction +mentioned above. Also, @code{/bin/sh} searches the directories listed +in the `PATH' environment variable for @samp{scm}, eliminating the need +to use absolute locations in order to invoke a program. + +@noindent +The following example additionally sets @var{*script*} to the script +argument, making it compatible with the scheme code of the previous +example. + @example -#! /usr/local/bin/scm \ %0 %1 %2 %3 %4 %5 %6 %7 %8 - -p1 -l !# -(print (program-arguments)) +#! /bin/sh +:;exec scm -e"(set! *script* \"$0\")" -l$0 $* + +(define (go-script) + (cond ((not *script*)) + ((and (= 1 (- (length *argv*) *optind*)) + (string->number (list-ref *argv* *optind*))) + => (lambda (n) (print (fact n)))) + (else + (print *argv*) + (display "\ +Usage: fact n + Returns the factorial of N. + +http://swissnet.ai.mit.edu/~jaffer/SLIB.html +" + (current-error-port)) + (exit #f)))) + (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(print (fact (string->number (list-ref (program-arguments) *optind*)))) + +(go-script) +@end example + +@example +./fact 6 +@result{} 720 @end example @@ -2330,7 +2247,7 @@ systems. @chapter The Language @menu -* Standards Compliance:: Links to sections in [R4RS] and [SLIB] +* Standards Compliance:: Links to sections in [R5RS] and [SLIB] * Miscellaneous Procedures:: * Time:: Both real time and processor time * Interrupts:: and exceptions @@ -2357,41 +2274,22 @@ Language.} @end ifclear and @ifset html -[R4RS], <A HREF="r4rs_toc.html"> +[R5RS], <A HREF="r5rs_toc.html"> @end ifset -@cite{Revised(4) Report on the Algorithmic Language Scheme}. +@cite{Revised(5) Report on the Algorithmic Language Scheme}. @ifset html </A> @end ifset @ifinfo -@ref{Top, , , r4rs, Revised(4) Report on the Algorithmic Language +@ref{Top, , , r5rs, Revised(5) Report on the Algorithmic Language Scheme}. @end ifinfo All the required features of these specifications are supported. Many of the optional features are supported as well. -@subheading Optionals of [R4RS] Supported by SCM +@subheading Optionals of [R5RS] Supported by SCM @table @asis -@item two clause @code{if}: @code{(if <test> <consequent>)} -@xref{Conditionals, , , r4rs, Revised(4) Scheme}. -@item @code{let*} -@itemx named @code{let} -@xref{Binding constructs, , , r4rs, Revised(4) Scheme}. -@item @code{do} -@xref{Iteration, , , r4rs, Revised(4) Scheme}. -@item All varieties of @code{define} -@xref{Definitions, , , r4rs, Revised(4) Scheme}. -@item @code{list-tail} -@xref{Pairs and lists, , , r4rs, Revised(4) Scheme}. -@item @code{string-copy} -@itemx @code{string-fill!} -@xref{Strings, , , r4rs, Revised(4) Scheme}. -@item @code{make-vector} of two arguments -@itemx @code{vector-fill!} -@xref{Vectors, , , r4rs, Revised(4) Scheme}. -@item @code{apply} of more than 2 arguments -@xref{Control features, , , r4rs, Revised(4) Scheme}. @item @code{-} and @code{/} of more than 2 arguments @itemx @code{exp} @itemx @code{log} @@ -2411,29 +2309,23 @@ Many of the optional features are supported as well. @itemx @code{angle} @itemx @code{exact->inexact} @itemx @code{inexact->exact} -@xref{Numerical operations, , , r4rs, Revised(4) Scheme}. -@item @code{delay} -@itemx @code{force} -@xref{Control features, , , r4rs, Revised(4) Scheme}. +@xref{Numerical operations, , , r5rs, Revised(5) Scheme}. @itemx @code{with-input-from-file} @itemx @code{with-output-to-file} -@xref{Ports, , , r4rs, Revised(4) Scheme}. -@itemx @code{char-ready?} -@xref{Input, , , r4rs, Revised(4) Scheme}. +@xref{Ports, , , r5rs, Revised(5) Scheme}. +@itemx @code{load} @itemx @code{transcript-on} @itemx @code{transcript-off} -@xref{System interface, , , r4rs, Revised(4) Scheme}. +@xref{System interface, , , r5rs, Revised(5) Scheme}. @end table -@subheading Optionals of [R4RS] not Supported by SCM +@subheading Optionals of [R5RS] not Supported by SCM @table @asis @item @code{numerator} @itemx @code{denominator} @itemx @code{rationalize} -@xref{Numerical operations, , , r4rs, Revised(4) Scheme}. -@item [R4RS] appendix Macros -@xref{Macros, , , r4rs, Revised(4) Scheme}. +@xref{Numerical operations, , , r5rs, Revised(5) Scheme}. @end table @subheading [SLIB] Features of SCM and SCMLIT @@ -2450,10 +2342,6 @@ See SLIB file @file{Template.scm}. @xref{Time, , , slib, SLIB}. @item defmacro @xref{Defmacro, , , slib, SLIB}. -@item dynamic-wind -@xref{Dynamic-Wind, , , slib, SLIB}. -@item eval -@xref{System, , , slib, SLIB}. @item getenv @itemx system @xref{System Interface, , , slib, SLIB}. @@ -2517,6 +2405,18 @@ program-vicinity, , slib, SLIB}. Returns the current line number of the file currently being loaded. @end defun +@defun port-filename port +Returns the filename @var{port} was opened with. If @var{port} is +not open to a file the result is unspecified. +@end defun + +@defun port-line port +@defunx port-column port +If @var{port} is a tracked port, return the current line (column) number, +otherwise return @code{#f}. Line numbers begin with 1, the column number is +zero if there are no characters on the current line. +@end defun + @defun eval obj Alias for @ref{System, eval, , slib, SLIB}. @end defun @@ -2529,7 +2429,7 @@ evaluating it. @code{eval-string} does not change @defun load-string str Reads and evaluates all the expressions from @var{str}. As with -@code{load}, the value returned is unspecified. @code{eval-string} does +@code{load}, the value returned is unspecified. @code{load-string} does not change @code{*load-pathname*} or @code{line-number}. @end defun @@ -2627,13 +2527,36 @@ If @var{secs} is 0, any alarm request is canceled. Otherwise an time. ALARM is not supported on all systems. @end defun +@defun milli-alarm millisecs interval +@defunx virtual-alarm millisecs interval +@defunx profile-alarm millisecs interval +@code{milli-alarm} is similar to @code{alarm}, except that the first +argument @var{millisecs}, and the return value are measured in +milliseconds rather than seconds. If the optional argument +@var{interval} is supplied then alarm interrupts will be scheduled every +@var{interval} milliseconds until turned off by a call to +@code{milli-alarm} or @code{alarm}. + +@code{virtual-alarm} and @code{profile-alarm} are similar. +@code{virtual-alarm} decrements process execution time rather than real +time, and causes @code{SIGVTALRM} to be signaled. +@code{profile-alarm} decrements both process execution time and +system execution time on behalf of the process, and causes +@code{SIGPROF} to be signaled. + +@code{milli-alarm}, @code{virtual-alarm}, and @code{profile-alarm} are +supported only on systems providing the @code{setitimer} system call. +@end defun + @deffn {Callback procedure} user-interrupt @dots{} @deffnx {Callback procedure} alarm-interrupt @dots{} +@deffnx {Callback procedure} virtual-alarm-interrupt @dots{} +@deffnx {Callback procedure} profile-alarm-interrupt @dots{} Establishes a response for @code{SIGINT} (control-C interrupt) and -@code{SIGALRM} interrupts. Program execution will resume if the handler -returns. This procedure should @code{(abort)} or some other action -which does not return if it does not want processing to continue after -it returns. +@code{SIGALRM}, @code{SIGVTALRM}, and @code{SIGPROF} interrupts. +Program execution will resume if the handler returns. This procedure +should @code{(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 @code{system} and @code{ed} procedures. @@ -2684,7 +2607,7 @@ Otherwise, returns @code{#f}. @noindent These procedures generalize and extend the standard capabilities in -@ref{Ports, , ,r4rs, Revised(4) Scheme}. +@ref{Ports, , ,r5rs, Revised(5) Scheme}. @defun open-file string modes @defunx try-open-file string modes @@ -2706,11 +2629,18 @@ reading, writing, and both reading and writing respectively. @end defvr @defun _ionbf modestr -Returns a version of modestr which when open-file is called with it as -the second argument will return an unbuffered port. A non-file -input-port must be unbuffered in order for char-ready? to work correctly -on it. The initial value of (current-input-port) is unbuffered if the -platform supports it. +Returns a version of @var{modestr} which when @code{open-file} is called +with it as the second argument will return an unbuffered port. A +non-file input-port must be unbuffered in order for @code{char-ready?} and +@code{wait-for-input} to work correctly on it. The initial value of +@code{(current-input-port)} is unbuffered if the platform supports it. +@end defun + +@defun _tracked modestr +Returns a version of @var{modestr} which when @code{open-file} is called +with it as the second argument will return a tracked port. A tracked +port maintains current line and column numbers, which may be queried +with @code{port_line} and @code{port_column}. @end defun @defun close-port port @@ -2764,7 +2694,8 @@ not to hang. If the @var{port} is at end of file then the value returned by @code{current-input-port}. @findex current-input-port -@emph{Rationale:} @code{Char-ready?} exists to make it possible for a program to +@emph{Rationale:} @code{Char-ready?} exists to make it possible for a +program to @findex char-ready? accept characters from interactive ports without getting stuck waiting for input. Any input editors associated with such ports must ensure @@ -2776,10 +2707,29 @@ interactive port that has no ready characters. @c end rationale @end deffn +@deffn {procedure} wait-for-input x +@deffnx {procedure} wait-for-input x port1 @dots{} +Returns a list those ports @var{port1} @dots{} which are @code{char-ready?}. +@findex char-ready? +If none of @var{port1} @dots{} become @code{char-ready?} within the time +interval of @var{x} seconds, then #f is returned. The +@var{port1} @dots{} arguments may be omitted, in which case they default +to the list of the value returned by @code{current-input-port}. +@findex current-input-port +@end deffn + @defun isatty? port Returns @code{#t} if @var{port} is input or output to a serial non-file device. @end defun +@defun freshline port +Outputs a newline to optional argument @var{port} unless the current +output column number of @var{port} is known to be zero, ie output will +start at the beginning of a new line. @var{port} defaults to +@code{current-output-port}. If @var{port} is not a tracked port +@code{freshline} is equivalent to @code{newline}. +@end defun + @node Soft Ports, Syntax Extensions, Files and Ports, The Language @section Soft Ports @@ -2813,7 +2763,7 @@ procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful operation for them to perform. If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input, -eof-object?, ,r4rs, Revised(4) Scheme}) it indicates that the port has +eof-object?, ,r5rs, Revised(5) Scheme}) it indicates that the port has reached end-of-file. For example: @example @@ -2854,6 +2804,18 @@ internal definitions) is a string, then that string is the @end example @end deffn +@defun comment string1 @dots{} +Appends @var{string1} @dots{} to the strings given as arguments to +previous calls @code{comment}. +@defunx comment +Returns the (appended) strings given as arguments to previous calls +@code{comment} and empties the current string collection. +@end defun + +@deffn {Read syntax} #;text-till-end-of-line +Behaves as @code{(comment "@var{text-till-end-of-line}")}. +@end deffn + @deffn {Read syntax} #. expression Is read as the object resulting from the evaluation of @var{expression}. This substitution occurs even inside quoted structure. @@ -2896,12 +2858,23 @@ ignored by the @code{read}. Nested @code{#|@dots{}|#} can occur inside @noindent A similar read syntax @dfn{#!} (exclamation rather than vertical bar) is -supported for Posix shell-scripts (@pxref{Shell Scripts}). +supported for Posix shell-scripts (@pxref{Scripting}). + +@deffn {Read syntax} #\token +If @var{token} is a sequence of two or more digits, then this syntax is +equivalent to @code{#.(integer->char (string->number token 8))}. + +If @var{token} is @code{C-}, @code{c-}, or @code{^} followed by a +character, then this syntax is read as a control character. If +@var{token} is @code{M-} or @code{m-} followed by a character, then a +meta character is read. @code{c-} and @code{m-} prefixes may be +combined. +@end deffn @defspec defined? symbol Equivalent to @code{#t} if @var{symbol} is a syntactic keyword (such as @code{if}) or a symbol with a value in the top level environment -(@pxref{Variables and regions, , ,r4rs, Revised(4) Scheme}). Otherwise +(@pxref{Variables and regions, , ,r5rs, Revised(5) Scheme}). Otherwise equivalent to @code{#f}. @end defspec @@ -2925,6 +2898,25 @@ value is not changed, and an error is signaled. @code{defconst} is valid only when used at top-level. @end defspec +@defspec set! (variable1 variable2 @dots{}) @r{<expression>} + +The identifiers @var{variable1}, @var{variable2}, @dots{} must be bound +either in some region enclosing the @samp{set!} expression or at top +level. + +@r{<Expression>} is evaluated, and the elements of the resulting list +are stored in the locations to which each corresponding @var{variable} +is bound. The result of the @samp{set!} expression is unspecified. + +@example +(define x 2) +(define y 3) +(+ x y) @result{} 5 +(set! (x y) (list 4 5)) @result{} @emph{unspecified} +(+ x y) @result{} 9 +@end example +@end defspec + @defspec casev key clause1 clause2 @dots{} @code{casev} is an extension of standard Scheme @code{case}: Each @var{clause} of a @code{casev} statement must have as first element a @@ -2989,14 +2981,24 @@ read from. The value returned by this function will be the value of @code{#<unspecified>} in which case the expression will be treated as whitespace. @code{#<unspecified>} is the value returned by the expression @code{(if #f #f)}. +@end deffn -@emph{Note:} When adding new @key{#} syntaxes, have your code save the -previous value of @code{read:sharp} when defining it. Call this saved -value if an invocation's syntax is not recognized. This will allow -@code{#+}, @code{#-}, @code{#!}, and @ref{Uniform Array}s to still be -supported (as they use @code{read:sharp}). +@deffn {Callback procedure} read:sharp-char token +If the sequence @key{#\} followed by a non-standard character name is +encountered by @code{read}, @code{read} will call the value of the +symbol @code{read:sharp-char} with the token (a string of length at +least two) as argument. If the value returned is a character, then that +will be the value of @code{read} for this expression, otherwise an error +will be signaled. @end deffn +@emph{Note:} When adding new @key{#} syntaxes, have your code save the +previous value of @code{read:sharp} or @code{read:sharp-char} when +defining it. Call this saved value if an invocation's syntax is not +recognized. This will allow @code{#+}, @code{#-}, @code{#!}, and +@ref{Uniform Array}s to still be supported (as they use @code{read:sharp}). + + @defun procedure->syntax proc Returns a @dfn{macro} which, when a symbol defined to this value appears as the first symbol in an expression, returns the result of applying @@ -3061,7 +3063,7 @@ Thus a mutable environment can be treated as both a list and local bindings. @end defspec -@defspec @@call-with-current-continuation procedure) +@defspec @@call-with-current-continuation procedure Returns the result of applying @var{procedure} to the current continuation. A @dfn{continuation} is a SCM object of type @code{contin} (@pxref{Continuations}). The procedure @@ -3075,7 +3077,7 @@ procedure)}. SCM provides a synthetic identifier type for efficient implementation of hygienic macros (for example, @code{syntax-rules} @pxref{Macros, , , -r4rs, Revised(4) Scheme}) A synthetic identifier may be inserted in +r5rs, Revised(5) 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 @emph{identifiers}. @@ -3101,11 +3103,16 @@ macro expander. @code{renamed-identifier} returns a distinct object for each call, even if passed identical arguments. @end defun -There is no direct way to access the data internal to a synthetic +There is no direct way to access all of 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. +@defun identifier->symbol id +Returns the symbol obtained by recursively extracting the parent of +@var{id}, which must be an identifier. +@end defun + @subsection Use of synthetic identifiers @code{renamed-identifier} may be used as a replacement for @code{gentemp}: @lisp @@ -3185,6 +3192,25 @@ For example, @end lisp @end defun +@defun @@macroexpand1 expr env +If the @code{car} of @var{expr} denotes a macro in @var{env}, then +if that macro is a primitive, @var{expr} will be returned, if the +macro was defined in Scheme, then a macro expansion will be returned. +If the @code{car} of @var{expr} does not denote a macro, the @code{#f} +is returned. +@end defun + +@defun extended-environment names values env +Returns a new environment object, equivalent to @var{env}, which must +either be an environment object or null, extended by one frame. +@var{names} must be an identifier, or an improper list of identifiers, +usable as a formals list in a @code{lambda} expression. @var{values} +must be a list of objects long enough to provide a binding for each of +the identifiers in @var{names}. If @var{names} is an identifier or an +improper list then @var{vals} may be, respectively, any object or an +improper list of objects. +@end defun + @defspec syntax-quote obj Synthetic identifiers are converted to their parent symbols by @code{quote} and @code{quasiquote} so that literal data in macro definitions will be @@ -3208,6 +3234,20 @@ redefinition, for example: @end lisp @end defspec +@defspec renaming-transformer proc +A low-level ``explicit renaming'' macro facility very similar to that +proposed by W. Clinger [Exrename] is supported. Syntax may be defined +in @code{define-syntax}, @code{let-syntax}, and @code{letrec-syntax} +using @code{renaming-transformer} instead of @code{syntax-rules}. +@var{proc} should evaluate to a procedure accepting three arguments: +@var{expr}, @var{rename}, and @var{compare}. @var{expr} is a +representation of Scheme code to be expanded, as list structure. +@var{rename} is a procedure accepting an identifier and returning an +identifier renamed in the definition environment of the new syntax. +@var{compare} accepts two identifiers and returns true if and only if +both denote the same binding in the usage environment of the new syntax. +@end defspec + @node Packages, The Implementation, The Language, Top @chapter Packages @@ -3225,6 +3265,10 @@ redefinition, for example: * Sockets:: Cruise the Net @end menu +@menu +* Xlib: (Xlibscm). X Window Graphics. +@end menu + @node Compiling And Linking, Dynamic Linking, Packages, Packages @section Compiling And Linking @@ -3251,7 +3295,7 @@ scm -e'(link-named-scm"cute""cube")' (lambda (fp) (for-each (lambda (string) (write-line string fp)) - '("#define IMPLINIT \"/home/jaffer/scm/Init5c3.scm\"" + '("#define IMPLINIT \"/home/jaffer/scm/Init@value{SCMVERSION}.scm\"" "#define COMPILED_INITS init_cube();" "#define BIGNUMS" "#define FLOATS" @@ -3302,7 +3346,7 @@ of the X11 library. @end defun @defun load filename lib1 @dots{} -In addition to the [R4RS] requirement of loading Scheme expressions if +In addition to the [R5RS] requirement of loading Scheme expressions if @var{filename} is a Scheme source file, @code{load} will also dynamically load/link object files (produced by @code{compile-file}, for instance). The object-suffix need not be given to load. For example, @@ -3532,7 +3576,7 @@ The immediate integer closest to negative infinity. @noindent These procedures augment the standard capabilities in @ref{Numerical -operations, , ,r4rs, Revised(4) Scheme}. +operations, , ,r5rs, Revised(5) Scheme}. @defun sinh z @defunx cosh z @@ -3597,18 +3641,24 @@ is not real. @subsection Conventional Arrays @dfn{Arrays} read and write as a @code{#} followed by the @dfn{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. +@cindex array +(number of dimensions) followed by the character #\a or #\A and 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. @example (make-array 'ho 3 3) @result{} -#2((ho ho ho) (ho ho ho) (ho ho ho)) +#2A((ho ho ho) (ho ho ho) (ho ho ho)) +@end example + +The rank may be elided, in which case it is read as one. +@example +'#A(a b c) @equiv{} '#(a b c) @end example Unshared conventional (not uniform) 0-based arrays of rank 1 (dimension) are equivalent to (and can't be distinguished from) vectors. @example -(make-array 'ho 3) @result{} (ho ho ho) +(make-array 'ho 3) @result{} #(ho ho ho) @end example When constructing an array, @var{bound} is either an inclusive range of @@ -3675,10 +3725,10 @@ in which case the returned array will have smaller rank than examples: @example -(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) -(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) -(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} - #2((a 4) (b 5) (c 6)) +(transpose-array '#2A((a b) (c d)) 1 0) @result{} #2A((a c) (b d)) +(transpose-array '#2A((a b) (c d)) 0 0) @result{} #1A(a d) +(transpose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} + #2A((a 4) (b 5) (c 6)) @end example @end defun @@ -3698,11 +3748,11 @@ enclosed array is unspecified. examples: @example -(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{} - #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))> +(enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{} + #<enclosed-array (#1A(a d) #1A(b e) #1A(c f)) (#1A(1 4) #1A(2 5) #1A(3 6))> -(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} - #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))> +(enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} + #<enclosed-array #2A((a 1) (d 4)) #2A((b 2) (e 5)) #2A((c 3) (f 6))> @end example @end defun @@ -3728,6 +3778,7 @@ array, @code{0} is returned. @defun array->list array Returns a list consisting of all the elements, in order, of @var{array}. +In the case of a rank-0 array, returns the single element. @end defun @defun array-copy! source destination @@ -3845,14 +3896,14 @@ according to the table: @example 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 # +#t boolean (bit-vector) #At +#\a char (string) #A\ +integer >0 unsigned integer #Au +integer <0 signed integer #Ae +1.0 float (single precision) #Aif +1/3 double (double precision float) #Aid ++i complex (double precision) #Aic +() conventional vector #A @end example @noindent @@ -3869,16 +3920,16 @@ bit-vectors}. @example (make-uniform-array #t 3) @result{} #*000 @equiv{} -#b(#f #f #f) @result{} #*000 +#At(#f #f #f) @result{} #*000 @equiv{} -#1b(#f #f #f) @result{} #*000 +#1At(#f #f #f) @result{} #*000 @end example @noindent -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 -@code{#} and @code{(}. For example, @code{'#e(3 5 9)} returns a uniform -vector of signed integers. +Other uniform vectors are written in a form similar to that of general +arrays, except that one or more modifying characters are put between +the #\A character and the contents list. For example, @code{'#Ae(3 5 9)} +returns a uniform vector of signed integers. @defun uniform-vector-ref uve index Returns the element at the @var{index} element in @var{uve}. @@ -3911,6 +3962,14 @@ Returns an object that would produce an array of the same type as Returns a uniform array of the type indicated by prototype @var{prot} with elements the same as those of @var{lst}. Elements must be of the appropriate type, no coercions are done. + +In, for example, the case of a rank-2 array, @var{lst} must be a list of +lists, all of the same length. The length of @var{lst} will be the +first dimension of the result array, and the length of each element the +second dimension. + +If @var{rank} is zero, @var{lst}, which need not be a list, is the +single element of the returned array. @end defun @defun uniform-vector-fill! uve fill @@ -3978,8 +4037,8 @@ If an @var{index} is provided for each dimension of @var{array} sets the @var{index1}, @var{index2}, @dots{}'th element of @var{array} to @var{val}. If one more @var{index} is provided, then the last index specifies bit position of the twos-complement representation of an exact -integer array element, setting the bit to 1 if @var{bool} is @code{#t} -and to 0 if @var{bool} is @code{#f} if 0. In this case it is an error +integer array element, setting the bit to 1 if @var{val} is @code{#t} +and to 0 if @var{val} is @code{#f}. In this case it is an error if the array element is not an exact integer or if @var{val} is not boolean. @end defun @@ -3993,7 +4052,7 @@ Bit vectors can be written and read as a sequence of @code{0}s and @code{1}s prefixed by @code{#*}. @example -#b(#f #f #f #t #f #t #f) @result{} #*0001010 +#At(#f #f #f #t #f #t #f) @result{} #*0001010 @end example @noindent @@ -4135,6 +4194,36 @@ Closes @var{dir} and returns @code{#t}. If @var{dir} is already closed,, @code{closedir} returns a @code{#f}. @end defun +@defun directory-for-each proc directory +The @var{list}s must be lists, and @var{proc} must be a procedure taking +one argument. @samp{Directory-For-Each} applies @var{proc} to the +(string) name of each file in @var{directory}. The dynamic order in +which @var{proc} is applied to the elements of the @var{list}s is +unspecified. The value returned by @samp{directory-for-each} is +unspecified. + +@defunx directory-for-each proc directory pred +Applies @var{proc} only to those filenames for which the procedure +@var{pred} returns a non-false value. + +@defunx directory-for-each proc directory match +Applies @var{proc} only to those filenames for which +@code{(filename:match?? @var{match})} would return a non-false value +(@pxref{Filenames, , , slib, SLIB}). + +@example +(require 'directory-for-each) +(directory-for-each print "." "[A-Z]*.scm") +@print{} +"Init.scm" +"Iedline.scm" +"Link.scm" +"Macro.scm" +"Transcen.scm" +"Init@value{SCMVERSION}.scm" +@end example +@end defun + @defun mkdir path mode The @code{mkdir} function creates a new, empty directory whose name is @var{path}. The integer argument @var{mode} specifies the file @@ -4256,7 +4345,7 @@ invariably uppercase. @code{Putenv} is used to set up the environment before calls to @code{execl}, @code{execlp}, @code{execv}, @code{execvp}, @code{system}, -or @code{open-pipe} (@pxref{I/O-Extensions, open-pipe}). +or @code{open-pipe} (@pxref{Posix Extensions, open-pipe}). To access environment variables, use @code{getenv} (@pxref{System Interface, getenv, , slib, SLIB}). @@ -4397,23 +4486,19 @@ whether all of them did. @defun waitpid pid options The @code{waitpid} function suspends execution of the current process -until a child as specified by the @var{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 @var{pid} has -already exited by the time of the call (a so-called @dfn{zombie} -process), the function returns immediately. Any system resources used -by the child are freed. +until a child as specified by the @var{pid} argument has exited, or +until a signal is delivered whose action is to terminate the current +process or to call a signal handling function. If a child as requested +by @var{pid} has already exited by the time of the call (a so-called +@dfn{zombie} process), the function returns immediately. Any system +resources used by the child are freed. -The value of @var{pid} can be one of: +The value of @var{pid} can be: @table @asis @item < -1 which means to wait for any child process whose process group ID is -equal to the absolute value of - -@item -1 -which means to wait for any child process whose process group ID is -equal to the @code{(abs @var{pid})}. +equal to the absolute value of @var{pid}. @item -1 which means to wait for any child process; this is the same behaviour @@ -4633,7 +4718,7 @@ writing is done. The value returned is unspecified. These functions are defined in @file{rgx.c} using a POSIX or GNU @dfn{regex} library. If your computer does not support regex, a package is available via ftp from -@file{prep.ai.mit.edu:/pub/gnu/regex-0.12.tar.gz}. For a description of +@file{ftp.gnu.org:/pub/gnu/regex-0.12.tar.gz}. For a description of regular expressions, @xref{syntax, , , regex, "regex" regular expression matching library}. @@ -4772,9 +4857,9 @@ using the @dfn{editline} or GNU @dfn{readline} (@pxref{Top, , Overview @end ifset @item @ifset html -<A HREF="ftp://prep.ai.mit.edu/pub/gnu/readline-2.0.tar.gz"> +<A HREF="ftp://ftp.gnu.org/pub/gnu/readline-2.0.tar.gz"> @end ifset -@code{prep.ai.mit.edu:/pub/gnu/readline-2.0.tar.gz} +@code{ftp.gnu.org:/pub/gnu/readline-2.0.tar.gz} @ifset html </A> @end ifset @@ -5491,35 +5576,39 @@ sockets for multiple connections without input blocking. (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)))))))))))) + (let ((actives (or (apply wait-for-input 5 listener-socket connections) + '()))) + (cond ((null? actives)) + ((memq listener-socket actives) + (set! actives (cdr (memq listener-socket actives))) + (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 ((memq con actives) + (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))))))))))))) @end example @noindent @@ -5541,16 +5630,43 @@ or you can use a client written in scheme: (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)))) +(define (go) + (define actives (wait-for-input (* 30 60) con (current-input-port))) + (let ((cs (and actives (memq con actives) (read-char con))) + (ct (and actives (memq (current-input-port) actives) (read-char)))) + (cond ((or (eof-object? cs) (eof-object? ct)) (close-port con)) + (else (cond (cs (display cs))) + (cond (ct (file-set-position con 0) + (display ct con) + (file-set-position con 0))) + (go))))) +(cond (con (display "Connecting to ") + (display (getpeername con)) + (newline) + (go)) + (else (display "Server not listening on port 8001") + (newline))) @end example +@iftex +@section Xlibscm + +@ifset html +<A HREF="Xlibscm_toc.html"> +@code{(require 'Xlib)} + +@dfn{Xlibscm} +</A> +is a SCM interface to the +<A HREF="http://www.x.org/"> X Window System.</A> +@end ifset + +@ifclear html +@xref{Top, ,SCM Language X Interface , Xlibscm, Xlibscm}, for the SCM +interface to the @dfn{X Window System}. +@end ifclear +@end iftex + @node The Implementation, Index, Packages, Top @chapter The Implementation @@ -5911,11 +6027,16 @@ uniform vector of double precision inexact complex numbers applicable object produced by call-with-current-continuation @end deftp -@deftp Header tc7_cclo -Subr and environment for compiled closure +@deftp Header tc7_specfun +subr that is treated specially within the evaluator -A cclo is similar to a vector (and is GCed like one), but can be applied -as a function: +@code{apply} and @code{call-with-current-continuation} are denoted by +these objects. Their behavior as functions is built into the evaluator; +they are not directly associated with C functions. This is necessary +in order to make them properly tail recursive. + +tc16_cclo is a subtype of tc7_specfun, a cclo is similar to a vector +(and is GCed like one), but can be applied as a function: @enumerate @item @@ -5930,6 +6051,10 @@ makes a closure from the @emph{subr} @var{proc} with @var{len}-1 extra locations for @code{SCM} data. Elements of a @var{cclo} are referenced using @code{VELTS(cclo)[n]} just as for vectors. @end defun + +@defmac CCLO_LENGTH cclo +Expands to the length of @var{cclo}. +@end defmac @end deftp @node Subr Cells, Ptob Cells, Header Cells, Data Types @@ -6013,7 +6138,8 @@ C function of list of @code{SCM} arguments. @noindent A @dfn{ptob} is a port object, capable of delivering or accepting -characters. @xref{Ports, , , r4rs, Revised(4) Report on the Algorithmic +@tindex ptob +characters. @xref{Ports, , , r5rs, Revised(5) Report on the Algorithmic Language Scheme}. Unlike the types described so far, new varieties of ptobs can be defined dynamically (@pxref{Defining Ptobs}). These are the initial ptobs: @@ -6083,6 +6209,7 @@ open output-port, respectively. @noindent A @dfn{smob} is a miscellaneous datatype. The type code and GCMARK bit +@tindex smob occupy the lower order 16 bits of the @code{CAR} half of the cell. The rest of the @code{CAR} can be used for sub-type or other information. The @code{CDR} contains data of size long and is often a pointer to @@ -6132,10 +6259,36 @@ bigpos and bigneg. The magnitude is stored as a @code{malloc}ed array of type @code{BIGDIG} which must be an unsigned integral type with size smaller than @code{long}. @code{BIGRAD} is the radix associated with @code{BIGDIG}. + +@code{NUMDIGS_MAX} (defined in @file{scmfig.h}) limits the number of +digits of a bignum to 1000. These digits are base @code{BIGRAD}, which +is typically 65536, giving 4816 decimal digits. + +Why only 4800 digits? The simple multiplication algorithm SCM uses is +O(n^2); this means the number of processor instructions required to +perform a multiplication is @emph{some multiple} of the product of the +number of digits of the two multiplicands. + +@example +digits * digits ==> operations + 5 x + 50 100 * x + 500 10000 * x + 5000 1000000 * x +@end example + +To calculate numbers larger than this, FFT multiplication [O(n*log(n))] +and other specialized algorithms are required. You should obtain a +package which specializes in number-theoretical calculations: + +@center @url{ftp://megrez.math.u-bordeaux.fr/pub/pari/} + + + @end deftp @deftp smob tc16_promise -made by DELAY. @xref{Control features, , , r4rs, Revised(4) Scheme}. +made by DELAY. @xref{Control features, , , r5rs, Revised(5) Scheme}. @end deftp @deftp smob tc16_arbiter @@ -6196,7 +6349,18 @@ dvect .........long length....G0101111 ........double *words........... cvect .........long length....G0110101 ........double *words........... contin .........long length....G0111101 .............*regs.............. -cclo .........long length....G0111111 ...........SCM **elts...........} +specfun ................xxxxxxxxG1111111 ...........SCM name............. +cclo ..short length..xxxxxx10G1111111 ...........SCM **elts...........} +@r{ PTOBs:} +@t{ port 0bwroxxxxxxxxG0110111 ..........FILE *stream.......... + socket ttttttt 00001xxxxxxxxG0110111 ..........FILE *stream.......... + inport uuuuuuuuuuU00011xxxxxxxxG0110111 ..........FILE *stream.......... +outport 0000000000000101xxxxxxxxG0110111 ..........FILE *stream.......... + ioport uuuuuuuuuuU00111xxxxxxxxG0110111 ..........FILE *stream.......... +fport 00 00000000G0110111 ..........FILE *stream.......... +pipe 00 00000001G0110111 ..........FILE *stream.......... +strport 00 00000010G0110111 ..........FILE *stream.......... +sfport 00 00000011G0110111 ..........FILE *stream..........} @r{ SUBRs:} @t{ spare 010001x1 spare 010011x1 @@ -6209,17 +6373,8 @@ 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)()........... +lsubr ..........int hpoff.....01110111 ...........SCM (*f)()........... rpsubr ..........int hpoff.....01111101 ...........SCM (*f)()...........} -@r{ PTOBs:} -@t{ 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..........} @r{ SMOBs:} @t{free_cell 000000000000000000000000G1111111 ...........*free_cell........000 @@ -6248,7 +6403,8 @@ array ...short rank..cxxxxxxxxG1111111 ............*array..............} * Defining Subrs:: * Defining Smobs:: * Defining Ptobs:: -* Calling Scheme From C:: +* Allocating memory:: +* Embedding SCM:: In other programs * Callbacks:: * Type Conversions:: For use with C code. * Continuations:: For C and SCM @@ -6393,7 +6549,7 @@ allocate all short-lived objects from the copying-heap, at no extra cost in allocation time. @end quotation - + @subsubheading Implementation Details A separate heap (@code{ecache_v}) is maintained for the copying @@ -6451,6 +6607,7 @@ of literature is available. @node Signals, C Macros, Memory Management for Environments, Operations @subsection Signals +@cindex signals @defun init_signals (in @file{scm.c}) initializes handlers for @code{SIGINT} and @@ -6650,8 +6807,8 @@ will append a symbol @code{'@i{foo}} to the (list) value of put any scheme code which needs to be run as part of your package into @file{I@i{foo}.scm}. @item -put an @code{if} into @file{Init5c3.scm} which loads @file{I@i{foo}.scm} if -your package is included: +put an @code{if} into @file{Init@value{SCMVERSION}.scm} which loads +@file{I@i{foo}.scm} if your package is included: @example (if (defined? twiddle-bits!) @@ -6777,13 +6934,18 @@ typedef struct @{ is a function of one argument of type @code{SCM} (the cell to mark) and returns type @code{SCM} which will then be marked. If no further objects need to be marked then return an immediate object such as -@code{BOOL_F}. 2 functions are provided: +@code{BOOL_F}. The smob cell itself will already have been marked. +@emph{Note:} This is different from SCM versions prior to 5c5. Only +additional data specific to a smob type need be marked by @code{smob.mark}. + + 2 functions are provided: @table @code @item markcdr(ptr) -which marks the current cell and returns @code{CDR(ptr)}. +returns @code{CDR(ptr)}. @item mark0(ptr) -which marks the current cell and returns @code{BOOL_F}. +is a no-op used for smobs containing no additional @code{SCM} data. 0 +may also be used in this case. @end table @item smob.free @@ -6815,8 +6977,10 @@ line goes in an @code{init_} routine. @noindent Promises and macros in @file{eval.c} and arbiters in @file{repl.c} provide examples of SMOBs. There are a maximum of 256 SMOBs. +Smobs that must allocate blocks of memory should use, for example, +@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}. -@node Defining Ptobs, Calling Scheme From C, Defining Smobs, Operations +@node Defining Ptobs, Allocating memory, Defining Smobs, Operations @subsection Defining Ptobs @noindent @@ -6845,49 +7009,201 @@ other C construct as its argument, unlike @code{.free} in a smob, which takes the whole smob cell. Often, @code{.free} and @code{.fclose} can be the same function. See @code{fptob} and @code{pipob} in @file{sys.c} for examples of how to define ptobs. +Ptobs that must allocate blocks of memory should use, for example, +@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}. + +@node Allocating memory, Embedding SCM, Defining Ptobs, Operations +@subsection Allocating memory +SCM maintains a count of bytes allocated using malloc, and calls the +garbage collector when that number exceeds a dynamically managed limit. +In order for this to work properly, @code{malloc} and @code{free} should +not be called directly to manage memory freeable by garbage collection. +The following functions are provided for that purpose: + +@deftypefun SCM must_malloc_cell (long @var{len}, SCM @var{c}, char *@var{what}) +@deftypefunx {char *} must_malloc (long @var{len}, char *@var{what}) +@var{len} is the number of bytes that should be allocated, @var{what} is +a string to be used in error or gc messages. @code{must_malloc} returns +a pointer to newly allocated memory. @code{must_malloc_cell} returns a +newly allocated cell whose @code{car} is @var{c} and whose @code{cdr} is +a pointer to newly allocated memory. +@end deftypefun + +@deftypefun void must_realloc_cell (SCM @var{z}, long @var{olen}, long @var{len}, char *@var{what}) +@deftypefunx {char *} must_realloc (char *@var{where}, long @var{olen}, long @var{len}, char *@var{what}) +@code{must_realloc_cell} takes as argument @var{z} a cell whose +@code{cdr} should be a pointer to a block of memory of length @var{olen} +allocated with @code{must_malloc_cell} and modifies the @code{cdr} to point +to a block of memory of length @var{len}. @code{must_realloc} takes as +argument @var{where} the address of a block of memory of length @var{olen} +allocated by @code{must_malloc} and returns the address of a block of +length @var{len}. + +The contents of the reallocated block will be unchanged up the the +minimum of the old and new sizes. + +@var{what} is a pointer to a string used for error and gc messages. +@end deftypefun + +@code{must_malloc}, @code{must_malloc_cell}, @code{must_realloc}, and +@code{must_realloc_cell} must be called with interrupts deferred +@xref{Signals}. + +@deftypefun void must_free (char *@var{ptr}, sizet @var{len}) +@code{must_free} is used to free a block of memory allocated by the +above functions and pointed to by @var{ptr}. @var{len} is the length of +the block in bytes, but this value is used only for debugging purposes. +If it is difficult or expensive to calculate then zero may be used +instead. +@end deftypefun + -@node Calling Scheme From C, Callbacks, Defining Ptobs, Operations -@subsection Calling Scheme From C + +@node Embedding SCM, Callbacks, Allocating memory, Operations +@subsection Embedding SCM +@cindex Embedding SCM @noindent -To use SCM as a whole from another program call @code{init_scm} or -@code{run_scm} as is done in @code{main()} in @file{scm.c}. +The file @file{scmmain.c} contains the definition of main(). +When SCM is compiled as a library @file{scmmain.c} is not included in +the library; a copy of @file{scmmain.c} can be modified to use SCM as an +embedded library module. + +@deftypefun int main (int @var{argc}, char **@var{argv}) +This is the top level C routine. The value of the @var{argc} argument +is the number of command line arguments. The @var{argv} argument is a +vector of C strings; its elements are the individual command line +argument strings. A null pointer always follows the last element: +@code{@var{argv}[@var{argc}]} is this null pointer. +@end deftypefun + +@deftypevar char *execpath +This string is the pathname of the executable file being run. This +variable can be examined and set from Scheme (@pxref{Internal State}). +@var{execpath} must be set to executable's path in order to use DUMP +(@pxref{Dump}) or DLD. +@end deftypevar @noindent -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: +Rename main() and arrange your code to call it with an @var{argv} which +sets up SCM as you want it. -@enumerate -@item -make a SCM procedure which calls your code's startup routine. -@item -use the @code{#define RTL} flag when compiling @file{scm.c} to elide -SCM's @code{main()}. -@item -In your @code{main()}, call @code{run_scm} with arguments (@code{argc} -and @code{argv}) to invoke your code's startup routine. -@item -link your code with SCM at compile time. -@end enumerate +@noindent +If you need more control than is possible through @var{argv}, here are +descriptions of the functions which main() calls. + +@deftypefun void init_sbrk (void) +Call this before SCM calls malloc(). Value returned from sbrk() is used +to gauge how much storage SCM uses. +@end deftypefun + +@deftypefun {char *} scm_find_execpath (int @var{argc}, char **@var{argv}, char *@var{script_arg}) +@var{argc} and @var{argv} are as described in main(). @var{script_arg} +is the pathname of the SCSH-style script (@pxref{Scripting}) being +invoked; 0 otherwise. @code{scm_find_execpath} returns the pathname of +the executable being run; if @code{scm_find_execpath} cannot determine +the pathname, then it returns 0. +@end deftypefun @noindent -For a dynamically linked single-thread program: +@code{scm_find_implpath} is defined in @file{scmmain.c}. Preceeding +this are definitions of@var{GENERIC_NAME} and @var{INIT_GETENV}. These, +along with @var{IMPLINIT} and @var{dirsep} control scm_find_implpath()'s +operation. -@enumerate -@item -make an @code{init_} procedure for your code which will set up any Scheme -definitions you need and then call your startup routine -(@pxref{Changing Scm}). -@item -Start SCM with command line arguments to dynamically link your code. -After your module is linked, the @code{init_} procedure will be called, and -hence your startup routine. -@end enumerate +@noindent +If your application has an easier way to locate initialization code for +SCM, then you can replace @code{scm_find_implpath}. + +@deftypefun {char *} scm_find_implpath (char *@var{execpath}) +Returns the full pathname of the Scheme initialization file or 0 if it +cannot find it. + +The string value of the preprocessor variable @var{INIT_GETENV} names an +environment variable (default @samp{"SCM_INIT_PATH"}). If this +environment variable is defined, its value will be returned from +@code{scm_find_implpath}. Otherwise find_impl_file() is called with the +arguments @var{execpath}, @var{GENERIC_NAME} (default "scm"), +@var{INIT_FILE_NAME} (default "Init@value{SCMVERSION}_scm"), and the +directory separator string @var{dirsep}. If find_impl_file() returns 0 +and @var{IMPLINIT} is defined, then a copy of the string @var{IMPLINIT} +is returned. +@end deftypefun + +@deftypefun int init_buf0 (FILE *@var{inport}) +Tries to determine whether @var{inport} (usually stdin) is an +interactive input port which should be used in an unbuffered mode. If +so, @var{inport} is set to unbuffered and non-zero is returned. +Otherwise, 0 is returned. + +@code{init_buf0} should be called before any input is read from +@var{inport}. Its value can be used as the last argument to +scm_init_from_argv(). +@end deftypefun + +@deftypefun void scm_init_from_argv (int @var{argc}, char **@var{argv}, char *@var{script_arg}, int @var{iverbose}, int @var{buf0stdin}) +Initializes SCM storage and creates a list of the argument strings +@var{program-arguments} from @var{argv}. @var{argc} and @var{argv} must +already be processed to accomodate Scheme Scripts (if desired). The +scheme variable @var{*script*} is set to the string @var{script_arg}, or +#f if @var{script_arg} is 0. +@var{iverbose} is the initial prolixity level. If @var{buf0stdin} is +non-zero, stdin is treated as an unbuffered port. +@end deftypefun + +@noindent +Call @code{init_signals} and @code{restore_signals} only if you want SCM +to handle interrupts and signals. + +@deftypefun void init_signals (void) +Initializes handlers for @code{SIGINT} and @code{SIGALRM} if they are +supported by the C implementation. All of the signal handlers +immediately reestablish themselves by a call to @code{signal()}. +@end deftypefun + +@deftypefun void restore_signals (void) +Restores the handlers in effect when @code{init_signals} was called. +@end deftypefun + +@deftypefun SCM scm_top_level (char *@var{initpath}, SCM (*toplvl_fun)()) +This is SCM's top-level. Errors longjmp here. @var{toplvl_fun} is a +callback function of zero arguments that is called by +@code{scm_top_level} to do useful work -- if zero, then @code{repl}, +which implements a read-eval-print loop, is called. + +If @var{toplvl_fun} returns, then @code{scm_top_level} will return as +well. If the return value of @var{toplvl_fun} is an immediate integer +then it will be used as the return value of @code{scm_top_level}. In +the main function supplied with SCM, this return value is the exit +status of the process. + +If the first character of string @var{initpath} is @samp{;}, @samp{(} or +whitespace, then scm_ldstr() is called with @var{initpath} to initialize +SCM; otherwise @var{initpath} names a file of Scheme code to be loaded +to initialize SCM. + +When a Scheme error is signaled; control will pass into +@code{scm_top_level} by @code{longjmp}, error messages will be printed +to @code{current-error-port}, and then @var{toplvl_fun} will be called +again. @var{toplvl_fun} must maintain enough state to prevent errors +from being resignalled. If @code{toplvl_fun} can not recover from an +error situation it may simply return. +@end deftypefun + +@deftypefun void final_scm (int @var{freeall}) +Calls all finalization routines registered with add_final(). If +@var{freeall} is non-zero, then all memory which SCM allocated with +malloc() will be freed. +@end deftypefun @noindent -Now use @code{apply} (and perhaps @code{intern}) to call Scheme -procedures from your C code. For example: +You can call indivdual Scheme procedures from C code in the +@var{toplvl_fun} argument passed to scm_top_level(), or from module +subrs (registered by an @code{init_} function, @pxref{Changing Scm}). + +@noindent +Use @code{apply} to call Scheme procedures from your C code. For +example: @example /* If this apply fails, SCM will catch the error */ @@ -6899,8 +7215,61 @@ func = CDR(intern(rpcname,strlen(rpcname))); retval = apply(func, cons(mksproc(srvproc), args), EOL); @end example -@node Callbacks, Type Conversions, Calling Scheme From C, Operations +Functions for loading Scheme files and evaluating Scheme code given +as C strings are described in the next section, (@pxref{Callbacks}). + +Here is a minimal embedding program @file{libtest.c}: + +@example +/* gcc -o libtest libtest.c libscm.a -ldl -lm -lc */ +#include "scm.h" +/* include patchlvl.h for SCM's INIT_FILE_NAME. */ +#include "patchlvl.h" + +void init_user_scm() +@{ + fputs("This is init_user_scm\n", stderr); fflush(stderr); + sysintern("*the-string*", makfrom0str("hello world\n")); +@} + +SCM user_main() +@{ + static int done = 0; + if (done++) return MAKINUM(EXIT_FAILURE); + scm_ldstr("(display *the-string*)"); + return MAKINUM(EXIT_SUCCESS); +@} + +int main(argc, argv) + int argc; + char **argv; +@{ + SCM retval; + char *implpath, *execpath; + + execpath = dld_find_executable(argv[0]); + fprintf(stderr, "dld_find_executable(%s): %s\n", argv[0], execpath); + implpath = find_impl_file(execpath, "scm", INIT_FILE_NAME, dirsep); + fprintf(stderr, "implpath: %s\n", implpath); + scm_init_from_argv(argc, argv, 0, 0); + + retval = scm_top_level(implpath, user_main); + + final_scm(!0); + return (int)INUM(retval); +@} + +@print{} +dld_find_executable(./libtest): /home/jaffer/scm/libtest +implpath: /home/jaffer/scm/Init@value{SCMVERSION}.scm +This is init_user_scm +hello world +@end example + + +@node Callbacks, Type Conversions, Embedding SCM, Operations @subsection Callbacks +@cindex callbacks @noindent SCM now has routines to make calling back to Scheme procedures easier. @@ -6909,7 +7278,7 @@ The source code for these routines are found in @file{rope.c}. @deftypefun int scm_ldfile (char *@var{file}) Loads the Scheme source file @var{file}. Returns 0 if successful, non-0 if not. This function is used to load SCM's initialization file -@file{Init5c3.scm}. +@file{Init@value{SCMVERSION}.scm}. @end deftypefun @deftypefun int scm_ldprog (char *@var{file}) @@ -6984,7 +7353,7 @@ of useful predefined @var{pos} macros, @xref{C Macros}. @emph{Note:} Inexact numbers are accepted only by @code{num2long} and @code{num2ulong} (for when @code{SCM} is compiled without bignums). To convert inexact numbers to exact numbers, @xref{Numerical operations, -inexact->exact, , r4rs, Revised(4) Scheme}. +inexact->exact, , r5rs, Revised(5) Scheme}. @end deftypefun @deftypefun unsigned long scm_addr (SCM @var{args}, char *@var{s_name}) @@ -7013,13 +7382,13 @@ null-terminated string @var{src} or the string @var{src} of length Returns a newly allocated @code{SCM} list of strings corresponding to the @var{argc} length array of null-terminated strings @var{argv}. If @var{argv} is less than @code{0}, @var{argv} is assumed to be -@code{NULL} terminated. @code{makfromstrs} is used by @code{run_scm} to -convert the arguments SCM was called with to a @code{SCM} list which is -the value of SCM procedure calls to @code{program-arguments} -(@pxref{SCM Session, program-arguments}). +@code{NULL} terminated. @code{makfromstrs} is used by +@code{scm_init_from_argv} to convert the arguments SCM was called with +to a @code{SCM} list which is the value of SCM procedure calls to +@code{program-arguments} (@pxref{SCM Session, program-arguments}). @end deftypefun -@deftypefun char **makargvfrmstrs (SCM @var{args}, char *@var{s_name}) +@deftypefun {char **} makargvfrmstrs (SCM @var{args}, char *@var{s_name}) Returns a @code{NULL} terminated list of null-terminated strings copied from the @code{SCM} list of strings @var{args}. The string @var{s_name} is used in messages from error calls by @code{makargvfrmstrs}. @@ -7035,13 +7404,14 @@ Frees the storage allocated to create @var{argv} by a call to @node Continuations, Evaluation, Type Conversions, Operations @subsection Continuations +@cindex continuations @noindent The source files @file{continue.h} and @file{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 @ref{Control features, -call-with-current-continuation, , r4rs, Revised(4) Scheme}. +call-with-current-continuation, , r5rs, Revised(5) Scheme}. @noindent The C constructs @code{jmp_buf}, @code{setjmp}, and @code{longjmp} @@ -7100,7 +7470,7 @@ routine to ensure that @var{start} is actually in the current stack segment. @end deftypefun -@deftypefun CONTINUATION *make_root_continuation (STACKITEM *@var{stack_base}) +@deftypefun {CONTINUATION *} make_root_continuation (STACKITEM *@var{stack_base}) Allocates (@code{malloc}) storage for a @code{CONTINUATION} of the current extent of stack. This newly allocated @code{CONTINUATION} is returned if successful, @code{0} if not. After @@ -7109,7 +7479,7 @@ to @code{setjump(@var{new_continuation}->jmpbuf)} in order to complete the capture of this continuation. @end deftypefun -@deftypefun CONTINUATION *make_continuation (CONTINUATION *@var{parent_cont}) +@deftypefun {CONTINUATION *} make_continuation (CONTINUATION *@var{parent_cont}) Allocates storage for the current @code{CONTINUATION}, copying (or encapsulating) the stack state from @code{@var{parent_cont}->stkbse} to the current top of stack. The newly allocated @code{CONTINUATION} is @@ -7291,7 +7661,7 @@ Programs of the world unite! You have nothing to lose but loss itself. @end quotation @noindent -The function @code{scm_find_impl_file} in @file{scm.c} is an attempt to +The function @code{find_impl_file} in @file{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 @@ -7299,13 +7669,13 @@ for which this information is either not available or unrelated to the locations of support files, then a higher level interface will be needed. -@deftypefun char *scm_find_impl_file(char *@var{exec_path}, char -*@var{generic_name}, char *@var{initname}, char *@var{sep}) Given the -pathname of this executable (@var{exec_path}), test for the existence of -@var{initname} in the implementation-vicinity of this program. Return a -newly allocated string of the path if successful, 0 if not. The -@var{sep} argument is a @emph{null-terminated string} of the character -used to separate directory components. +@deftypefun {char *} find_impl_file (char *@var{exec_path}, char *@var{generic_name}, char *@var{initname}, char *@var{sep}) + +Given the pathname of this executable (@var{exec_path}), test for the +existence of @var{initname} in the implementation-vicinity of this +program. Return a newly allocated string of the path if successful, 0 +if not. The @var{sep} argument is a @emph{null-terminated string} of +the character used to separate directory components. @end deftypefun @itemize @bullet @@ -7353,20 +7723,20 @@ subdirectory. For example, the executable might be @subsection Executable Pathname @noindent -For purposes of finding @file{Init5c3.scm}, dumping an executable, and -dynamic linking, a SCM session needs the pathname of its executable -image. +For purposes of finding @file{Init@value{SCMVERSION}.scm}, dumping an +executable, and dynamic linking, a SCM session needs the pathname of its +executable image. @noindent When a program is executed by MS-DOS, the full pathname of that executable is available in @code{argv[0]}. This value can be passed -directly to @code{scm_find_impl_file} (@pxref{File-System Habitat}). +directly to @code{find_impl_file} (@pxref{File-System Habitat}). @noindent In order to find the habitat for a unix program, we first need to know the full pathname for the associated executable file. -@deftypefun char *dld_find_executable (const char *@var{command}) +@deftypefun {char *} dld_find_executable (const char *@var{command}) @code{dld_find_executable} returns the absolute path name of the file that would be executed if @var{command} were given as a command. It looks up the environment variable @var{PATH}, searches in each of the @@ -7401,19 +7771,19 @@ in any of the directories listed in @code{PATH}. @noindent Source code for these C functions is in the file @file{script.c}. -@ref{Shell Scripts} for a description of script argument processing. +@ref{Scripting} for a description of script argument processing. @noindent @code{script_find_executable} is only defined on unix systems. -@deftypefun char *script_find_executable (const char *@var{name}) +@deftypefun {char *} script_find_executable (const char *@var{name}) @code{script_find_executable} returns the path name of the -executable which will is invoked by the script file @var{name}; +executable which is invoked by the script file @var{name}; @var{name} if it is a binary executable (not a script); or 0 if @var{name} does not exist or is not executable. @end deftypefun -@deftypefun char **script_process_argv(int @var{argc}; char **@var{argv}) +@deftypefun {char **} script_process_argv (int @var{argc}; char **@var{argv}) Given an @dfn{main} style argument vector @var{argv} and the number of arguments, @var{argc}, @code{script_process_argv} returns a newly allocated argument vector in which the second line of the script being @@ -7428,7 +7798,7 @@ is returned. nested script invocations. @end deftypefun -@deftypefun int script_count_argv(char **@var{argv}) +@deftypefun int script_count_argv (char **@var{argv}) Returns the number of argument strings in @var{argv}. @end deftypefun @@ -7450,10 +7820,6 @@ generates more. @code{divide()} could use shifts instead of multiply and divide when scaling. @item -If an open fails because there are no unused file handles, GC should -be done so that file handles which are no longer used can be -collected. -@item Currently, @code{dump}ing an executable does not preserve ports. When loading a @code{dump}ed executable, disk files could be reopened to the same file and position as they had when the executable was dumped. @@ -7464,24 +7830,6 @@ with a frame which calls the contin just created. This in combination with checking stack depth could also be used to allow stacks deeper than 64K on the IBM PC. @item -The @code{must-} or @code{make-} routines need some sort of C macros or -conditionalization so that they check: - -@itemize @bullet -@item -that the @code{LENGTH} field fits into a @code{size_t} (as is checked -now) for platforms with @code{(sizeof(size_t) < sizeof(SCM))}. -@item -that the @code{LENGTH} field fits into 24 (or 56) bits on machines where -@code{size_t} is 32 bits or more. -@end itemize - -This is trickier than it first looks because the must_malloc() routine -is also used for allocating heap segments, which do not have the -@code{LENGTH} field restriction. Putting the 24 bit test into -@code{must_malloc()} should be tested for speed impact. - -@item In the quest for speed, there has been some discussion about a "Forth" style Scheme interpreter. @@ -7781,5 +8129,10 @@ This is an alphabetical list of data types and feature names in SCM. @printindex tp +This is an alphabetical list of concepts introduced in this manual. + +@unnumbered Concept Index +@printindex cp + @contents @bye |