diff options
Diffstat (limited to 'scm.texi')
| -rw-r--r-- | scm.texi | 1367 |
1 files changed, 680 insertions, 687 deletions
@@ -55,7 +55,7 @@ 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} +@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM} Copyright (C) 1990-1999 Free Software Foundation @@ -84,7 +84,7 @@ by the author. @menu * Overview:: -* Installing SCM:: +* Installing SCM:: How to * Operational Features:: * The Language:: Reference. * Packages:: Optional Capabilities. @@ -105,9 +105,9 @@ 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"> +<A HREF="http://swissnet.ai.mit.edu/~jaffer/SCM"> @end ifset -@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html} +@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM} @ifset html </A> @end ifset @@ -174,7 +174,7 @@ timing information printed interactively (the @code{verbose} function). @section Authors @table @b -@item Aubrey Jaffer (jaffer @@ alum.mit.edu) +@item Aubrey Jaffer (agj @@ alum.mit.edu) Most of SCM. @item Radey Shouman Arrays, @code{gsubr}s, compiled closures, records, Ecache, syntax-rules @@ -480,34 +480,34 @@ low priority. SLIB is available from the same sites as SCM: @ifclear html @itemize @bullet @item -swissnet.ai.mit.edu:/pub/scm/slib2d4.tar.gz +swissnet.ai.mit.edu:/pub/scm/slib3a1.tar.gz @item -ftp.gnu.org:/pub/gnu/jacal/slib2d4.tar.gz +ftp.gnu.org:/pub/gnu/jacal/slib3a1.tar.gz @item -ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2d4.tar.gz +ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib3a1.tar.gz @end itemize @end ifclear @ifset html @itemize @bullet @item -<A HREF="http://swissnet.ai.mit.edu/ftpdir/scm/slib2d4.zip"> -http://swissnet.ai.mit.edu/ftpdir/scm/slib2d4.zip +<A HREF="http://swissnet.ai.mit.edu/ftpdir/scm/slib3a1.zip"> +http://swissnet.ai.mit.edu/ftpdir/scm/slib3a1.zip </A> @item -<A HREF="ftp://ftp.gnu.org/pub/gnu/jacal/slib2d4.tar.gz"> -ftp.gnu.org:/pub/gnu/jacal/slib2d4.tar.gz +<A HREF="ftp://ftp.gnu.org/pub/gnu/jacal/slib3a1.tar.gz"> +ftp.gnu.org:/pub/gnu/jacal/slib3a1.tar.gz </A> @item -<A HREF="ftp://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2d4.tar.gz"> -ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2d4.tar.gz +<A HREF="ftp://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib3a1.tar.gz"> +ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib3a1.tar.gz </A> @end itemize @end ifset @noindent -Unpack SLIB (@samp{tar xzf slib2d4.tar.gz} or @samp{unzip -ao -slib2d4.zip}) in an appropriate directory for your system; both +Unpack SLIB (@samp{tar xzf slib3a1.tar.gz} or @samp{unzip -ao +slib3a1.zip}) in an appropriate directory for your system; both @code{tar} and @code{unzip} will create the directory @file{slib}. @noindent @@ -518,7 +518,6 @@ file @file{Init@value{SCMVERSION}.scm} is installed). @example (define (library-vicinity) "/usr/local/lib/slib/") -(load (in-vicinity (library-vicinity) "require")) @end example @noindent @@ -533,7 +532,6 @@ implementation-vicinity, which is absolute: (define library-vicinity (let ((lv (string-append (implementation-vicinity) "../slib/"))) (lambda () lv))) -(load (in-vicinity (library-vicinity) "require")) @end example @noindent @@ -647,6 +645,33 @@ The platforms defined by table @dfn{platform} in @file{build.scm} are: @include platform.txi @end example +@deffn {Build Option} -f @var{pathname} +specifies that the build options contained in @var{pathname} be +spliced into the argument list at this point. The use of option files +can separate functional features from platform-specific ones. + +The @file{Makefile} calls out builds with the options in @samp{.opt} +files: + +@table @file +@item dlls.opt +Options for Makefile targets mydlls, myturtle, and x.so. +@item gdb.opt +Options for udgdbscm and gdbscm. +@item libscm.opt +Options for libscm.a. +@item pg.opt +Options for pgscm, which instruments C functions. +@item udscm4.opt +Options for targets udscm4 and myscm4 (scm). +@item udscm5.opt +Options for targets udscm5 and myscm5 (scm). +@end table + +The Makefile creates options files it depends on only if they do not +already exist. +@end deffn + @deffn {Build Option} -o @var{filename} @deffnx {Build Option} ---outname=@var{filename} specifies that the compilation should produce an executable or object @@ -793,7 +818,7 @@ compile and link your file at compile time, use the @samp{-c} and @samp{-i} options to build: @example -bash$ build -c foo.c -i init_foo +bash$ ./build -c foo.c -i init_foo @print{} #! /bin/sh rm -f scmflags.h @@ -812,7 +837,7 @@ gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \ To make a dynamically loadable object file use the @code{-t dll} option: @example -bash$ build -t dll -c foo.c +bash$ ./build -t dll -c foo.c @print{} #! /bin/sh rm -f scmflags.h @@ -840,7 +865,7 @@ in the BSD family (a.out binary format) can usually be ported to @dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a proposed POSIX standard and may be available on other machines with @dfn{COFF} binary format. For notes about porting to MS-Windows and -finishing the port to VMS @ref{Finishing Dynamic Linking}. +finishing the port to VMS @ref{VMS Dynamic Linking}. @noindent @dfn{DLD} is a library package of C functions that performs @dfn{dynamic @@ -1006,7 +1031,9 @@ macintosh Macintosh (THINK_C and __MWERKS__ define) MCH_AMIGA Aztec_c 5.2a on AMIGA __MACH__ Apple Darwin MSDOS Microsoft C 5.10 and 6.00A +_MSDOS Microsoft CLARM and CLTHUMB compilers. __MSDOS__ Turbo C, Borland C, and DJGPP +__NetBSD__ NetBSD nosve Control Data NOS/VE SVR2 System V Revision 2. __SVR4 SunOS @@ -1021,13 +1048,19 @@ vax11c VAX C compiler VAX11 VAX C compiler _Windows Borland C 3.1 compiling for Windows _WIN32 MS VisualC++ 4.2 and Cygwin (Win32 API) +_WIN32_WCE MS Windows CE vms (and VMS) VAX-11 C under VMS. __alpha DEC Alpha processor __alpha__ DEC Alpha processor hp9000s800 HP RISC processor +__ia64 GCC on IA64 +__ia64__ GCC on IA64 +_LONGLONG GCC on IA64 __i386__ DJGPP i386 DJGPP +_M_ARM Microsoft CLARM compiler defines as 4 for ARM. +_M_ARMT Microsoft CLTHUMB compiler defines as 4 for Thumb. MULTIMAX Encore computer ppc PowerPC __ppc__ PowerPC @@ -1230,7 +1263,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 @@ alum.mit.edu}. The bug report +can send a bug report to @code{agj @@ alum.mit.edu}. The bug report should include: @enumerate @@ -1313,8 +1346,8 @@ on the command line, or from standard input. This explanation applies to SCMLIT or other builds of SCM. @noindent -Scheme-code files can also invoke SCM and its variants. @xref{Syntax -Extensions, #!}. +Scheme-code files can also invoke SCM and its variants. +@xref{Lexical Conventions, #!}. @node SCM Options, Invocation Examples, Invoking SCM, Operational Features @section Options @@ -1345,10 +1378,10 @@ prints version information and exit. @deffn {Command Option} -r feature requires @var{feature}. This will load a file from [SLIB] if that -@var{feature} is not already provided. If @var{feature} is 2, 2rs, -r2rs, 3, 3rs, r3rs, 4, 4rs, r4rs, 5, 5rs, or r5rs; @code{scm} will -require the features neccessary to support [R2RS], [R3RS], [R4RS], or -[R5RS], respectively. +@var{feature} is not already provided. If @var{feature} is 2, 2rs, or +r2rs; 3, 3rs, or r3rs; 4, 4rs, or r4rs; 5, 5rs, or r5rs; @code{scm} +will require the features neccessary to support [R2RS]; [R3RS]; +[R4RS]; or [R5RS], respectively. @end deffn @deffn {Command Option} -h feature @@ -1357,10 +1390,9 @@ provides @var{feature}. @deffn {Command Option} -l filename @deffnx {Command Option} -f filename -loads @var{filename}. @code{Scm} will load the first (unoptioned) file -named on the command line if no @code{-c}, @code{-e}, @code{-f}, -@code{-l}, or @code{-s} option preceeds -it. +loads @var{filename}. @code{Scm} will load the first (unoptioned) +file named on the command line if no @code{-c}, @code{-e}, @code{-f}, +@code{-l}, or @code{-s} option preceeds it. @end deffn @deffn {Command Option} -d filename @@ -1435,13 +1467,14 @@ are errors. @end deffn @deffn {Command Option} -s -specifies, by analogy with @code{sh}, that further options are to be -treated as program aguments. +specifies, by analogy with @code{sh}, that @code{scm} should run +interactively and that further options are to be treated as program +aguments. @end deffn @deffn {Command Option} - @deffnx {Command Option} --- -specifies that there are no more options on the command line. +specifies that further options are to be treated as program aguments. @end deffn @node Invocation Examples, SCM Variables, SCM Options, Operational Features @@ -1556,6 +1589,11 @@ interactive top-level is not entered. Returns a list of strings of the arguments scm was called with. @end defun +@defun getlogin +Returns the (login) name of the user logged in on the controlling +terminal of the process, or #f if this information cannot be determined. +@end defun + @noindent For documentation of the procedures @code{getenv} and @code{system} @xref{System Interface, , , slib, SLIB}. @@ -1583,10 +1621,7 @@ single the single argument @var{filename}. @table @asis @item Gnu Emacs: Editing of Scheme code is supported by emacs. Buffers holding files -ending in .scm are automatically put into scheme-mode. EMACS for MS-DOS -and MS-Windows systems is available (free) from: - -@center @url{http://simtel.coast.net/SimTel/gnu/demacs.html} +ending in .scm are automatically put into scheme-mode. If your Emacs can run a process in a buffer you can use the Emacs command @samp{M-x run-scheme} with SCM. Otherwise, use the emacs @@ -2059,7 +2094,7 @@ variable @code{PATH} are @emph{not} searched to find @var{interpreter}. When executing a shell-script, the operating system invokes @var{interpreter} with a single argument encapsulating the rest of the -first line's contents (if if not just whitespace), the pathname of the +first line's contents (if not just whitespace), the pathname of the Scheme Script file, and then any arguments which the shell-script was invoked with. @@ -2104,25 +2139,25 @@ The following Scheme-Script prints factorial of its argument: @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 +(define (fact.script args) + (cond ((and (= 1 (length args)) + (string->number (car args))) + => (lambda (n) (print (fact n)) #t)) + (else (fact.usage)))) + +(define (fact.usage) + (print *argv*) + (display "\ +Usage: fact N + Returns the factorial of N. " - (current-error-port)) - (exit #f)))) + (current-error-port)) + #f) (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(go-script) + +(if *script* (exit (fact.script (list-tail *argv* *optind*)))) @end example @example @@ -2139,10 +2174,8 @@ If the wrong number of arguments is given, @code{fact} prints its ./fact 3 2 @print{} ("./fact" "3" "2") -Usage: fact n +Usage: fact N Returns the factorial of N. - -http://swissnet.ai.mit.edu/~jaffer/SLIB.html @end example @@ -2152,11 +2185,13 @@ http://swissnet.ai.mit.edu/~jaffer/SLIB.html @noindent 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}. +@code{#!.bat} and @code{!#.exe}, @cindex !# @cindex !#.exe @cindex #! @cindex #!.bat +which are available from: +@url{http://swissnet.ai.mit.edu/ftpdir/scm/sharpbang.zip} @noindent With these two programs installed in a @code{PATH} directory, we have @@ -2183,7 +2218,7 @@ executables, @code{#!} tries all directories named by environment variable @code{PATH}. Once the @var{interpreter} executable path is found, arguments are -processed in the manner of scheme-shell, with the all the text after the +processed in the manner of scheme-shell, with 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 Scheme-Script up to @samp{!#}, the name of the Scheme-Script file, and @@ -2241,25 +2276,24 @@ example. #! /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. +(define (fact.script args) + (cond ((and (= 1 (length args)) + (string->number (car args))) + => (lambda (n) (print (fact n)) #t)) + (else (fact.usage)))) -http://swissnet.ai.mit.edu/~jaffer/SLIB.html +(define (fact.usage) + (print *argv*) + (display "\ +Usage: fact N + Returns the factorial of N. " - (current-error-port)) - (exit #f)))) + (current-error-port)) + #f) (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(go-script) +(if *script* (exit (fact.script (list-tail *argv* *optind*)))) @end example @example @@ -2273,19 +2307,17 @@ http://swissnet.ai.mit.edu/~jaffer/SLIB.html @menu * Standards Compliance:: Links to sections in [R5RS] and [SLIB] -* Miscellaneous Procedures:: +* Storage:: Finalizers, GC-hook, vector-set-length! * Time:: Both real time and processor time * Interrupts:: and exceptions * Process Synchronization:: Because interrupts are preemptive * Files and Ports:: -* Line Numbers:: -* Soft Ports:: Emulate I/O devices -* Syntax Extensions:: -* Low Level Syntactic Hooks:: -* Syntactic Hooks for Hygienic Macros:: +* Eval and Load:: and line-numbers +* Lexical Conventions:: Also called read-syntax +* Syntax:: Macros @end menu -@node Standards Compliance, Miscellaneous Procedures, The Language, The Language +@node Standards Compliance, Storage, The Language, The Language @section Standards Compliance @noindent @@ -2408,59 +2440,9 @@ See SLIB file @file{Template.scm}. @xref{Require, , , slib, SLIB}. @end table -@node Miscellaneous Procedures, Time, Standards Compliance, The Language -@section Miscellaneous Procedures -@defun try-load filename -If the string @var{filename} names an existing file, the try-load -procedure reads Scheme source code expressions and definitions from the -file and evaluates them sequentially and returns @code{#t}. If not, -try-load returns @code{#f}. The try-load procedure does not affect the -values returned by @code{current-input-port} and -@code{current-output-port}. -@end defun - -@defvar *load-pathname* -Is set to the pathname given as argument to @code{load}, -@code{try-load}, and @code{dyn:link} -(@pxref{Compiling And Linking, , , hobbit, Hobbit}). -@code{*load-pathname*} is used to compute the value of -@ref{Vicinity, program-vicinity, , slib, SLIB}. -@end defvar - -@defun line-number -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 and column numbers begin with 1. -The column number applies to the next character to be read; if that -character is a newline, then the column number will be one more than -the length of the line. -@end defun - -@defun eval obj -Alias for @ref{System, eval, , slib, SLIB}. -@end defun - -@defun eval-string str -Returns the result of reading an expression from @var{str} and -evaluating it. @code{eval-string} does not change -@code{*load-pathname*} or @code{line-number}. -@end defun - -@defun load-string str -Reads and evaluates all the expressions from @var{str}. As with -@code{load}, the value returned is unspecified. @code{load-string} does -not change @code{*load-pathname*} or @code{line-number}. -@end defun +@node Storage, Time, Standards Compliance, The Language +@section Storage @defun vector-set-length! object length Change the length of string, vector, bit-vector, or uniform-array @@ -2479,25 +2461,50 @@ depend on this feature; @code{copy-tree} could get redefined. @end defun @defun acons obj1 obj2 obj3 -Returns (cons (cons obj1 obj2) obj3). The expression (set! a-list -(acons key datum a-list)) adds a new association to a-list. -@end defun +Returns (cons (cons obj1 obj2) obj3). -@defun terms -This command displays the GNU General Public License. -@end defun +@lisp +(set! a-list (acons key datum a-list)) +@end lisp -@defun list-file filename -Displays the text contents of @var{filename}. +Adds a new association to a-list. @end defun -@deffn Procedure print arg1 @dots{} -@code{Print} writes all its arguments, separated by spaces. -@code{Print} outputs a @code{newline} at the end and returns the value -of the last argument. +@deffn {Callback procedure} gc-hook @dots{} +Allows a Scheme procedure to be run shortly after each garbage collection. +This procedure will not be run recursively. If it runs long enough +to cause a garbage collection before returning a warning will be +printed. + +To remove the gc-hook, @code{(set! gc-hook #f)}. @end deffn -@node Time, Interrupts, Miscellaneous Procedures, The Language +@defun add-finalizer object finalizer +@var{object} may be any garbage collected object, that is, any object +other than an immediate integer, character, or special token such +as @code{#f} or @code{#t}, @xref{Immediates}. @var{finalizer} is +a thunk, or procedure taking no arguments. + +@var{finalizer} will be invoked asynchronously exactly once some time +after @var{object} becomes eligible for garbage collection. A reference +to @var{object} in the environment of @var{finalizer} will not prevent +finalization, but will delay the reclamation of @var{object} at least +until the next garbage collection. A reference to @var{object} in some +other object's finalizer will necessarily prevent finalization until both +objects are eligible for garbage collection. + +Finalizers are not run in any predictable order. All finalizers will be +run by the time the program ends. + +This facility was based on the paper by Simon Peyton Jones, et al, +``Stretching the storage manager: weak pointers and stable names in +Haskell'', Proc. 11th International Workshop on the Implementation of +Functional Languages, The Netherlands, September 7-10 1999, +Springer-Verlag LNCS. +@end defun + + +@node Time, Interrupts, Storage, The Language @section Time @defvr Constant internal-time-units-per-second @@ -2610,37 +2617,6 @@ To unestablish a response for an error set the handler symbol to @code{#f}. For instance, @code{(set! could-not-open #f)}. @end deffn -@deffn {Callback procedure} gc-hook @dots{} -Allows a Scheme procedure to be run shortly after each garbage collection. -This procedure will not be run recursively. If it runs long enough -to cause a garbage collection before returning a warning will be -printed. -@end deffn - -@defun add-finalizer object finalizer -@var{object} may be any garbage collected object, that is, any object -other than an immediate integer, character, or special token such -as @code{#f} or @code{#t}, @xref{Immediates}. @var{finalizer} is -a thunk, or procedure taking no arguments. - -@var{finalizer} will be invoked asynchronously exactly once some time -after @var{object} becomes eligible for garbage collection. A reference -to @var{object} in the environment of @var{finalizer} will not prevent -finalization, but will delay the reclamation of @var{object} at least -until the next garbage collection. A reference to @var{object} in some -other object's finalizer will necessarily prevent finalization until both -objects are eligible for garbage collection. - -Finalizers are not run in any predictable order. All finalizers will be -run by the time the program ends. - -This facility was based on the paper by Simon Peyton Jones, et al, -``Stretching the storage manager: weak pointers and stable names in -Haskell'', Proc. 11th International Workshop on the Implementation of -Functional Languages, The Netherlands, September 7-10 1999, -Springer-Verlag LNCS. - -@end defun @node Process Synchronization, Files and Ports, Interrupts, The Language @section Process Synchronization @@ -2699,13 +2675,26 @@ Returns @code{#t} and unlocks @var{arbiter} if @var{arbiter} was locked. Otherwise, returns @code{#f}. @end defun -@node Files and Ports, Line Numbers, Process Synchronization, The Language + + +@node Files and Ports, Eval and Load, Process Synchronization, The Language @section Files and Ports @noindent These procedures generalize and extend the standard capabilities in @ref{Ports, , ,r5rs, Revised(5) Scheme}. + +@menu +* Opening and Closing:: +* Port Properties:: +* Port Redirection:: +* Soft Ports:: +@end menu + +@node Opening and Closing, Port Properties, Files and Ports, Files and Ports +@subsection Opening and Closing + @defun open-file string modes @defunx try-open-file string modes Returns a port capable of receiving or delivering characters as @@ -2752,6 +2741,22 @@ does not already exist. This functionality is provided by calling for all platforms. @end defun +@defun open-ports +Returns a list of all currently open ports, excluding string ports, +see @xref{String Ports, , , slib, SLIB}. This may be useful after +a fork @xref{Posix Extensions}, or for debugging. Bear in mind that +ports that would be closed by gc will be kept open by a reference to +this list. +@end defun + +@defun close-port port +Closes @var{port}. The same as close-input-port and close-output-port. +@end defun + + +@node Port Properties, Port Redirection, Opening and Closing, Files and Ports +@subsection Port Properties + @defun port-closed? port Returns #t if @var{port} is closed. @end defun @@ -2761,38 +2766,31 @@ If @var{obj} is not a port returns false, otherwise returns a symbol describing the port type, for example string or pipe. @end defun -@defun close-port port -Closes @var{port}. The same as close-input-port and close-output-port. -@end defun - -@defun current-error-port -Returns the current port to which diagnostic output is directed. +@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 with-error-to-file string thunk -@var{thunk} must be a procedure of no arguments, and string must be a -string naming a file. The file is opened for output, an output port -connected to it is made the default value returned by -current-error-port, and the @var{thunk} is called with no arguments. When -the thunk returns, the port is closed and the previous default is -restored. With-error-to-file returns the value yielded by @var{thunk}. +@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 and column numbers begin with 1. +The column number applies to the next character to be read; if that +character is a newline, then the column number will be one more than +the length of the line. @end defun -@defun with-input-from-port port thunk -@defunx with-output-to-port port thunk -@defunx with-error-to-port port thunk -These routines differ from with-input-from-file, with-output-to-file, -and with-error-to-file in that the first argument is a port, rather -than a string naming a file. +@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 -@defun call-with-outputs thunk proc -Calls the @var{thunk} procedure while the current-output-port and -current-error-port are directed to string-ports. If @var{thunk} -returns, the @var{proc} procedure is called with the output-string, the -error-string, and the value returned by @var{thunk}. If @var{thunk} -does not return a value (perhaps because of error), @var{proc} is called -with just the output-string and the error-string as arguments. +@defun isatty? port +Returns @code{#t} if @var{port} is input or output to a serial non-file +device. @end defun @deffn {procedure} char-ready? @@ -2836,31 +2834,145 @@ 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. + +@node Port Redirection, Soft Ports, Port Properties, Files and Ports +@subsection Port Redirection + +@defun current-error-port +Returns the current port to which diagnostic output is directed. @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}. +@defun with-error-to-file string thunk +@var{thunk} must be a procedure of no arguments, and string must be a +string naming a file. The file is opened for output, an output port +connected to it is made the default value returned by +current-error-port, and the @var{thunk} is called with no arguments. When +the thunk returns, the port is closed and the previous default is +restored. With-error-to-file returns the value yielded by @var{thunk}. @end defun -@defun open-ports -Returns a list of all currently open ports, excluding string ports, -see @xref{String Ports, , , slib, SLIB}. This may be useful after -a fork @xref{Posix Extensions}, or for debugging. Bear in mind that -ports that would be closed by gc will be kept open by a reference to -this list. +@defun with-input-from-port port thunk +@defunx with-output-to-port port thunk +@defunx with-error-to-port port thunk +These routines differ from with-input-from-file, with-output-to-file, +and with-error-to-file in that the first argument is a port, rather +than a string naming a file. @end defun +@defun call-with-outputs thunk proc +Calls the @var{thunk} procedure while the current-output-port and +current-error-port are directed to string-ports. If @var{thunk} +returns, the @var{proc} procedure is called with the output-string, the +error-string, and the value returned by @var{thunk}. If @var{thunk} +does not return a value (perhaps because of error), @var{proc} is called +with just the output-string and the error-string as arguments. +@end defun + + +@node Soft Ports, , Port Redirection, Files and Ports +@subsection Soft Ports + +@noindent +A @dfn{soft-port} is a port based on a vector of procedures capable of +accepting or delivering characters. It allows emulation of I/O ports. + +@defun make-soft-port vector modes +Returns a port capable of receiving or delivering characters as +specified by the @var{modes} string (@pxref{Files and Ports, +open-file}). @var{vector} must be a vector of length 6. Its components +are as follows: + +@enumerate 0 +@item +procedure accepting one character for output +@item +procedure accepting a string for output +@item +thunk for flushing output +@item +thunk for getting one character +@item +thunk for closing port (not by garbage collection) +@end enumerate -@node Line Numbers, Soft Ports, Files and Ports, The Language -@section Line Numbers +For an output-only port only elements 0, 1, 2, and 4 need be +procedures. For an input-only port only elements 3 and 4 need be +procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful +operation for them to perform. -Scheme code define by load may optionally contain line number +If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input, +eof-object?, ,r5rs, Revised(5) Scheme}) it indicates that the port has +reached end-of-file. For example: + +If it is necessary to explicitly close the port when it is garbage +collected, (@pxref{Interrupts, add-finalizer}). + +@example +(define stdout (current-output-port)) +(define p (make-soft-port + (vector + (lambda (c) (write c stdout)) + (lambda (s) (display s stdout)) + (lambda () (display "." stdout)) + (lambda () (char-upcase (read-char))) + (lambda () (display "@@" stdout))) + "rw")) + +(write p p) @result{} #<input-output-soft#\space45d10#\> +@end example +@end defun + + + +@node Eval and Load, Lexical Conventions, Files and Ports, The Language +@section Eval and Load + +@defun try-load filename +If the string @var{filename} names an existing file, the try-load +procedure reads Scheme source code expressions and definitions from the +file and evaluates them sequentially and returns @code{#t}. If not, +try-load returns @code{#f}. The try-load procedure does not affect the +values returned by @code{current-input-port} and +@code{current-output-port}. +@end defun + +@defvar *load-pathname* +Is set to the pathname given as argument to @code{load}, +@code{try-load}, and @code{dyn:link} +(@pxref{Compiling And Linking, , , hobbit, Hobbit}). +@code{*load-pathname*} is used to compute the value of +@ref{Vicinity, program-vicinity, , slib, SLIB}. +@end defvar + +@defun eval obj +Alias for @ref{System, eval, , slib, SLIB}. +@end defun + +@defun eval-string str +Returns the result of reading an expression from @var{str} and +evaluating it. @code{eval-string} does not change +@code{*load-pathname*} or @code{line-number}. +@end defun + +@defun load-string str +Reads and evaluates all the expressions from @var{str}. As with +@code{load}, the value returned is unspecified. @code{load-string} does +not change @code{*load-pathname*} or @code{line-number}. +@end defun + +@defun line-number +Returns the current line number of the file currently being loaded. +@end defun + + +@menu +* Line Numbers:: +@end menu + +@node Line Numbers, , Eval and Load, Eval and Load +@subsection Line Numbers + +Scheme code defined by load may optionally contain line number information. Currently this information is used only for reporting expansion time errors, but in the future run-time error messages may also include line number information. @@ -2881,10 +2993,18 @@ equivalent to the vector. The meaning of s-expressions with line-numbers in other positions is undefined. @defun read-numbered port -Behaves like @code{read}, except that every s-expression read will be +Behaves like @code{read}, except that + +@itemize bullet +@item +Load (read) sytnaxes are enabled. +@item +every s-expression read will be replaced with a cons of a line-number object and the sexp actually read. This replacement is done only if @var{port} is a tracked port See @xref{Files and Ports}. +@end itemize + @end defun @defun integer->line-number int @@ -2900,6 +3020,10 @@ Returns the value of line-number object @var{linum} as an integer. Returns true if and only if @var{obj} is a line-number object. @end defun +@defun read-for-load port +Behaves like @code{read}, except that load syntaxes are enabled. +@end defun + @defvar *load-reader* @defvarx *slib-load-reader* The value of @code{*load-reader*} should be a value acceptable as @@ -2913,61 +3037,102 @@ In order to disable all line-numbering, it is sufficient to set! @end defvar -@node Soft Ports, Syntax Extensions, Line Numbers, The Language -@section Soft Ports +@node Lexical Conventions, Syntax, Eval and Load, The Language +@section Lexical Conventions -@noindent -A @dfn{soft-port} is a port based on a vector of procedures capable of -accepting or delivering characters. It allows emulation of I/O ports. -@defun make-soft-port vector modes -Returns a port capable of receiving or delivering characters as -specified by the @var{modes} string (@pxref{Files and Ports, -open-file}). @var{vector} must be a vector of length 6. Its components -are as follows: +@menu +* Common-Lisp Read Syntax:: +* Load Syntax:: +* Documentation and Comments:: +* Modifying Read Syntax:: +@end menu -@enumerate 0 -@item -procedure accepting one character for output -@item -procedure accepting a string for output -@item -thunk for flushing output -@item -thunk for getting one character -@item -thunk for closing port (not by garbage collection) -@end enumerate +@node Common-Lisp Read Syntax, Load Syntax, Lexical Conventions, Lexical Conventions +@subsection Common-Lisp Read Syntax -For an output-only port only elements 0, 1, 2, and 4 need be -procedures. For an input-only port only elements 3 and 4 need be -procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful -operation for them to perform. +@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 thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input, -eof-object?, ,r5rs, Revised(5) Scheme}) it indicates that the port has -reached end-of-file. For example: +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 -If it is necessary to explicitly close the port when it is garbage -collected, (@pxref{Interrupts, add-finalizer}). +@deffn {Read syntax} #+ feature form +If feature is @code{provided?} (by @code{*features*}) then @var{form} is +read as a scheme expression. If not, then @var{form} is treated as +whitespace. -@example -(define stdout (current-output-port)) -(define p (make-soft-port - (vector - (lambda (c) (write c stdout)) - (lambda (s) (display s stdout)) - (lambda () (display "." stdout)) - (lambda () (char-upcase (read-char))) - (lambda () (display "@@" stdout))) - "rw")) +Feature is a boolean expression composed of symbols and @code{and}, +@code{or}, and @code{not} of boolean expressions. -(write p p) @result{} #<input-output-soft#\space45d10#\> +For more information on @code{provided?} and @code{*features*}, +@xref{Require, , , slib, SLIB}. +@end deffn + +@deffn {Read syntax} #- feature form +is equivalent to @code{#+(not feature) expression}. +@end deffn + +@deffn {Read syntax} #| any thing |# +Is a balanced comment. Everything up to the matching @code{|#} is +ignored by the @code{read}. Nested @code{#|@dots{}|#} can occur inside +@var{any thing}. +@end deffn + +@noindent +@dfn{Load sytax} is Read syntax enabled for @code{read} only when that +@code{read} is part of loading a file or string. This distinction was +made so that reading from a datafile would not be able to corrupt a +scheme program using @samp{#.}. + +@deffn {Load syntax} #. expression +Is read as the object resulting from the evaluation of @var{expression}. +This substitution occurs even inside quoted structure. + +In order to allow compiled code to work with @code{#.} it is good +practice to define those symbols used inside of @var{expression} with +@code{#.(define @dots{})}. For example: + +@example +#.(define foo 9) @result{} #<unspecified> +'(#.foo #.(+ foo foo)) @result{} (9 18) @end example -@end defun +@end deffn + +@deffn {Load syntax} #' form +is equivalent to @var{form} (for compatibility with common-lisp). +@end deffn + + +@node Load Syntax, Documentation and Comments, Common-Lisp Read Syntax, Lexical Conventions +@subsection Load Syntax + +@noindent +@dfn{#!} is the unix mechanism for executing scripts. +See @ref{Unix Scheme Scripts} for the full description of how this +comment supports scripting. -@node Syntax Extensions, Low Level Syntactic Hooks, Soft Ports, The Language -@section Syntax Extensions +@deffn {Load syntax} #?line +@deffnx {Load syntax} #?column +Return integers for the current line and column being read during a +load. +@end deffn + +@deffn {Load syntax} #?file +Returns the string naming the file currently being loaded. This path +is the string passed to @code{load}, possibly with @samp{.scm} +appended. +@end deffn + + + +@node Documentation and Comments, Modifying Read Syntax, Load Syntax, Lexical Conventions +@subsection Documentation and Comments @deffn {procedure} procedure-documentation proc Returns the documentation string of @var{proc} if it exists, or @@ -2992,69 +3157,91 @@ internal definitions) is a string, then that string is the @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 +@deffn {Load 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. -In order to allow compiled code to work with @code{#.} it is good -practice to define those symbols used inside of @var{expression} with -@code{#.(define @dots{})}. For example: -@example -#.(define foo 9) @result{} #<unspecified> -'(#.foo #.(+ foo foo)) @result{} (9 18) -@end example -@end deffn +@node Modifying Read Syntax, , Documentation and Comments, Lexical Conventions +@subsection Modifying Read Syntax -@deffn {Read syntax} #+ feature form -If feature is @code{provided?} (by @code{*features*}) then @var{form} is -read as a scheme expression. If not, then @var{form} is treated as -whitespace. - -Feature is a boolean expression composed of symbols and @code{and}, -@code{or}, and @code{not} of boolean expressions. +@deffn {Callback procedure} read:sharp c port +If a @key{#} followed by a character (for a non-standard syntax) is +encountered by @code{read}, @code{read} will call the value of the +symbol @code{read:sharp} with arguments the character and the port being +read from. The value returned by this function will be the value of +@code{read} for this expression unless the function returns +@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)}. -For more information on @code{provided?} and @code{*features*}, -@xref{Require, , , slib, SLIB}. +@deffnx {Callback procedure} load:sharp c port +Dispatches like @code{read:sharp}, but only during @code{load}s. The +read-syntaxes handled by @code{load:sharp} are a superset of those +handled by @code{read:sharp}. @code{load:sharp} calls +@code{read:sharp} if none of its syntaxes match @var{c}. @end deffn -@deffn {Read syntax} #- feature form -is equivalent to @code{#+(not feature) expression}. +@deffn {Callback procedure} char:sharp 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{char:sharp} 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 -@deffn {Read syntax} #' form -is equivalent to @var{form} (for compatibility with common-lisp). -@end deffn +@emph{Note:} When adding new @key{#} syntaxes, have your code save the +previous value of @code{load:sharp}, @code{read:sharp}, or +@code{char:sharp} when defining it. Call this saved value if an +invocation's syntax is not recognized. This will allow @code{#+}, +@code{#-}, and @ref{Uniform Array}s to still be supported (as they +dispatch from @code{read:sharp}). -@deffn {Read syntax} #| any thing |# -Is a balanced comment. Everything up to the matching @code{|#} is -ignored by the @code{read}. Nested @code{#|@dots{}|#} can occur inside -@var{any thing}. -@end deffn -@noindent -A similar read syntax @dfn{#!} (exclamation rather than vertical bar) is -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))}. +@node Syntax, , Lexical Conventions, The Language +@section Syntax -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 +SCM provides a native implementation of @dfn{defmacro}. +@xref{Defmacro, , , slib, SLIB}. + +When built with @samp{-F macro} build option (@pxref{Build Options}) and +@samp{*syntax-rules*} is non-false, SCM also supports [R5RS] +@code{syntax-rules} macros. @xref{Macros, , ,r5rs, Revised(5) Scheme}. + +Other Scheme Syntax Extension Packages from SLIB can be employed through +the use of @samp{macro:eval} and @samp{macro:load}; Or by using the SLIB +read-eval-print-loop: + +@example +(require 'repl) +(repl:top-level macro:eval) +@end example + +With the appropriate catalog entries +(@pxref{Library Catalogs, , , slib, SLIB}), files using macro +packages will automatically use the correct macro loader when +@samp{require}d. + +@menu +* Define and Set:: +* Defmacro:: +* Syntax-Rules:: +* Macro Primitives:: +* Environment Frames:: +* Syntactic Hooks for Hygienic Macros:: +@end menu + +@node Define and Set, Defmacro, Syntax, Syntax +@subsection Define and Set @defspec defined? symbol Equivalent to @code{#t} if @var{symbol} is a syntactic keyword (such as @@ -3069,7 +3256,7 @@ If @var{identifier} is unbound in the top level environment, then @var{initial-value} as if the @code{defvar} form were instead the form @code{(define identifier initial-value)} . If @var{identifier} already has a value, then @var{initial-value} is @emph{not} evaluated and -@var{identifier}'s value is not changed. @code{defconst} is valid only +@var{identifier}'s value is not changed. @code{defvar} is valid only when used at top-level. @end defspec @@ -3145,15 +3332,19 @@ expansion. @code{defconst} constants should be defined before use. (else 'consonant)) ==> consonant } @end format - @end defspec + + +@node Defmacro, Syntax-Rules, Define and Set, Syntax +@subsection Defmacro + @noindent @findex defmacro @findex macroexpand @findex macroexpand-1 @findex gentemp -SCM also supports the following constructs from Common Lisp: +SCM supports the following constructs from Common Lisp: @code{defmacro}, @code{macroexpand}, @code{macroexpand-1}, and @code{gentemp}. @xref{Defmacro, , , slib, SLIB}. @@ -3187,6 +3378,10 @@ For example: (let1 not legal syntax) @error{} not "does not match" ((name value)) @end lisp + +@node Syntax-Rules, Macro Primitives, Defmacro, Syntax +@subsection Syntax-Rules + @findex syntax-rules SCM supports [R5RS] @code{syntax-rules} macros @xref{Macros, , ,r5rs, Revised(5) Scheme}. @@ -3241,34 +3436,9 @@ For example: (set! eight 9) @result{} ERROR @end lisp -@node Low Level Syntactic Hooks, Syntactic Hooks for Hygienic Macros, Syntax Extensions, The Language -@section Low Level Syntactic Hooks - -@deffn {Callback procedure} read:sharp c port -If a @key{#} followed by a character (for a non-standard syntax) is -encountered by @code{read}, @code{read} will call the value of the -symbol @code{read:sharp} with arguments the character and the port being -read from. The value returned by this function will be the value of -@code{read} for this expression unless the function returns -@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 - -@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}). +@node Macro Primitives, Environment Frames, Syntax-Rules, Syntax +@subsection Macro Primitives @defun procedure->syntax proc Returns a @dfn{macro} which, when a symbol defined to this value appears @@ -3310,6 +3480,10 @@ purpose may not result in @var{name} being interpreted as a macro keyword. @end defspec + +@node Environment Frames, Syntactic Hooks for Hygienic Macros, Macro Primitives, Syntax +@subsection Environment Frames + An @dfn{environment} is a list of frames representing lexical bindings. Only the names and scope of the bindings are included in environments passed to macro expanders -- run-time values are not included. @@ -3391,8 +3565,8 @@ Thus a mutable environment can be treated as both a list and local bindings. @end defspec -@node Syntactic Hooks for Hygienic Macros, , Low Level Syntactic Hooks, The Language -@section Syntactic Hooks for Hygienic Macros +@node Syntactic Hooks for Hygienic Macros, , Environment Frames, Syntax +@subsection Syntactic Hooks for Hygienic Macros SCM provides a synthetic identifier type for efficient implementation of hygienic macros (for example, @code{syntax-rules} @pxref{Macros, , , @@ -3432,7 +3606,8 @@ Returns the symbol obtained by recursively extracting the parent of @var{id}, which must be an identifier. @end defun -@subsection Use of synthetic identifiers +@subsection Use of Synthetic Identifiers + @code{renamed-identifier} may be used as a replacement for @code{gentemp}: @lisp (define gentemp @@ -3931,22 +4106,25 @@ is not real. @menu * Conventional Arrays:: -* Array Mapping:: array-for-each * Uniform Array:: * Bit Vectors:: +* Array Mapping:: array-for-each @end menu -@node Conventional Arrays, Array Mapping, Arrays, Arrays +@node Conventional Arrays, Uniform Array, Arrays, Arrays @subsection Conventional Arrays +The following syntax and procedures are SCM extensions to feature +@code{array} in @ref{Arrays, , , slib, SLIB}. + @dfn{Arrays} read and write as a @code{#} followed by the @dfn{rank} @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{} -#2A((ho ho ho) (ho ho ho) (ho ho ho)) +(create-array '#(ho) 4 3) @result{} +#2A((ho ho ho) (ho ho ho) (ho ho ho) (ho ho ho)) @end example The rank may be elided, in which case it is read as one. @@ -3954,60 +4132,11 @@ The rank may be elided, in which case it is read as one. '#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) -@end example - -When constructing an array, @var{bound} is either an inclusive range of -indices expressed as a two element list, or an upper bound expressed -as a single integer. So -@example -(make-array 'foo 3 3) @equiv{} (make-array 'foo '(0 2) '(0 2)) -@end example - -@defun array? obj -Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not. -@end defun - -@defun make-array initial-value bound1 bound2 @dots{} -Creates and returns an array that has as many dimensions as there are -@var{bound}s and fills it with @var{initial-value}. -@end defun - -@defun array-ref array index1 index2 @dots{} -Returns the @var{index1}, @var{index2}, @dots{}'th element of -@var{array}. -@end defun - -@defun array-in-bounds? array index1 index2 @dots{} -Returns @code{#t} if its arguments would be acceptable to @var{array-ref}. -@end defun - -@defun array-set! array new-value index1 index2 @dots{} -Sets the @var{index1}, @var{index2}, @dots{}'th element of @var{array} -to @var{new-value}. The value returned by @code{array-set!} is -unspecified. -@end defun - -@defun make-shared-array array mapper bound1 bound2 @dots{} -@code{make-shared-array} can be used to create shared subarrays of other -arrays. The @var{mapper} is a function that translates coordinates in -the new array into coordinates in the old array. A @var{mapper} must be -linear, and its range must stay within the bounds of the old array, but -it can be otherwise arbitrary. A simple example: +Unshared, conventional (not uniform) 0-based arrays of rank 1 are +equivalent to (and can't be distinguished from) scheme vectors. @example -(define fred (make-array #f 8 8)) -(define freds-diagonal - (make-shared-array fred (lambda (i) (list i i)) 8)) -(array-set! freds-diagonal 'foo 3) -(array-ref fred 3 3) @result{} foo -(define freds-center - (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2)) -(array-ref freds-center 0 0) @result{} foo +(create-array '#(ho) 3) @result{} #(ho ho ho) @end example -@end defun @defun transpose-array array dim0 dim1 @dots{} Returns an array sharing contents with @var{array}, but with dimensions @@ -4055,132 +4184,26 @@ examples: @end example @end defun -@defun array-shape array -Returns a list of inclusive bounds of integers. -@example -(array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4)) -@end example -@end defun - -@defun array-dimensions array -@code{Array-dimensions} is similar to @code{array-shape} but replaces -elements with a @code{0} minimum with one greater than the maximum. So: -@example -(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5) -@end example -@end defun - -@defun array-rank obj -Returns the number of dimensions of @var{obj}. If @var{obj} is not an -array, @code{0} is returned. -@end defun - @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 -Copies every element from vector or array @var{source} to the -corresponding element of @var{destination}. @var{destination} must have -the same rank as @var{source}, and be at least as large in each -dimension. The order of copying is unspecified. -@end defun - -@defun serial-array-copy! source destination -Same as @code{array-copy!} but guaranteed to copy in row-major order. -@end defun - -@defun array-fill! array fill -Stores @var{fill} in every element of @var{array}. The value returned -is unspecified. -@end defun - -@defun array-equal? array0 array1 @dots{} -Returns @code{#t} iff all arguments are arrays with the same shape, the -same type, and have corresponding elements which are either -@code{equal?} or @code{array-equal?}. This function differs from -@code{equal?} in that a one dimensional shared array may be -@var{array-equal?} but not @var{equal?} to a vector or uniform vector. -@end defun - @defun array-contents array @defunx array-contents array strict -If @var{array} may be @dfn{unrolled} into a one dimensional shared array -without changing their order (last subscript changing fastest), then -@code{array-contents} returns that shared array, otherwise it returns -@code{#f}. All arrays made by @var{make-array} and -@var{create-array} may be unrolled, some arrays made by -@var{make-shared-array} may not be. +If @var{array} may be @dfn{unrolled} into a one dimensional shared +array without changing their order (last subscript changing fastest), +then @code{array-contents} returns that shared array, otherwise it +returns @code{#f}. All arrays made by @var{create-array} may be +unrolled, some arrays made by @var{make-shared-array} may not be. If the optional argument @var{strict} is provided, a shared array will be returned only if its elements are stored internally contiguous in memory. @end defun -@node Array Mapping, Uniform Array, Conventional Arrays, Arrays -@subsection Array Mapping -@code{(require 'array-for-each)} -@ftindex array-for-each - -@defun array-map! array0 proc array1 @dots{} - -If @var{array1}, @dots{} are arrays, they must have the same number of -dimensions as @var{array0} and have a range for each index which -includes the range for the corresponding index in @var{array0}. -If they are scalars, that is, not arrays, vectors, or strings, then -they will be converted internally to arrays of the appropriate shape. -@var{proc} is applied to each tuple of elements of @var{array1} @dots{} -and the result is stored as the corresponding element in @var{array0}. -The value returned is unspecified. The order of application is -unspecified. - -@end defun - -@defun serial-array-map! array0 proc array1 @dots{} -Same as @var{array-map!}, but guaranteed to apply @var{proc} in -row-major order. -@end defun - -@defun array-for-each proc array0 @dots{} -@var{proc} is applied to each tuple of elements of @var{array0} @dots{} -in row-major order. The value returned is unspecified. -@end defun - -@defun array-index-map! array proc -applies @var{proc} to the indices of each element of @var{array} in -turn, storing the result in the corresponding element. The value -returned and the order of application are unspecified. - -One can implement @var{array-indexes} as -@example -(define (array-indexes array) - (let ((ra (apply make-array #f (array-shape array)))) - (array-index-map! ra (lambda x x)) - ra)) -@end example -Another example: -@example -(define (apl:index-generator n) - (let ((v (make-vector n 1))) - (array-index-map! v (lambda (i) i)) - v)) -@end example -@end defun - -@defun scalar->array scalar array prototype -Returns a uniform array of the same shape as @var{array}, having only -one shared element, which is @code{eqv?} to @var{scalar}. -If the optional argument @var{prototype} is supplied it will be used -as the prototype for the returned array. Otherwise the returned array -will be of the same type as @code{array} if that is possible, and -a conventional array if it is not. This function is used internally -by @code{array-map!} and friends to handle scalar arguments. -@end defun - - -@node Uniform Array, Bit Vectors, Array Mapping, Arrays +@node Uniform Array, Bit Vectors, Conventional Arrays, Arrays @subsection Uniform Array @noindent @@ -4260,19 +4283,6 @@ 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 -Stores @var{fill} in every element of @var{uve}. The value returned is -unspecified. -@end defun - -@defun dimensions->uniform-array dims prototype fill -@defunx dimensions->uniform-array dims prototype -Creates and returns a uniform array or vector of type corresponding to -@var{prototype} with dimensions @var{dims} or length @var{length}. If -the @var{fill} argument is supplied, the returned array is filled with -this value. -@end defun - @defun uniform-array-read! ura @defunx uniform-array-read! ura port Attempts to read all elements of @var{ura}, in lexicographic order, as @@ -4321,7 +4331,7 @@ if the array element is not an exact integer or if @var{val} is not boolean. @end defun -@node Bit Vectors, , Uniform Array, Arrays +@node Bit Vectors, Array Mapping, Uniform Array, Arrays @subsection Bit Vectors @noindent @@ -4370,6 +4380,74 @@ Returns @var{bv} is not modified. @end defun + +@node Array Mapping, , Bit Vectors, Arrays +@subsection Array Mapping + +@code{(require 'array-for-each)} +@ftindex array-for-each + +SCM has some extra functions in feature @code{array-for-each}: + +@defun array-fill! array fill +Stores @var{fill} in every element of @var{array}. The value returned +is unspecified. +@end defun + +@defun serial-array-copy! source destination +Same as @code{array-copy!} but guaranteed to copy in row-major order. +@end defun + +@defun array-equal? array0 array1 @dots{} +Returns @code{#t} iff all arguments are arrays with the same shape, the +same type, and have corresponding elements which are either +@code{equal?} or @code{array-equal?}. This function differs from +@code{equal?} in that a one dimensional shared array may be +@var{array-equal?} but not @var{equal?} to a vector or uniform vector. +@end defun + +@defun array-map! array0 proc array1 @dots{} +If @var{array1}, @dots{} are arrays, they must have the same number of +dimensions as @var{array0} and have a range for each index which +includes the range for the corresponding index in @var{array0}. If +they are scalars, that is, not arrays, vectors, or strings, then they +will be converted internally to arrays of the appropriate shape. +@var{proc} is applied to each tuple of elements of @var{array1} +@dots{} and the result is stored as the corresponding element in +@var{array0}. The value returned is unspecified. The order of +application is unspecified. + +Handling non-array arguments is a SCM extension of +@ref{Array Mapping, array-map!, , slib, SLIB} +@end defun + +@defun serial-array-map! array0 proc array1 @dots{} +Same as @var{array-map!}, but guaranteed to apply @var{proc} in +row-major order. +@end defun + +@defun array-map prototype proc array1 array2 @dots{} +@var{array2}, @dots{} must have the same number of dimensions as +@var{array1} and have a range for each index which includes the +range for the corresponding index in @var{array1}. @var{proc} is +applied to each tuple of elements of @var{array1}, @var{array2}, +@dots{} and the result is stored as the corresponding element in a +new array of type @var{prototype}. The new array is returned. The +order of application is unspecified. +@end defun + +@defun scalar->array scalar array prototype +@defunx scalar->array scalar array +Returns a uniform array of the same shape as @var{array}, having only +one shared element, which is @code{eqv?} to @var{scalar}. +If the optional argument @var{prototype} is supplied it will be used +as the prototype for the returned array. Otherwise the returned array +will be of the same type as @code{array} if that is possible, and +a conventional array if it is not. This function is used internally +by @code{array-map!} and friends to handle scalar arguments. +@end defun + + @node Records, I/O-Extensions, Arrays, Packages @section Records @@ -4498,12 +4576,11 @@ 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. +@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 filenames 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 @@ -4515,7 +4592,7 @@ Applies @var{proc} only to those filenames for which (@pxref{Filenames, , , slib, SLIB}). @example -(require 'directory-for-each) +(require 'directory) (directory-for-each print "." "[A-Z]*.scm") @print{} "Init.scm" @@ -4657,6 +4734,8 @@ Interface, getenv, , slib, SLIB}). @node Posix Extensions, Unix Extensions, I/O-Extensions, Packages @section Posix Extensions +@cindex Posix +@cindex posix @noindent If @code{'posix} is provided (by linking in @file{posix.o}), the following functions are defined: @@ -4718,11 +4797,6 @@ Returns the process ID of the parent of the current process. For a process's own ID @xref{I/O-Extensions, getpid}. @end defun -@defun getlogin -Returns the (login) name of the user logged in on the controlling -terminal of the process, or #f if this information cannot be determined. -@end defun - @defun getuid Returns the real user ID of this process. @end defun @@ -4974,6 +5048,8 @@ string containing the file name of termainal device; otherwise @node Unix Extensions, Regular Expression Pattern Matching, Posix Extensions, Packages @section Unix Extensions +@cindex Unix +@cindex unix @noindent If @code{'unix} is provided (by linking in @file{unix.o}), the following functions are defined: @@ -5613,13 +5689,13 @@ to most of the C @dfn{socket} library. For more information on sockets, @xref{Sockets, , , libc, The GNU C Library Reference Manual}. @menu -* Host Data:: +* Host and Other Inquiries:: * Internet Addresses and Socket Names:: * Socket:: @end menu -@node Host Data, Internet Addresses and Socket Names, Sockets, Sockets -@subsection Host Data, Network, Protocol, and Service Inquiries +@node Host and Other Inquiries, Internet Addresses and Socket Names, Sockets, Sockets +@subsection Host and Other Inquiries @defvr Constant af_inet @defvrx Constant af_unix @@ -5728,7 +5804,7 @@ between calls to getserv. Otherwise, the table stays open. When called without an argument, the service table is closed. @end defun -@node Internet Addresses and Socket Names, Socket, Host Data, Sockets +@node Internet Addresses and Socket Names, Socket, Host and Other Inquiries, Sockets @subsection Internet Addresses and Socket Names @defun inet:string->address string @@ -6620,7 +6696,7 @@ synchronization object. @xref{Process Synchronization}. @end deftp @deftp smob tc16_macro -macro expanding function. @xref{Low Level Syntactic Hooks}. +macro expanding function. @xref{Macro Primitives}. @end deftp @deftp smob tc16_array @@ -6676,15 +6752,15 @@ contin .........long length....G0111101 .............*regs.............. 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..........} +@t{ port int portnum.CwroxxxxxxxxG0110111 ..........FILE *stream.......... + socket int portnum.C001xxxxxxxxG0110111 ..........FILE *stream.......... + inport int portnum.C011xxxxxxxxG0110111 ..........FILE *stream.......... +outport int portnum.0101xxxxxxxxG0110111 ..........FILE *stream.......... + ioport int portnum.C111xxxxxxxxG0110111 ..........FILE *stream.......... +fport int portnum.C 00000000G0110111 ..........FILE *stream.......... +pipe int portnum.C 00000001G0110111 ..........FILE *stream.......... +strport 00000000000.0 00000010G0110111 ..........FILE *stream.......... +sfport int portnum.C 00000011G0110111 ..........FILE *stream..........} @r{ SUBRs:} @t{ spare 010001x1 spare 010011x1 @@ -6823,6 +6899,9 @@ object is freed. If the type header of smob is collected, the smob's @node Memory Management for Environments, Signals, Garbage Collection, Operations @subsection Memory Management for Environments +@ifset html +<A NAME="ecache"></A> +@end ifset @cindex memory management @cindex environments @cindex ecache @@ -6979,7 +7058,7 @@ that this constraint is satisfied @code{#define CAREFUL_INTS} in @subsection C Macros -@defmac ASSERT cond arg pos subr +@defmac ASRTER cond arg pos subr signals an error if the expression (@var{cond}) is 0. @var{arg} is the offending object, @var{subr} is the string naming the subr, and @var{pos} indicates the position or type of error. @var{pos} can be one @@ -7006,14 +7085,14 @@ of @item a C string @code{(char *)} @end itemize -Error checking is not done by @code{ASSERT} if the flag @code{RECKLESS} +Error checking is not done by @code{ASRTER} if the flag @code{RECKLESS} is defined. An error condition can still be signaled in this case with a call to @code{wta(arg, pos, subr)}. @end defmac @defmac ASRTGO cond label @code{goto} @var{label} if the expression (@var{cond}) is 0. Like -@code{ASSERT}, @code{ASRTGO} does is not active if the flag +@code{ASRTER}, @code{ASRTGO} does is not active if the flag @code{RECKLESS} is defined. @end defmac @@ -7049,13 +7128,21 @@ address of the local @code{SCM} variable to @emph{any} procedure also protects it. The procedure @code{scm_protect_temp} is provided for this purpose. +@deftypefun void scm_protect_temp (SCM *@var{ptr}) +Forces the SCM object @var{ptr} to be saved on the C-stack, where it +will be traced for GC. +@end deftypefun + @noindent Also, if you maintain a static pointer to some (non-immediate) @code{SCM} object, you must either make your pointer be the value cell -of a symbol (see @code{errobj} for an example) or make your pointer be -one of the @code{sys_protects} (see @code{dynwinds} for an example). -The former method is prefered since it does not require any changes to -the SCM distribution. +of a symbol (see @code{errobj} for an example) or (permanently) add +your pointer to @code{sys_protects} using: + +@deftypefun SCM scm_gc_protect (SCM @var{obj}) +Permanently adds @var{obj} to a table of objects protected from +garbage collection. @code{scm_gc_protect} returns @var{obj}. +@end deftypefun @noindent To add a C routine to scm: @@ -7178,7 +7265,8 @@ add @code{case:} clause to @code{ceval()} near @code{i_quasiquote} (in New syntax can now be added without recompiling SCM by the use of the @code{procedure->syntax}, @code{procedure->macro}, @code{procedure->memoizing-macro}, and @code{defmacro}. For details, -@xref{Syntax Extensions}. +@xref{Syntax}. + @node Defining Subrs, Defining Smobs, Changing Scm, Operations @subsection Defining Subrs @@ -7557,9 +7645,9 @@ Here is a minimal embedding program @file{libtest.c}: /* include patchlvl.h for SCM's INIT_FILE_NAME. */ #include "patchlvl.h" -void init_user_scm() +void libtest_init_user_scm() @{ - fputs("This is init_user_scm\n", stderr); fflush(stderr); + fputs("This is libtest_init_user_scm\n", stderr); fflush(stderr); sysintern("*the-string*", makfrom0str("hello world\n")); @} @@ -7578,6 +7666,7 @@ int main(argc, argv) SCM retval; char *implpath, *execpath; + init_user_scm = libtest_init_user_scm; 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); @@ -7593,7 +7682,7 @@ int main(argc, argv) @print{} dld_find_executable(./libtest): /home/jaffer/scm/libtest implpath: /home/jaffer/scm/Init@value{SCMVERSION}.scm -This is init_user_scm +This is libtest_init_user_scm hello world @end example @@ -7602,6 +7691,7 @@ hello world @subsection Callbacks @cindex callbacks +@cindex rope @noindent SCM now has routines to make calling back to Scheme procedures easier. The source code for these routines are found in @file{rope.c}. @@ -7653,9 +7743,12 @@ can use a wrapper like this for your Scheme procedures: @noindent Calls to procedures so wrapped will return even if an error occurs. + + @node Type Conversions, Continuations, Callbacks, Operations @subsection Type Conversions +@cindex rope These type conversion functions are very useful for connecting SCM and C code. Most are defined in @file{rope.c}. @@ -7672,19 +7765,21 @@ To convert integer numbers of smaller types (@code{short} or @deftypefun long num2long (SCM @var{num}, char *@var{pos}, char *@var{s_caller}) @deftypefunx unsigned long num2ulong (SCM @var{num}, char *@var{pos}, char *@var{s_caller}) +@deftypefunx short num2short (SCM @var{num}, char *@var{pos}, char *@var{s_caller}) @deftypefunx unsigned short num2ushort (SCM @var{num}, char *@var{pos}, char *@var{s_caller}) @deftypefunx unsigned char num2uchar (SCM @var{num}, char *@var{pos}, char *@var{s_caller}) +@deftypefunx double num2dbl (SCM @var{num}, char *@var{pos}, char *@var{s_caller}) These functions are used to check and convert @code{SCM} arguments to the named C type. The first argument @var{num} is checked to see it it is within the range of the destination type. If so, the converted -number is returned. If not, the @code{ASSERT} macro calls @code{wta} +number is returned. If not, the @code{ASRTER} macro calls @code{wta} with @var{num} and strings @var{pos} and @var{s_caller}. For a listing 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, , r5rs, Revised(5) Scheme}. +@emph{Note:} Inexact numbers are accepted only by @code{num2dbl}, +@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, , r5rs, Revised(5) Scheme}. @end deftypefun @deftypefun unsigned long scm_addr (SCM @var{args}, char *@var{s_name}) @@ -7696,10 +7791,17 @@ any messages from error calls by @code{scm_addr}. @code{scm_addr} is useful for performing C operations on strings or other uniform arrays (@pxref{Uniform Array}). -@emph{Note:} While you use a pointer returned from @code{scm_addr} you -must keep a pointer to the associated @code{SCM} object in a stack -allocated variable or GC-protected location in order to assure that SCM -does not reuse that storage before you are done with it. +@deftypefunx unsigned long scm_base_addr(SCM @var{ra}, char *@var{s_name}) +Returns a pointer (cast to an @code{unsigned long}) to the beginning +of storage of array @var{ra}. Note that if @var{ra} is a +shared-array, the strorage accessed this way may be much larger than +@var{ra}. + +@emph{Note:} While you use a pointer returned from @code{scm_addr} or +@code{scm_base_addr} you must keep a pointer to the associated +@code{SCM} object in a stack allocated variable or GC-protected +location in order to assure that SCM does not reuse that storage +before you are done with it. @xref{Changing Scm, scm_gc_protect}. @end deftypefun @deftypefun SCM makfrom0str (char *@var{src}) @@ -8178,20 +8280,18 @@ the interpreter to instead always look up the values of the associated symbols. @end quotation +@item +Scott Schwartz <schwartz@@galapagos.cse.psu.edu> suggests: One way to +tidy up the dynamic loading stuff would be to grab the code from perl5. + @end itemize @menu -* Finishing Dynamic Linking:: +* VMS Dynamic Linking:: Finishing the job. @end menu -@node Finishing Dynamic Linking, , Improvements To Make, Improvements To Make -@subsection Finishing Dynamic Linking - -@noindent -Scott Schwartz <schwartz@@galapagos.cse.psu.edu> suggests: One way to -tidy up the dynamic loading stuff would be to grab the code from perl5. - -@subsubheading VMS +@node VMS Dynamic Linking, , Improvements To Make, Improvements To Make +@subsection VMS Dynamic Linking @noindent George Carrette (gjc@@mitech.com) outlines how to dynamically link on @@ -8329,113 +8429,6 @@ modify and relink @file{LISPLIB.EXE} without having to relink programs that have been linked against it. @end enumerate -@subsubheading Windows NT -@noindent -George Carrette (gjc@@mitech.com) outlines how to dynamically link on -Windows NT: - -@itemize @bullet -@item -The Software Developers Kit has a sample called SIMPLDLL. -Here is the gist of it, following along the lines of the VMS description -above (contents of a makefile for the SDK NMAKE) - -@format -@t{LISPLIB.exp: -LISPLIB.lib: LISPLIB.def - $(implib) -machine:$(CPU) -def:LISPLIB.def -out:LISPLIB.lib - -LISPLIB.DLL : $(LISPLIB_OBJS) LISPLIB.EXP - $(link) $(linkdebug) \ - -dll \ - -out:LISPLIB.DLL \ - LISPLIB.EXP $(LISPLIB_OBJS) $(conlibsdll)} -@end format - -@item -The @file{LISPDEF.DEF} file has this: - -@format -@t{LIBRARY lisplib -EXPORT - init_lisp - init_repl} -@end format - -@item -And @file{MAIN.EXE} using: - -@format -@t{CLINK = $(link) $(ldebug) $(conflags) -out:$*.exe $** $(conlibsdll) - -MAIN.EXE : MAIN.OBJ LISPLIB.LIB - $(CLINK)} -@end format - -@item -And @file{MYSUBRS.DLL} is produced using: - -@format -@t{mysubrs.exp: -mysubrs.lib: mysubrs.def - $(implib) -machine:$(CPU) -def:MYSUBRS.def -out:MYSUBRS.lib - -mysubrs.dll : mysubrs.obj mysubrs.exp mysubrs.lib - $(link) $(linkdebug) \ - -dll \ - -out:mysubrs.dll \ - MYSUBRS.OBJ MYSUBRS.EXP LISPLIB.LIB $(conlibsdll)} -@end format - -@item -Where @file{MYSUBRS.DEF} has - -@format -@t{LIBRARY mysubrs -EXPORT - INIT_MYSUBRS} -@end format - -@item -And the dynamic loader looks something like this, calling the two -procedures @code{LoadLibrary} and @code{GetProcAddress}. - -@format -@t{LISP share_image_load(LISP fname) -@{long iflag; - LISP retval,(*fcn)(void); - HANDLE hLib; - DWORD err; - char *libname,fcnname[64]; - iflag = nointerrupt(1); - libname = c_string(fname); - _snprintf(fcnname,sizeof(fcnname),"INIT_%s",libname); - if (!(hLib = LoadLibrary(libname))) - @{err = GetLastError(); - retval = list2(fname,LSPNUM(err)); - serror1("library failed to load",retval);@} - if (!(fcn = (LISP (*)(void)) GetProcAddress(hLib,fcnname))) - @{err = GetLastError(); - retval = list2(fname,LSPNUM(err)); - serror1("could not find library init procedure",retval);@} - retval = (*fcn)(); - nointerrupt(iflag); - return(retval);@}} -@end format - -@item -@emph{Note:} in VMS the linker and dynamic loader is case sensitive, but -all the language compilers, including C, will by default upper-case -external symbols for use by the linker, although the debugger gets its -own symbols and case sensitivity is language mode dependant. In Windows -NT things are case sensitive generally except for file and device names, -which are case canonicalizing like in the Symbolics filesystem. - -@item -@emph{Also:} All this WINDOWS NT stuff will work in MS-DOS MS-Windows -3.1 too, by a method of compiling and linking under Windows NT, and then -copying various files over to MS-DOS/WINDOWS. -@end itemize @node Index, , The Implementation, Top |