summaryrefslogtreecommitdiffstats
path: root/scm.texi
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:27 -0800
committerBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:27 -0800
commitc7d035ae1a729232579a0fe41ed5affa131d3623 (patch)
treefb387f7c2a8e01cf603d4c75fbbaa68f711df986 /scm.texi
parentdeda2c0fd8689349fea2a900199a76ff7ecb319e (diff)
downloadscm-c7d035ae1a729232579a0fe41ed5affa131d3623.tar.gz
scm-c7d035ae1a729232579a0fe41ed5affa131d3623.zip
Import Upstream version 5d9upstream/5d9
Diffstat (limited to 'scm.texi')
-rw-r--r--scm.texi1367
1 files changed, 680 insertions, 687 deletions
diff --git a/scm.texi b/scm.texi
index f0cd485..2f87364 100644
--- a/scm.texi
+++ b/scm.texi
@@ -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