Import from pre-1.0 documentation from Richard.
This commit is contained in:
sperber
parent
3dedf2b9a7
commit
cdd7382bf1
|
|
@ -0,0 +1,170 @@
|
|||
|
||||
(define control-names
|
||||
'#("NUL" "SOH" "STX" "ETX" "EOT" "ENQ" "ACK" "BEL"
|
||||
"BS" "HT" "LF" "VT" "FF" "CR" "SO" "SI"
|
||||
"DLE" "DC1" "DC2" "DC3" "DC4" "NAK" "SYN" "ETB"
|
||||
"CAN" "EM" "SUB" "ESC" "FS" "GS" "RS" "US"
|
||||
"SPACE"))
|
||||
|
||||
(define unicode-latin-1-names
|
||||
'#("NULL"
|
||||
"START OF HEADING"
|
||||
"START OF TEXT"
|
||||
"END OF TEXT"
|
||||
"END OF TRANSMISSION"
|
||||
"ENQUIRY"
|
||||
"ACKNOWLEDGE"
|
||||
"BELL"
|
||||
"BACKSPACE"
|
||||
"HORIZONTAL TABULATION"
|
||||
"LINE FEED"
|
||||
"VERTICAL TABULATION"
|
||||
"FORM FEED"
|
||||
"CARRIAGE RETURN"
|
||||
"SHIFT OUT"
|
||||
"SHIFT IN"
|
||||
"DATA LINK ESCAPE"
|
||||
"DEVICE CONTROL ONE"
|
||||
"DEVICE CONTROL TWO"
|
||||
"DEVICE CONTROL THREE"
|
||||
"DEVICE CONTROL FOUR"
|
||||
"NEGATIVE ACKNOWLEDGE"
|
||||
"SYNCHRONOUS IDLE"
|
||||
"END OF TRANSMISSION BLOCK"
|
||||
"CANCEL"
|
||||
"END OF MEDIUM"
|
||||
"SUBSTITUTE"
|
||||
"ESCAPE"
|
||||
"FILE SEPARATOR"
|
||||
"GROUP SEPARATOR"
|
||||
"RECORD SEPARATOR"
|
||||
"UNIT SEPARATOR"
|
||||
"SPACE"
|
||||
"EXCLAMATION MARK"
|
||||
"QUOTATION MARK"
|
||||
"NUMBER SIGN"
|
||||
"DOLLAR SIGN"
|
||||
"PERCENT SIGN"
|
||||
"AMPERSAND"
|
||||
"APOSTROPHE"
|
||||
"LEFT PARENTHESIS"
|
||||
"RIGHT PARENTHESIS"
|
||||
"ASTERISK"
|
||||
"PLUS SIGN"
|
||||
"COMMA"
|
||||
"HYPHEN-MINUS"
|
||||
"FULL STOP"
|
||||
"SOLIDUS"
|
||||
"DIGIT ZERO"
|
||||
"DIGIT ONE"
|
||||
"DIGIT TWO"
|
||||
"DIGIT THREE"
|
||||
"DIGIT FOUR"
|
||||
"DIGIT FIVE"
|
||||
"DIGIT SIX"
|
||||
"DIGIT SEVEN"
|
||||
"DIGIT EIGHT"
|
||||
"DIGIT NINE"
|
||||
"COLON"
|
||||
"SEMICOLON"
|
||||
"LESS-THAN SIGN"
|
||||
"EQUALS SIGN"
|
||||
"GREATER-THAN SIGN"
|
||||
"QUESTION MARK"
|
||||
"COMMERCIAL AT"
|
||||
"LATIN CAPITAL LETTER A"
|
||||
"LATIN CAPITAL LETTER B"
|
||||
"LATIN CAPITAL LETTER C"
|
||||
"LATIN CAPITAL LETTER D"
|
||||
"LATIN CAPITAL LETTER E"
|
||||
"LATIN CAPITAL LETTER F"
|
||||
"LATIN CAPITAL LETTER G"
|
||||
"LATIN CAPITAL LETTER H"
|
||||
"LATIN CAPITAL LETTER I"
|
||||
"LATIN CAPITAL LETTER J"
|
||||
"LATIN CAPITAL LETTER K"
|
||||
"LATIN CAPITAL LETTER L"
|
||||
"LATIN CAPITAL LETTER M"
|
||||
"LATIN CAPITAL LETTER N"
|
||||
"LATIN CAPITAL LETTER O"
|
||||
"LATIN CAPITAL LETTER P"
|
||||
"LATIN CAPITAL LETTER Q"
|
||||
"LATIN CAPITAL LETTER R"
|
||||
"LATIN CAPITAL LETTER S"
|
||||
"LATIN CAPITAL LETTER T"
|
||||
"LATIN CAPITAL LETTER U"
|
||||
"LATIN CAPITAL LETTER V"
|
||||
"LATIN CAPITAL LETTER W"
|
||||
"LATIN CAPITAL LETTER X"
|
||||
"LATIN CAPITAL LETTER Y"
|
||||
"LATIN CAPITAL LETTER Z"
|
||||
"LEFT SQUARE BRACKET"
|
||||
"REVERSE SOLIDUS"
|
||||
"RIGHT SQUARE BRACKET"
|
||||
"CIRCUMFLEX ACCENT"
|
||||
"LOW LINE"
|
||||
"GRAVE ACCENT"
|
||||
"LATIN SMALL LETTER A"
|
||||
"LATIN SMALL LETTER B"
|
||||
"LATIN SMALL LETTER C"
|
||||
"LATIN SMALL LETTER D"
|
||||
"LATIN SMALL LETTER E"
|
||||
"LATIN SMALL LETTER F"
|
||||
"LATIN SMALL LETTER G"
|
||||
"LATIN SMALL LETTER H"
|
||||
"LATIN SMALL LETTER I"
|
||||
"LATIN SMALL LETTER J"
|
||||
"LATIN SMALL LETTER K"
|
||||
"LATIN SMALL LETTER L"
|
||||
"LATIN SMALL LETTER M"
|
||||
"LATIN SMALL LETTER N"
|
||||
"LATIN SMALL LETTER O"
|
||||
"LATIN SMALL LETTER P"
|
||||
"LATIN SMALL LETTER Q"
|
||||
"LATIN SMALL LETTER R"
|
||||
"LATIN SMALL LETTER S"
|
||||
"LATIN SMALL LETTER T"
|
||||
"LATIN SMALL LETTER U"
|
||||
"LATIN SMALL LETTER V"
|
||||
"LATIN SMALL LETTER W"
|
||||
"LATIN SMALL LETTER X"
|
||||
"LATIN SMALL LETTER Y"
|
||||
"LATIN SMALL LETTER Z"
|
||||
"LEFT CURLY BRACKET"
|
||||
"VERTICAL LINE"
|
||||
"RIGHT CURLY BRACKET"
|
||||
"TILDE"
|
||||
"DELETE"))
|
||||
|
||||
(define (display-char i)
|
||||
(for-each display
|
||||
(list "\\code{" (number->string i 10) "} & \\code{"
|
||||
(string-upcase (number->string i 16)) "} & "
|
||||
(cond ((<= i 32)
|
||||
(vector-ref control-names i))
|
||||
((= i 127)
|
||||
"DEL")
|
||||
((= i (char->ascii #\|))
|
||||
"\\verb$|$")
|
||||
(else
|
||||
(string-append "\\verb|"
|
||||
(list->string (list (ascii->char i)))
|
||||
"|")))
|
||||
" & "
|
||||
(string-downcase (vector-ref unicode-latin-1-names i)))))
|
||||
|
||||
(define (string-upcase string)
|
||||
(list->string (map char-upcase (string->list string))))
|
||||
|
||||
(define (string-downcase string)
|
||||
(list->string (map char-downcase (string->list string))))
|
||||
|
||||
(define (write-ascii-table)
|
||||
(do ((i 0 (+ i 1)))
|
||||
((= i 64))
|
||||
(display-char i)
|
||||
(display " & ")
|
||||
(display-char (+ i 64))
|
||||
(display " \\\\")
|
||||
(newline)))
|
||||
|
||||
|
|
@ -0,0 +1,97 @@
|
|||
|
||||
\T\appendix
|
||||
\chapter{ASCII character encoding}
|
||||
\label{ascii-chart}
|
||||
|
||||
% Table of ASCII encodings (as used by CHAR->ASCII and ASCII->CHAR)
|
||||
|
||||
``ASCII'' stands for ``American Standard Code for Information Interchange''.
|
||||
The ASCII standard is a seven-bit code published by the United States of
|
||||
America Standards Institute (USASI) in 1968.
|
||||
The ASCII encoding forms the first half of ISO-8859-1 (Latin1) which in
|
||||
turn forms the first page of ISO 10646 (Unicode).
|
||||
|
||||
The Scheme~48 procedures
|
||||
\link{\code{char->ascii}}{ascii-procedures}
|
||||
and
|
||||
\link{\code{ascii->char}}{ascii-procedures}
|
||||
\T (section~\ref{ascii-procedures})
|
||||
give access to the ASCII encoding.
|
||||
|
||||
% Could also show named Scheme characters (#\space etc.) and C escapes.
|
||||
|
||||
\T{\small
|
||||
\W\begin{tabular}{rrllrrll}
|
||||
\T\setlongtables
|
||||
\T\begin{longtable}{rrllrrll}
|
||||
n$_{10}$ & n$_{16}$ & & Unicode name & n$_{10}$ & n$_{16}$ & & Unicode name \\
|
||||
\T\endfirsthead
|
||||
\T n$_{10}$ & n$_{16}$ & & Unicode name & n$_{10}$ & n$_{16}$ & & Unicode name \\
|
||||
\T\endhead
|
||||
\code{0} & \code{0} & NUL & null & \code{64} & \code{40} & \verb|@| & commercial at \\
|
||||
\code{1} & \code{1} & SOH & start of heading & \code{65} & \code{41} & \verb|A| & latin capital letter a \\
|
||||
\code{2} & \code{2} & STX & start of text & \code{66} & \code{42} & \verb|B| & latin capital letter b \\
|
||||
\code{3} & \code{3} & ETX & end of text & \code{67} & \code{43} & \verb|C| & latin capital letter c \\
|
||||
\code{4} & \code{4} & EOT & end of transmission & \code{68} & \code{44} & \verb|D| & latin capital letter d \\
|
||||
\code{5} & \code{5} & ENQ & enquiry & \code{69} & \code{45} & \verb|E| & latin capital letter e \\
|
||||
\code{6} & \code{6} & ACK & acknowledge & \code{70} & \code{46} & \verb|F| & latin capital letter f \\
|
||||
\code{7} & \code{7} & BEL & bell & \code{71} & \code{47} & \verb|G| & latin capital letter g \\
|
||||
\code{8} & \code{8} & BS & backspace & \code{72} & \code{48} & \verb|H| & latin capital letter h \\
|
||||
\code{9} & \code{9} & HT & horizontal tabulation & \code{73} & \code{49} & \verb|I| & latin capital letter i \\
|
||||
\code{10} & \code{A} & LF & line feed & \code{74} & \code{4A} & \verb|J| & latin capital letter j \\
|
||||
\code{11} & \code{B} & VT & vertical tabulation & \code{75} & \code{4B} & \verb|K| & latin capital letter k \\
|
||||
\code{12} & \code{C} & FF & form feed & \code{76} & \code{4C} & \verb|L| & latin capital letter l \\
|
||||
\code{13} & \code{D} & CR & carriage return & \code{77} & \code{4D} & \verb|M| & latin capital letter m \\
|
||||
\code{14} & \code{E} & SO & shift out & \code{78} & \code{4E} & \verb|N| & latin capital letter n \\
|
||||
\code{15} & \code{F} & SI & shift in & \code{79} & \code{4F} & \verb|O| & latin capital letter o \\
|
||||
\code{16} & \code{10} & DLE & data link escape & \code{80} & \code{50} & \verb|P| & latin capital letter p \\
|
||||
\code{17} & \code{11} & DC1 & device control one & \code{81} & \code{51} & \verb|Q| & latin capital letter q \\
|
||||
\code{18} & \code{12} & DC2 & device control two & \code{82} & \code{52} & \verb|R| & latin capital letter r \\
|
||||
\code{19} & \code{13} & DC3 & device control three & \code{83} & \code{53} & \verb|S| & latin capital letter s \\
|
||||
\code{20} & \code{14} & DC4 & device control four & \code{84} & \code{54} & \verb|T| & latin capital letter t \\
|
||||
\code{21} & \code{15} & NAK & negative acknowledge & \code{85} & \code{55} & \verb|U| & latin capital letter u \\
|
||||
\code{22} & \code{16} & SYN & synchronous idle & \code{86} & \code{56} & \verb|V| & latin capital letter v \\
|
||||
\code{23} & \code{17} & ETB & end of transmission block & \code{87} & \code{57} & \verb|W| & latin capital letter w \\
|
||||
\code{24} & \code{18} & CAN & cancel & \code{88} & \code{58} & \verb|X| & latin capital letter x \\
|
||||
\code{25} & \code{19} & EM & end of medium & \code{89} & \code{59} & \verb|Y| & latin capital letter y \\
|
||||
\code{26} & \code{1A} & SUB & substitute & \code{90} & \code{5A} & \verb|Z| & latin capital letter z \\
|
||||
\code{27} & \code{1B} & ESC & escape & \code{91} & \code{5B} & \verb|[| & left square bracket \\
|
||||
\code{28} & \code{1C} & FS & file separator & \code{92} & \code{5C} & \verb|\| & reverse solidus \\
|
||||
\code{29} & \code{1D} & GS & group separator & \code{93} & \code{5D} & \verb|]| & right square bracket \\
|
||||
\code{30} & \code{1E} & RS & record separator & \code{94} & \code{5E} & \verb|^| & circumflex accent \\
|
||||
\code{31} & \code{1F} & US & unit separator & \code{95} & \code{5F} & \verb|_| & low line \\
|
||||
\code{32} & \code{20} & SPACE & space & \code{96} & \code{60} & \verb|`| & grave accent \\
|
||||
\code{33} & \code{21} & \verb|!| & exclamation mark & \code{97} & \code{61} & \verb|a| & latin small letter a \\
|
||||
\code{34} & \code{22} & \verb|"| & quotation mark & \code{98} & \code{62} & \verb|b| & latin small letter b \\
|
||||
\code{35} & \code{23} & \verb|#| & number sign & \code{99} & \code{63} & \verb|c| & latin small letter c \\
|
||||
\code{36} & \code{24} & \verb|$| & dollar sign & \code{100} & \code{64} & \verb|d| & latin small letter d \\
|
||||
\code{37} & \code{25} & \verb|%| & percent sign & \code{101} & \code{65} & \verb|e| & latin small letter e \\
|
||||
\code{38} & \code{26} & \verb|&| & ampersand & \code{102} & \code{66} & \verb|f| & latin small letter f \\
|
||||
\code{39} & \code{27} & \verb|'| & apostrophe & \code{103} & \code{67} & \verb|g| & latin small letter g \\
|
||||
\code{40} & \code{28} & \verb|(| & left parenthesis & \code{104} & \code{68} & \verb|h| & latin small letter h \\
|
||||
\code{41} & \code{29} & \verb|)| & right parenthesis & \code{105} & \code{69} & \verb|i| & latin small letter i \\
|
||||
\code{42} & \code{2A} & \verb|*| & asterisk & \code{106} & \code{6A} & \verb|j| & latin small letter j \\
|
||||
\code{43} & \code{2B} & \verb|+| & plus sign & \code{107} & \code{6B} & \verb|k| & latin small letter k \\
|
||||
\code{44} & \code{2C} & \verb|,| & comma & \code{108} & \code{6C} & \verb|l| & latin small letter l \\
|
||||
\code{45} & \code{2D} & \verb|-| & hyphen-minus & \code{109} & \code{6D} & \verb|m| & latin small letter m \\
|
||||
\code{46} & \code{2E} & \verb|.| & full stop & \code{110} & \code{6E} & \verb|n| & latin small letter n \\
|
||||
\code{47} & \code{2F} & \verb|/| & solidus & \code{111} & \code{6F} & \verb|o| & latin small letter o \\
|
||||
\code{48} & \code{30} & \verb|0| & digit zero & \code{112} & \code{70} & \verb|p| & latin small letter p \\
|
||||
\code{49} & \code{31} & \verb|1| & digit one & \code{113} & \code{71} & \verb|q| & latin small letter q \\
|
||||
\code{50} & \code{32} & \verb|2| & digit two & \code{114} & \code{72} & \verb|r| & latin small letter r \\
|
||||
\code{51} & \code{33} & \verb|3| & digit three & \code{115} & \code{73} & \verb|s| & latin small letter s \\
|
||||
\code{52} & \code{34} & \verb|4| & digit four & \code{116} & \code{74} & \verb|t| & latin small letter t \\
|
||||
\code{53} & \code{35} & \verb|5| & digit five & \code{117} & \code{75} & \verb|u| & latin small letter u \\
|
||||
\code{54} & \code{36} & \verb|6| & digit six & \code{118} & \code{76} & \verb|v| & latin small letter v \\
|
||||
\code{55} & \code{37} & \verb|7| & digit seven & \code{119} & \code{77} & \verb|w| & latin small letter w \\
|
||||
\code{56} & \code{38} & \verb|8| & digit eight & \code{120} & \code{78} & \verb|x| & latin small letter x \\
|
||||
\code{57} & \code{39} & \verb|9| & digit nine & \code{121} & \code{79} & \verb|y| & latin small letter y \\
|
||||
\code{58} & \code{3A} & \verb|:| & colon & \code{122} & \code{7A} & \verb|z| & latin small letter z \\
|
||||
\code{59} & \code{3B} & \verb|;| & semicolon & \code{123} & \code{7B} & \verb|{| & left curly bracket \\
|
||||
\code{60} & \code{3C} & \verb|<| & less-than sign & \code{124} & \code{7C} & \verb$|$ & vertical line \\
|
||||
\code{61} & \code{3D} & \verb|=| & equals sign & \code{125} & \code{7D} & \verb|}| & right curly bracket \\
|
||||
\code{62} & \code{3E} & \verb|>| & greater-than sign & \code{126} & \code{7E} & \verb|~| & tilde \\
|
||||
\code{63} & \code{3F} & \verb|?| & question mark & \code{127} & \code{7F} & DEL & delete \\
|
||||
\W\end{tabular}
|
||||
\T\end{longtable}
|
||||
\T}
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
|
||||
\begin{thebibliography}{10}
|
||||
\addtocounter{chapter}{1}
|
||||
\T\addcontentsline{toc}{chapter}{\protect\numberline{\thechapter}{Bibliography}}
|
||||
|
||||
\bibitem{POSIX}
|
||||
Information technology -- Portable Operating System Interface (POSIX).
|
||||
\newblock ISO/IEC 9945-1 ANSI/IEEE Std 1003.1.
|
||||
\newblock 2nd Ed., 1996.
|
||||
|
||||
\bibitem{Clinger-Rees:Macros}
|
||||
William Clinger and Jonathan~Rees.
|
||||
\newblock Macros that work.
|
||||
\newblock {\em Principles of Programming Languages}, January 1991.
|
||||
|
||||
\bibitem{Clinger-Rees:R4RS}
|
||||
William Clinger and Jonathan~Rees (editors).
|
||||
\newblock Revised${}^4$ report on the algorithmic language {S}cheme.
|
||||
\newblock {\em LISP Pointers} IV(3):1--55, July-September 1991.
|
||||
|
||||
\bibitem{Curtis-Rauen:Modules}
|
||||
Pavel Curtis and James Rauen.
|
||||
\newblock A module system for Scheme.
|
||||
\newblock {\em ACM Conference on Lisp and Functional Programming,}
|
||||
pages 13--19, 1990.
|
||||
|
||||
\bibitem{Kelsey-Rees:Scheme48}
|
||||
Richard~Kelsey and Jonathan~Rees.
|
||||
\newblock A Tractable {Scheme} Implementation.
|
||||
\newblock {\em Lisp and Symbolic Computation} 7:315--335 1994.
|
||||
|
||||
\bibitem{R5RS}
|
||||
Richard Kelsey, Will Clinger, Jonathan Rees (editors).
|
||||
\newblock Revised$^5$ Report on the Algorithmic Language Scheme.
|
||||
\newblock {\em Higher-Order and Symbolic Computation,} Vol. 11, No. 1,
|
||||
September, 1998.
|
||||
\newblock and {\em ACM SIGPLAN Notices}, Vol. 33, No. 9, October, 1998.
|
||||
|
||||
\bibitem{MacQueen:Modules}
|
||||
David MacQueen.
|
||||
\newblock Modules for Standard ML.
|
||||
\newblock {\em ACM Conference on Lisp and Functional Programming,}
|
||||
1984.
|
||||
|
||||
\bibitem{Rees-Donald:Program}
|
||||
Jonathan Rees and Bruce Donald.
|
||||
\newblock Program mobile robots in Scheme.
|
||||
\newblock {\em International Conference on Robotics and
|
||||
Automation,} IEEE, 1992.
|
||||
|
||||
\bibitem{Sheldon-Gifford:Static}
|
||||
Mark A.~Sheldon and David K.~Gifford.
|
||||
\newblock Static dependent types for first-class modules.
|
||||
\newblock {\em ACM Conference on Lisp and Functional Programming,}
|
||||
pages 20--29, 1990.
|
||||
|
||||
\bibitem{Shivers:Scsh-manual}
|
||||
Olin Shivers and Brian D.~Calrstrom.
|
||||
\newblock Scsh Reference Manual, scsh release 0.4.
|
||||
\newblock MIT Laboratory for Computer Science
|
||||
\newblock Also available at URL http://swissnet.ai.mit.edu/scsh/.
|
||||
|
||||
\bibitem{Shivers:Scsh96}
|
||||
Olin Shivers.
|
||||
\newblock A universal scripting framework,
|
||||
or Lambda: the ultimate ``little language''.
|
||||
\newblock {\em Concurrency and Parallelism, Programming, Networking, and
|
||||
Security,} pages 254--265, Springer 1996.
|
||||
\newblock Joxan Jaffar and Roland H.~C.~Yap, editors.
|
||||
|
||||
\end{thebibliography}
|
||||
|
|
@ -0,0 +1,617 @@
|
|||
\chapter{Command processor}
|
||||
\label{chapter:command-processor}
|
||||
|
||||
This chapter details Scheme~48's command processor, which incorporates
|
||||
both a read-eval-print loop and an interactive debugger.
|
||||
At the \code{>} prompt, you can type either a Scheme form
|
||||
(expression or definition) or a command beginning with a comma.
|
||||
In
|
||||
\link*{inspection mode}[inspection mode (see section~\Ref)]{inspector}
|
||||
the prompt changes to \code{:} and commands
|
||||
no longer need to be preceded by a comma; input beginning with
|
||||
a letter or digit is assumed to be a command, not an expression.
|
||||
In inspection mode the command processor prints out a
|
||||
menu of selectable components for the current object of interest.
|
||||
|
||||
\section{Current focus value and {\tt \#\#}}
|
||||
|
||||
The command processor keeps track of a current {\em focus value}.
|
||||
This value is normally the last value returned by a command.
|
||||
If a command returns multiple values the focus object is a list of the
|
||||
values.
|
||||
The focus value is not changed if a command returns no values or
|
||||
a distinguished `unspecific' value.
|
||||
Examples of forms that return this unspecific value are definitions,
|
||||
uses of \code{set!}, and \code{(if \#f 0)}.
|
||||
It prints as \code{\#\{Unspecific\}}.
|
||||
|
||||
The reader used by the command processor reads \code{\#\#} as a special
|
||||
expression that evaluates to the current focus object.
|
||||
\begin{example}
|
||||
> (list 'a 'b)
|
||||
'(a b)
|
||||
> (car ##)
|
||||
'a
|
||||
> (symbol->string ##)
|
||||
"a"
|
||||
> (if #f 0)
|
||||
#\{Unspecific\}
|
||||
> ##
|
||||
"a"
|
||||
>
|
||||
\end{example}
|
||||
|
||||
\section{Command levels}
|
||||
|
||||
If an error, keyboard interrupt, or other breakpoint occurs, or the
|
||||
\code{,push} command is used, the command
|
||||
processor invokes a recursive copy of itself, preserving the dynamic state of
|
||||
the program when the breakpoint occured.
|
||||
The recursive invocation creates a new {\em command level}.
|
||||
The command levels form a stack with the current level at the top.
|
||||
The command prompt indicates the number of stopped levels below the
|
||||
current one: \code{>} or \code{:} for the
|
||||
base level and \code{\cvar{n}>} or \code{\cvar{n}:} for all other levels,
|
||||
where \cvar{n} is the command-level nesting depth.
|
||||
The \code{auto-levels} switch
|
||||
described below can be used to disable the automatic pushing of new levels.
|
||||
|
||||
The command processor's evaluation package and the value of the
|
||||
\code{inspect-focus-value} switch are local to each command level.
|
||||
They are preserved when a new level is pushed and restored when
|
||||
it is discarded.
|
||||
The settings of all other switches are shared by all command levels.
|
||||
|
||||
\begin{description}
|
||||
\item $\langle{}$eof$\rangle{}$\\
|
||||
Discards the current command level and resumes running the level down.
|
||||
$\langle{}$eof$\rangle{}$ is usually
|
||||
control-\code{D} at a Unix shell or control-\code{C} control-\code{D} using
|
||||
the Emacs \code{cmuscheme48} library.
|
||||
|
||||
\item \code{,pop}\\
|
||||
The same as $\langle{}$eof$\rangle{}$.
|
||||
|
||||
\item \code{,proceed [\cvar{exp} \ldots}]\\
|
||||
Proceed after an interrupt or error, resuming the next command
|
||||
level down, delivering the values of \cvar{exp~\ldots} to the continuation.
|
||||
Interrupt continuations discard any returned values.
|
||||
\code{,Pop} and \code{,proceed} have the same effect after an interrupt
|
||||
but behave differently after errors.
|
||||
\code{,Proceed} restarts the erroneous computation from the point where the
|
||||
error occurred (although not all errors are proceedable) while
|
||||
\code{,pop} (and $\langle{}$eof$\rangle{}$) discards it and prompts for
|
||||
a new command.
|
||||
|
||||
\item \code{,push}\\
|
||||
Pushes a new command level on above the current one.
|
||||
This is useful if the \code{auto-levels} switch has been used
|
||||
to disable the automatic pushing of new levels for errors and interrupts.
|
||||
|
||||
\item \code{,reset [\cvar{number}]}\\
|
||||
Pops down to a given level and restarts that level.
|
||||
\cvar{Number} defaults to zero, \code{,reset} restarts the command
|
||||
processor, discarding all existing levels.
|
||||
|
||||
\end{description}
|
||||
|
||||
Whenever moving to an existing level, either by sending
|
||||
an $\langle{}$eof$\rangle{}$
|
||||
or by using \code{,reset} or the other commands listed above,
|
||||
the command processor runs all of the \code{dynamic-wind} ``after'' thunks
|
||||
belonging to stopped computations on the discarded level(s).
|
||||
|
||||
\section{Logistical commands}
|
||||
\begin{description}
|
||||
\item \code{,load \cvar{filename \ldots}}\\
|
||||
Loads the named Scheme source file(s).
|
||||
Easier to type than \code{(load "\cvar{filename}")} because you don't have to
|
||||
shift to type the parentheses or quote marks. Also, it works in
|
||||
any package, unlike \code{(load "\cvar{filename}")}, which will work only
|
||||
work in packages in which the variable \code{load} is defined appropriately.
|
||||
|
||||
\item \code{,exit [\cvar{exp}]}
|
||||
Exits back out to shell (or executive or whatever invoked Scheme~48
|
||||
in the first place).
|
||||
\cvar{Exp} should evaluate to an integer. The
|
||||
integer is returned to the calling program.
|
||||
The default value of \cvar{exp} is zero, which, on Unix,
|
||||
is generally interpreted as success.
|
||||
\end{description}
|
||||
|
||||
\section{Module commands}
|
||||
\label{module-command-guide}
|
||||
|
||||
There are many commands related to modules.
|
||||
Only the most commonly used module commands are described here;
|
||||
documentation for the
|
||||
rest can be found in \link*{the module chapter}[section~\Ref]{module-commands}.
|
||||
There is also
|
||||
\link*{a brief description of modules, structures, and packages}
|
||||
[a brief description of modules, structures, and packages in section~\Ref]
|
||||
{module-guide} below.
|
||||
|
||||
\begin{description}
|
||||
\item \code{,open \cvar{structure \ldots}}\\
|
||||
Makes the bindings in the \cvar{structure}s visible in the current package.
|
||||
The packages associated with the \cvar{structure}s will be loaded if
|
||||
this has not already been done (the \code{ask-before-loading} switch
|
||||
can be used disable the automatic loading of packages).
|
||||
|
||||
\item \code{,config [\cvar{command}]}\\
|
||||
Executes \cvar{command} in the \code{config} package, which includes
|
||||
the module configuration language.
|
||||
For example, use
|
||||
\begin{example}
|
||||
,config ,load \cvar{filename}
|
||||
\end{example}
|
||||
to load a file containing module definitions.
|
||||
If no \cvar{command} is given, the \code{config} package becomes the
|
||||
execution package for future commands.
|
||||
|
||||
\item \code{,user [\cvar{command}]} \\
|
||||
This is similar to the {\tt ,config}. It
|
||||
moves to or executes a command in the user package (which is the
|
||||
default package when the \hack{} command processor starts).
|
||||
|
||||
\end{description}
|
||||
|
||||
\section{Debugging commands}
|
||||
\label{debug-commands}
|
||||
|
||||
\begin{description}
|
||||
\item \code{,preview}\\
|
||||
Somewhat like a backtrace, but because of tail recursion you see
|
||||
less than you might in debuggers for some other languages.
|
||||
The stack to display is chosen as follows:
|
||||
\begin{enumerate}
|
||||
\item If the current focus object is a continuation or a thread,
|
||||
then that continuation or thread's stack is displayed.
|
||||
\item Otherwise, if the current command level was initiated because of
|
||||
a breakpoint in the next level down, then the stack at that
|
||||
breakpoint is displayed.
|
||||
\item Otherwise, there is no stack to display and a message is printed
|
||||
to that effect.
|
||||
\end{enumerate}
|
||||
One line is printed out for each continuation on the chosen stack,
|
||||
going from top to bottom.
|
||||
|
||||
\item \code{,run \cvar{exp}}\\
|
||||
Evaluate \cvar{exp}, printing the result(s) and making them
|
||||
(or a list of them, if \cvar{exp} returns multiple results)
|
||||
the new focus object.
|
||||
The \code{,run} command is useful when writing
|
||||
\link*{command programs}
|
||||
[command programs, which are described in section~\Ref{} below]
|
||||
{command-programs}.
|
||||
|
||||
\item \code{,trace \cvar{name} \ldots}\\
|
||||
Start tracing calls to the named procedure or procedures.
|
||||
With no arguments, displays all procedures currently traced.
|
||||
This affects the binding of \cvar{name}, not the behavior of the
|
||||
procedure that is its current value. \cvar{Name} is redefined
|
||||
to be a procedure that prints a message,
|
||||
calls the original value of \cvar{name}, prints another
|
||||
message, and finally passes along the value(s) returned by the
|
||||
original procedure.
|
||||
|
||||
\item \code{,untrace \cvar{name} \ldots}\\
|
||||
Stop tracing calls to the named procedure or procedures.
|
||||
With no argument, stop tracing all calls to all procedures.
|
||||
|
||||
\item \code{,condition}\\
|
||||
The \code{,condition} command displays the condition object
|
||||
describing the error or interrupt that initiated the current
|
||||
command level. The condition object becomes the current focus
|
||||
value. This is particularly useful in conjunction with
|
||||
the inspector. For example, if a procedure is passed the wrong number of
|
||||
arguments, do \code{,condition} followed by
|
||||
\code{,inspect} to inspect the
|
||||
procedure and its arguments.
|
||||
|
||||
\item \code{,bound?\ \cvar{name}}\\
|
||||
Display the binding of \cvar{name}, if there is one, and otherwise
|
||||
prints `\code{Not bound}'.
|
||||
|
||||
\item \code{,expand \cvar{form}}
|
||||
\T\vspace{-1em}
|
||||
\item \code{,expand-all \cvar{form}}\\
|
||||
Show macro expansion of \cvar{form}, if any.
|
||||
\code{,expand} performs a single macro expansion while
|
||||
\code{,expand-all} fully expands all macros in \cvar{form}.
|
||||
|
||||
\item \code{,where \cvar{procedure}}\\
|
||||
Display name of file containing \cvar{procedure}'s source code.
|
||||
\end{description}
|
||||
|
||||
\section{Switches}
|
||||
|
||||
There are a number of binary switches that control the behavior of the
|
||||
command processor.
|
||||
They can be set using the \code{,set} and \code{,unset} commands.
|
||||
|
||||
\begin{description}
|
||||
\item \code{,set \cvar{switch} [on | off | ?]}\\
|
||||
This sets the value of mode-switch \cvar{switch}.
|
||||
The second argument defaults to \code{on}.
|
||||
If the second argument is \code{?} the value of \cvar{switch} is
|
||||
is displayed and not changed.
|
||||
Doing \code{,set ?} will display a list of the switches and
|
||||
their current values.
|
||||
|
||||
\item \code{,unset \cvar{switch}}\\
|
||||
\code{,unset \cvar{switch}} is the same as
|
||||
\code{,set \cvar{switch} off}.
|
||||
\end{description}
|
||||
|
||||
The switches are as follows:
|
||||
\begin{description}
|
||||
\item \code{batch}\\
|
||||
In `batch mode' any error or interrupt that comes up will cause
|
||||
Scheme~48 to exit immediately with a non-zero exit status. Also,
|
||||
the command processor doesn't print prompts. Batch mode is
|
||||
off by default.
|
||||
|
||||
% JAR says: disable auto-levels by default??
|
||||
|
||||
\item \code{auto-levels}\\
|
||||
Enables or disables the automatic pushing of a new command level when
|
||||
an error, interrupt, or other breakpoint occurs.
|
||||
When enabled (the default), breakpoints push a new command level,
|
||||
and $\langle{}$eof$\rangle{}$ (see above)
|
||||
or \code{,reset} is required to return to top level. The effects of
|
||||
pushed command levels include:
|
||||
\begin{itemize}
|
||||
\item a longer prompt
|
||||
\item retention of the continuation in effect at the point of errors
|
||||
\item confusion among some newcomers
|
||||
\end{itemize}
|
||||
With \code{auto-levels} disabled one must issue a
|
||||
\code{,push} command immediately
|
||||
following an error in order to retain the error continuation for
|
||||
debugging purposes; otherwise the continuation is lost as soon as
|
||||
the focus object changes. If you don't know anything about the
|
||||
available debugging tools, then levels might as well be disabled.
|
||||
|
||||
\item \code{inspect-focus-value}\\
|
||||
Enable or disable `inspection' mode, which is used for inspecting
|
||||
data structures and continuations.
|
||||
\link*{Inspection mode is desribed below}
|
||||
[Inspection mode is described in section~\Ref]
|
||||
{inspector}.
|
||||
|
||||
\item \code{break-on-warnings}\\
|
||||
Enter a new command level when a warning is produced, just as
|
||||
when an error occurs. Normally warnings only result in a displayed
|
||||
message and the program does not stop executing.
|
||||
|
||||
\item \code{ask-before-loading} \\
|
||||
If on, the system will ask before loading modules that are arguments
|
||||
to the \code{,open} command. \code{Ask-before-loading} is off by
|
||||
default.
|
||||
\begin{example}
|
||||
> ,set ask-before-loading
|
||||
will ask before loading modules
|
||||
> ,open random
|
||||
Load structure random (y/n)? y
|
||||
>
|
||||
\end{example}
|
||||
|
||||
\item \code{load-noisily}\\
|
||||
When on, the system will print out the names of modules and files
|
||||
as they are loaded. \code{load-noisily} is off by default.
|
||||
\begin{example}
|
||||
> ,set load-noisily
|
||||
will notify when loading modules and files
|
||||
> ,open random
|
||||
[random /usr/local/lib/scheme48/big/random.scm]
|
||||
>
|
||||
\end{example}
|
||||
|
||||
\item \code{inline-values}\\
|
||||
This controls whether or not the compiler is allowed to substitute
|
||||
variables' values in-line.
|
||||
When \code{inline-values} mode is on,
|
||||
some Scheme procedures will be substituted in-line; when it is off,
|
||||
none will.
|
||||
\link*{The performance section}[Section~\Ref]{section:performance}
|
||||
has more information.
|
||||
|
||||
\end{description}
|
||||
|
||||
\section{Inspection mode}
|
||||
\label{inspector}
|
||||
|
||||
There is a data inspector available via the \code{,inspect} and
|
||||
\code{,debug} commands or by setting the \code{inspect-focus-value} switch.
|
||||
The inspector is particularly useful with procedures, continuations,
|
||||
and records.
|
||||
The command processor can be taken out of inspection mode by
|
||||
using the \code{q} command, by unsetting the \code{inspect-focus-value} switch,
|
||||
or by going to a command level where the \code{inspect-focus-value} is not
|
||||
set.
|
||||
When in inspection mode, input that begins with
|
||||
a letter or digit is read as a command, not as an expression.
|
||||
To see the value of a variable or number, do \code{(begin \cvar{exp})}
|
||||
or use the \code{,run \cvar{exp}} command.
|
||||
|
||||
In inspection mode the command processor prints out a
|
||||
menu of selectable components for the current focus object.
|
||||
To inspect a particular component, just type the corresponding number in
|
||||
the menu.
|
||||
That component becomes the new focus object.
|
||||
For example:
|
||||
\begin{example}
|
||||
> ,inspect '(a (b c) d)
|
||||
(a (b c) d)
|
||||
|
||||
[0] a
|
||||
[1] (b c)
|
||||
[2] d
|
||||
: 1
|
||||
(b c)
|
||||
|
||||
[0] b
|
||||
[1] c
|
||||
:
|
||||
\end{example}
|
||||
|
||||
When a new focus object is selected the previous one is pushed onto a
|
||||
stack.
|
||||
You can pop the stack, reverting to the previous object, with
|
||||
the \code{u} command, or use the \code{stack} command to move to
|
||||
an earlier object.
|
||||
|
||||
%\begin{description}
|
||||
%\item \code{stack}\\
|
||||
% Prints the current stack out as a menu.
|
||||
% Selecting an item pops all higher values off of the stack and
|
||||
% makes that item the current focus value.
|
||||
%\end{description}
|
||||
%
|
||||
|
||||
Commands useful when in inspection mode:
|
||||
\begin{itemize}
|
||||
\item\code{u} (up) pop object stack
|
||||
\item\code{m} (more) print more of a long menu
|
||||
\item\code{(\ldots)} evaluate a form and select result
|
||||
\item\code{q} quit
|
||||
\item\code{template} select a closure or continuation's template
|
||||
(Templates are the static components of procedures; these are found
|
||||
inside of procedures and continuations, and contain the quoted
|
||||
constants and top-level variables referred to by byte-compiled code.)
|
||||
\item\code{d} (down) move to the next continuation
|
||||
(current object must be a continuation)
|
||||
\item\code{menu} print the selection menu for the focus object
|
||||
\end{itemize}
|
||||
|
||||
Multiple selection commands (\code{u}, \code{d}, and menu indexes)
|
||||
may be put on a single line.
|
||||
|
||||
%\code{\#\#} is always the object currently being inspected.
|
||||
%After a \code{q}
|
||||
%command,
|
||||
%or an error in the inspector, \code{\#\#} is the last object that was being
|
||||
%inspected.
|
||||
|
||||
All ordinary commands are available when in inspection mode.
|
||||
Similarly, the inspection commands can be used when not in inspection
|
||||
mode.
|
||||
For example:
|
||||
\begin{example}
|
||||
> (list 'a '(b c) 'd)
|
||||
'(a (b c) d)
|
||||
> ,1
|
||||
'(b c)
|
||||
> ,menu
|
||||
[0] b
|
||||
[1] c
|
||||
>
|
||||
\end{example}
|
||||
|
||||
If the current command level was initiated because of
|
||||
a breakpoint in the next level down, then
|
||||
\code{,debug} will invoke the inspector on the
|
||||
continuation at the point of the error.
|
||||
The \code{u} and \code{d} (up and down)
|
||||
commands then make the inspected-value stack look like a conventional stack
|
||||
debugger, with continuations playing the role of stack frames. \code{D} goes
|
||||
to older or deeper continuations (frames), and \code{u} goes back up to more
|
||||
recent ones.
|
||||
|
||||
\section{Command programs}
|
||||
\label{command-programs}
|
||||
|
||||
The \code{exec} package contains procedures that are used
|
||||
to execute the command processor's commands.
|
||||
A command \code{,\cvar{foo}} is executed by applying the value of
|
||||
the identifier \cvar{foo} in the \code{exec} package to
|
||||
the (suitably parsed) command arguments.
|
||||
|
||||
\begin{description}
|
||||
\item \code{,exec [\cvar{command}]}\\
|
||||
Evaluate \cvar{command} in the \code{exec} package.
|
||||
For example, use
|
||||
\begin{example}
|
||||
,exec ,load \cvar{filename}
|
||||
\end{example}
|
||||
to load a file containing commands.
|
||||
If no \cvar{command} is given, the \code{exec} package becomes the
|
||||
execution package for future commands.
|
||||
\end{description}
|
||||
|
||||
The required argument types are as follows:
|
||||
\begin{itemize}
|
||||
\item filenames should be strings
|
||||
\item other names and identifiers should be symbols
|
||||
\item expressions should be s-expressions
|
||||
\item commands (as for \code{,config} and \code{,exec} itself)
|
||||
should be lists of the form
|
||||
\code{(\cvar{command-name} \cvar{argument} \cvar{...})}
|
||||
where \cvar{command-name} is a symbol.
|
||||
\end{itemize}
|
||||
|
||||
For example, the following two commands are equivalent:
|
||||
\begin{example}
|
||||
,config ,load my-file.scm
|
||||
|
||||
,exec (config '(load "my-file.scm"))
|
||||
\end{example}
|
||||
|
||||
The file \code{scheme/vm/load-vm.scm} in the source directory contains an
|
||||
example of an \code{exec} program.
|
||||
|
||||
\section{Building images}
|
||||
|
||||
\begin{description}
|
||||
\item \code{,dump \cvar{filename} [\cvar{identification}]}\\
|
||||
Writes the current heap out to a file, which can then be run using the
|
||||
virtual machine. The new image file includes the command processor.
|
||||
If present, \cvar{identification}
|
||||
should be a string (written with double quotes); this string will
|
||||
be part of the greeting message as the image starts up.
|
||||
|
||||
\item \code{,build \cvar{exp} \cvar{filename}}\\
|
||||
Like \code{,dump}, except that the image file contains the value of
|
||||
\cvar{exp}, which should be a procedure of one argument, instead of
|
||||
the command processor. When
|
||||
\cvar{filename} is resumed, that procedure will be invoked on the VM's
|
||||
\code{-a} arguments, which are passed as a list of strings. The
|
||||
procedure should return an integer which is
|
||||
returned to the program that invoked the VM. The command
|
||||
processor and debugging system are not included in the image
|
||||
(unless you go to some effort to preserve them, such as retaining
|
||||
a continuation).
|
||||
|
||||
Doing \code{,flush} before building an image will reduce the amount
|
||||
of debugging information in the image, making for a smaller
|
||||
image file, but if an error occurs, the error message may be less
|
||||
helpful. Doing \code{,flush source maps} before loading any programs
|
||||
used in the image will make it still smaller.
|
||||
See \link*{the description of \code{flush}}[section~\Ref]{resource-commands}
|
||||
for more information.
|
||||
|
||||
\end{description}
|
||||
|
||||
\section{Resource query and control}
|
||||
\label{resource-commands}.
|
||||
|
||||
\begin{description}
|
||||
\item \code{,time \cvar{exp}}\\
|
||||
Measure execution time.
|
||||
|
||||
\item \code{,collect}\\
|
||||
Invoke the garbage collector. Ordinarily this happens
|
||||
automatically, but the command tells how much space is available
|
||||
before and after the collection.
|
||||
|
||||
\item \code{,keep \cvar{kind}}
|
||||
\T\vspace{-1em}
|
||||
\item \code{,flush \cvar{kind}}\\
|
||||
These control the amount of debugging information retained after
|
||||
compiling procedures. This information can consume a fair amount
|
||||
of space. \cvar{kind} is one of the following:
|
||||
\begin{itemize}
|
||||
\item \code{maps} - environment maps (local variable names, for inspector)
|
||||
\item \code{source} - source code for continuations (displayed by inspector)
|
||||
\item \code{names} - procedure names (as displayed by \code{write} and in error
|
||||
messages)
|
||||
\item \code{files} - source file names
|
||||
\end{itemize}
|
||||
These commands refer to future compilations only, not to procedures
|
||||
that already exist. To have any effect, they must be done before
|
||||
programs are loaded. The default is to keep all four types.
|
||||
% JAR says: ,keep tabulate - puts debug data in a table that can be
|
||||
% independently flushed (how? -RK) or even written out and re-read later!
|
||||
% (how? -RK)
|
||||
|
||||
\item \code{,flush}\\
|
||||
The flush command with no argument deletes the database of names
|
||||
of initial procedures. Doing \code{,flush} before a \code{,build} or
|
||||
\code{,dump}
|
||||
will make the resulting image significantly smaller, but will
|
||||
compromise the information content of many error
|
||||
messages.
|
||||
\end{description}
|
||||
|
||||
\section{Threads}
|
||||
|
||||
Each command level has its own set of threads. These threads are suspended
|
||||
when a new level is entered and resumed when the owning level again becomes
|
||||
the current level.
|
||||
A thread that raises an error is not resumed unless
|
||||
explicitly restarted using the \code{,proceed} command.
|
||||
In addition to any threads spawned by the user, each level has a thread
|
||||
that runs the command processor on that level.
|
||||
A new command-processor thread is started if the current one
|
||||
dies or is terminated.
|
||||
When a command level is abandoned for a lower level, or when
|
||||
a level is restarted using \code{,reset}, all of the threads on that
|
||||
level are terminated and any \code{dynamic-wind} ``after'' thunks are run.
|
||||
|
||||
The following commands are useful when debugging multithreaded programs:
|
||||
\begin{description}
|
||||
\item \code{,resume [\cvar{number}]}\\
|
||||
Pops out to a given level and resumes running all threads at that level.
|
||||
\cvar{Number} defaults to zero.
|
||||
|
||||
\item \code{,threads}\\
|
||||
Invokes the inspector on a list of the threads running at the
|
||||
next lower command level.
|
||||
|
||||
\item \code{,exit-when-done [\cvar{exp}]}\\
|
||||
Waits until all user threads have completed and then
|
||||
exits back out to shell (or executive or whatever invoked Scheme~48
|
||||
in the first place).
|
||||
\cvar{Exp} should evaluate to an integer which is then
|
||||
returned to the calling program.
|
||||
% JAR says: interaction with ,build ?
|
||||
|
||||
%\item \code{,spawn \cvar{exp} [\cvar{name}]}\\
|
||||
% Starts a new thread running \cvar{exp} on next command level down.
|
||||
% The optional \cvar{name} is used for printing and debugging.
|
||||
%
|
||||
%\item \code{,suspend [\cvar{exp}]}
|
||||
%\T\vspace{-1em}
|
||||
%\item \code{,continue [\cvar{exp}]}
|
||||
%\T\vspace{-1em}
|
||||
%\item \code{,kill [\cvar{exp}]}\\
|
||||
% Suspend, unsuspend, and terminate a thread, respectively.
|
||||
% Suspended threads are not run until unsuspended, terminated
|
||||
% threads are never run again.
|
||||
% \cvar{Exp} should evaluate to a thread.
|
||||
% If \cvar{exp} is not present, the current focus object is used.
|
||||
%
|
||||
|
||||
% example of ,threads ,suspend ...
|
||||
\end{description}
|
||||
|
||||
\section{Quite obscure}
|
||||
|
||||
\begin{description}
|
||||
\item \code{,go \cvar{exp}}\\
|
||||
This is like \code{,exit \cvar{exp}} except that the evaluation of \cvar{exp}
|
||||
is tail-recursive with respect to the command processor. This
|
||||
means that the command processor itself can probably be GC'ed,
|
||||
should a garbage collection occur in the execution of \cvar{exp}.
|
||||
If an error occurs Scheme~48 will exit with a non-zero value.
|
||||
|
||||
\item \code{,translate \cvar{from} \cvar{to}}\\
|
||||
For \code{load} and the \code{,load} command
|
||||
(but not for \code{open-\{in|out\}put-file}), file
|
||||
names beginning with the string \cvar{from} will be changed so that the
|
||||
initial \cvar{from} is replaced by the string \cvar{to}. E.g.
|
||||
\begin{example}
|
||||
\code{,translate /usr/gjc/ /zu/gjc/}
|
||||
\end{example}
|
||||
will cause \code{(load "/usr/gjc/foo.scm")} to have the same effect as
|
||||
\code{(load "/zu/gjc/foo.scm")}.
|
||||
% JAR says: Useful with the module system! "virtual directories"
|
||||
|
||||
\item \code{,from-file \cvar{filename} \cvar{form} \ldots\ ,end}\\
|
||||
This is used by the \code{cmuscheme48} Emacs library to indicate the file
|
||||
from which the \cvar{form}s came. \cvar{Filename} is then used by the
|
||||
command processor to determine the package in which the \cvar{form}s
|
||||
are to be evaluated.
|
||||
\end{description}
|
||||
|
||||
|
|
@ -1,69 +1,53 @@
|
|||
\documentclass{article}
|
||||
\usepackage{hyperlatex}
|
||||
|
||||
\include{proto}
|
||||
%\htmltitle{Mixing Scheme 48 and C}
|
||||
%\htmladdress{\begin{rawhtml}<a href="http://www-pu.informatik.uni-tuebingen.de/users/sperber/">Mike
|
||||
% Sperber</a>, <a href="http://www.neci.nj.nec.com/homepages/kelsey/">Richard Kelsey</a>\end{rawhtml}}
|
||||
%
|
||||
%\title{Using C code with Scheme 48}
|
||||
%\author{Mike Sperber\\\texttt{\small sperber@informatik.uni-tuebingen.de}\\
|
||||
% Richard Kelsey\\\texttt{\small kelsey@research.nj.nec.com}
|
||||
% }
|
||||
%
|
||||
%\makeindex
|
||||
%
|
||||
%\begin{document}
|
||||
%
|
||||
%\maketitle
|
||||
%
|
||||
%\begin{abstract}
|
||||
|
||||
% Make each section be a separate HTML file.
|
||||
\setcounter{htmldepth}{1}
|
||||
% What is all this, you ask?
|
||||
% We provide three different titles:
|
||||
% - for the table of contents, which has the extra authors
|
||||
% - for links, which doesn't
|
||||
% - for the page, which does, but on two lines
|
||||
% The html \chapter command takes a second optional argument, which is the
|
||||
% title to use in the ToC.
|
||||
|
||||
\W\newcommand{\langle}{<}
|
||||
\W\newcommand{\rangle}{>}
|
||||
\texonly{
|
||||
\chapter[Mixing Scheme 48 and C {\rm\ \ Mike Sperber and Richard Kelsey}]
|
||||
{Mixing Scheme 48 and C \\ {\large Mike Sperber and Richard Kelsey}}
|
||||
}
|
||||
|
||||
\newcommand{\meta}[1]{{\noindent\mbox{\textrm{$\langle$#1$\rangle$}}}}
|
||||
\newcommand{\hyper}[1]{\meta{#1}}
|
||||
\newcommand{\hyperi}[1]{\hyper{#1$_1$}}
|
||||
\newcommand{\hyperii}[1]{\hyper{#1$_2$}}
|
||||
\newcommand{\hyperj}[1]{\hyper{#1$_i$}}
|
||||
\newcommand{\hypern}[1]{\hyper{#1$_n$}}
|
||||
\renewcommand{\var}[1]{\noindent\mbox{\textit{#1}}}
|
||||
\newcommand{\vari}[1]{\var{#1$_1$}}
|
||||
\newcommand{\varii}[1]{\var{#1$_2$}}
|
||||
\newcommand{\variii}[1]{\var{#1$_3$}}
|
||||
\newcommand{\variv}[1]{\var{#1$_4$}}
|
||||
\newcommand{\varj}[1]{\var{#1$_j$}}
|
||||
\newcommand{\varn}[1]{\var{#1$_n$}}
|
||||
\htmlonly{
|
||||
\chapter[Mixing Scheme 48 and C]%
|
||||
[Mixing Scheme 48 and C %
|
||||
\htmlsym{nbsp}\htmlsym{nbsp} {\it Mike Sperber and Richard Kelsey}]
|
||||
{Mixing Scheme 48 and C \\ {\large Mike Sperber and Richard Kelsey}}
|
||||
}
|
||||
\label{external-chapter}
|
||||
|
||||
\W\newcommand{\frenchspacing}{}
|
||||
\W\newcommand{\textnormal}[1]{#1}
|
||||
|
||||
\newcommand{\defining}[1]{{\emph{#1}}}
|
||||
|
||||
\newcommand{\exprtype}{syntax}
|
||||
|
||||
\W\newcommand{\unskip}{}
|
||||
\W\newcommand{\textrm}[1]{#1}
|
||||
|
||||
\newcommand{\dotsfoo}{\ldots\texonly{\thinspace}}
|
||||
|
||||
\htmltitle{Mixing Scheme 48 and C}
|
||||
\htmladdress{\begin{rawhtml}<a href="http://www-pu.informatik.uni-tuebingen.de/users/sperber/">Mike
|
||||
Sperber</a>, <a href="http://www.neci.nj.nec.com/homepages/kelsey/">Richard Kelsey</a>\end{rawhtml}}
|
||||
|
||||
\title{Using C code with Scheme 48}
|
||||
\author{Mike Sperber\\\texttt{\small sperber@informatik.uni-tuebingen.de}\\
|
||||
Richard Kelsey\\\texttt{\small kelsey@research.nj.nec.com}
|
||||
}
|
||||
|
||||
\makeindex
|
||||
|
||||
\begin{document}
|
||||
|
||||
\maketitle
|
||||
|
||||
\begin{abstract}
|
||||
This document describes an interface for calling C functions
|
||||
This chapter describes an interface for calling C functions
|
||||
from Scheme, calling Scheme functions from C, and allocating
|
||||
storage in the Scheme heap.
|
||||
These facilities are designed to link
|
||||
existing C libraries into Scheme~48 in order to use them from Scheme.
|
||||
To this end, Scheme~48 manages stub functions in C that
|
||||
storage in the Scheme heap..
|
||||
Scheme~48 manages stub functions in C that
|
||||
negotiate between the calling conventions of Scheme and C and the
|
||||
memory allocation policies of both worlds.
|
||||
No stub generator is available yet, but writing them is a straightforward task.
|
||||
No stub generator is available yet, but writing stubs is a straightforward task.
|
||||
|
||||
\end{abstract}
|
||||
%\end{abstract}
|
||||
|
||||
\section{Available Facilities}
|
||||
\section{Available facilities}
|
||||
\label{sec:facilities}
|
||||
|
||||
The following facilities are available for interfacing between
|
||||
|
|
@ -84,11 +68,11 @@ The following facilities are available for interfacing between
|
|||
bindings for access by C code.
|
||||
\end{itemize}
|
||||
%
|
||||
This document has three parts: the first describes how bindings are
|
||||
moved from Scheme to C and vice versa, the second tells how to call
|
||||
C functions from Scheme, and the third covers the C interface
|
||||
to Scheme objects, including calling Scheme procedures, using the
|
||||
Scheme heap, and so forth.
|
||||
%This section has three parts: the first describes how bindings are
|
||||
% moved from Scheme to C and vice versa, the second tells how to call
|
||||
% C functions from Scheme, and the third covers the C interface
|
||||
% to Scheme objects, including calling Scheme procedures, using the
|
||||
% Scheme heap, and so forth.
|
||||
|
||||
\subsection{Scheme structures}
|
||||
|
||||
|
|
@ -123,6 +107,20 @@ All of the C functions and macros described have prototypes or definitions
|
|||
in the file \code{c/scheme48.h}.
|
||||
The C type for Scheme values is defined there to be \code{s48\_value}.
|
||||
|
||||
\subsection{Garbage collection}
|
||||
|
||||
Scheme~48 uses a copying garbage collector.
|
||||
The collector must be able to locate all references
|
||||
to objects allocated in the Scheme~48 heap in order to ensure that
|
||||
storage is not reclaimed prematurely and to update references to objects
|
||||
moved by the collector.
|
||||
The garbage collector may run whenever an object is allocated in the heap.
|
||||
C variables whose values are Scheme~48 objects and which are live across
|
||||
heap allocation calls need to be registered with
|
||||
the
|
||||
\link{garbage collector}
|
||||
[garbage collector. See section~\Ref{} for more information]{gc}.
|
||||
|
||||
\section{Shared bindings}
|
||||
\label{sec:shared-bindings}
|
||||
|
||||
|
|
@ -158,7 +156,7 @@ The C macro \code{S48\_SHARED\_BINDING\_REF} dereferences a shared binding,
|
|||
\subsection{Exporting C values to Scheme}
|
||||
|
||||
\begin{protos}
|
||||
\cproto{void s48\_define\_exported\_binding(char *name, s48\_value value)}
|
||||
\cproto{void s48\_define\_exported\_binding(char *name, s48\_value v)}
|
||||
\end{protos}
|
||||
|
||||
\begin{protos}
|
||||
|
|
@ -172,11 +170,12 @@ Again, if a name is looked up before it has been defined, a new binding is
|
|||
created for it.
|
||||
|
||||
The common case of exporting a C function to Scheme can be done using
|
||||
the macro \code{S48\_EXPORT\_FUNCTION(\emph{name})}.
|
||||
the macro \code{S48\_EXPORT\_FUNCTION(\cvar{name})}.
|
||||
This expands into
|
||||
|
||||
\code{s48\_define\_exported\_binding("\cvar{name}", %
|
||||
s48\_enter\_pointer(\cvar{name}))}
|
||||
\begin{example}
|
||||
s48\_define\_exported\_binding("\cvar{name}",
|
||||
s48\_enter\_pointer(\cvar{name}))
|
||||
\end{example}
|
||||
|
||||
\noindent which boxes the function into a Scheme byte vector and then
|
||||
exports it.
|
||||
|
|
@ -186,7 +185,7 @@ Note that \code{s48\_enter\_pointer} allocates space in the Scheme heap
|
|||
|
||||
\begin{protos}
|
||||
\syntaxprotonoresult{import-definition}{ \cvar{name}}
|
||||
\syntaxprotonoresult{import-definition}{ \cvar{name c-name}}
|
||||
\syntaxprotonoresultnoindex{import-definition}{ \cvar{name c-name}}
|
||||
\end{protos}
|
||||
These macros simplify importing definitions from C to Scheme.
|
||||
They expand into
|
||||
|
|
@ -233,10 +232,10 @@ The following C macros correspond to the Scheme functions above.
|
|||
\cproto{int\ \ \ \ \ \ \ S48\_SHARED\_BINDING\_P(x)}
|
||||
\cproto{int\ \ \ \ \ \ \ S48\_SHARED\_BINDING\_IS\_IMPORT\_P(s48\_value s\_b)}
|
||||
\cproto{s48\_value S48\_SHARED\_BINDING\_NAME(s48\_value s\_b)}
|
||||
\cproto{void\ \ \ \ \ \ S48\_SHARED\_BINDING\_SET(s48\_value s\_b, s48\_value value)}
|
||||
\cproto{void\ \ \ \ \ \ S48\_SHARED\_BINDING\_SET(s48\_value s\_b, s48\_value v)}
|
||||
\end{protos}
|
||||
|
||||
\section{Calling C Functions from Scheme}
|
||||
\section{Calling C functions from Scheme}
|
||||
\label{sec:external-call}
|
||||
|
||||
There are three different ways to call C functions from Scheme, depending on
|
||||
|
|
@ -264,6 +263,8 @@ The \cvar{name} argument is used only for printing error messages.
|
|||
|
||||
For all of these, the C function is passed the \cvar{arg$_i$} values
|
||||
and the value returned is that returned by C procedure.
|
||||
No automatic representation conversion occurs for either arguments or
|
||||
return values.
|
||||
Up to twelve arguments may be passed.
|
||||
There is no method supplied for returning multiple values to
|
||||
Scheme from C (or vice versa) (mainly because C does not have multiple return
|
||||
|
|
@ -276,7 +277,7 @@ Keyboard interrupts that occur during a call to a C function are ignored
|
|||
\begin{protos}
|
||||
\syntaxprotonoresult{import-lambda-definition}
|
||||
{ \cvar{name} (\cvar{formal} \ldots)}
|
||||
\syntaxprotonoresult{import-lambda-definition}
|
||||
\syntaxprotonoresultnoindex{import-lambda-definition}
|
||||
{ \cvar{name} (\cvar{formal} \ldots)\ \cvar{c-name}}
|
||||
\end{protos}
|
||||
\noindent{}These macros simplify importing functions from C.
|
||||
|
|
@ -296,17 +297,17 @@ These expand into
|
|||
If \cvar{c-name} is not supplied, it is derived from \cvar{name} by converting
|
||||
all letters to lowercase and replacing `\code{-}' with `\code{\_}'.
|
||||
|
||||
\section{Adding external modules to the \code{Makefile}}
|
||||
\section{Adding external modules to the {\tt Makefile}}
|
||||
\label{sec:external-modules}
|
||||
|
||||
Getting access to C bindings from Scheme requires that the C code be
|
||||
compiled an linked in with the Scheme~48 virtual machine and that the
|
||||
relevent shared-bindings be created.
|
||||
compiled and linked in with the Scheme~48 virtual machine and that the
|
||||
relevant shared bindings be created.
|
||||
The Scheme~48 makefile has rules for compiling and linking external code
|
||||
and for specifying initialization functions that should be called on
|
||||
startup.
|
||||
There are three Makefile variables that control which external modules are
|
||||
included in the executable for the virutal machine (\code{scheme48vm}).
|
||||
There are three \code{Makefile} variables that control which external modules are
|
||||
included in the executable for the virtual machine (\code{scheme48vm}).
|
||||
\code{EXTERNAL\_OBJECTS} lists the object files to be included in
|
||||
\code{scheme48vm},
|
||||
\code{EXTERNAL\_FLAGS} is a list of \code{ld} flags to be used when
|
||||
|
|
@ -318,7 +319,7 @@ The procedures listed in \code{EXTERNAL\_INITIALIZERS} should take no
|
|||
After changing the definitions of any of these variables you should
|
||||
do \code{make scheme48vm} to rebuild the virtual machine.
|
||||
|
||||
\section{Dynamic Loading}
|
||||
\section{Dynamic loading}
|
||||
\label{dynamic-externals}
|
||||
|
||||
External code can be loaded into a running Scheme~48 process
|
||||
|
|
@ -369,9 +370,9 @@ The following two functions can be used to update the values of
|
|||
\proto{lookup-all-externals}{}{boolean}
|
||||
\end{protos}
|
||||
\noindent
|
||||
\code{Lookup-external} updates the value of \cvar{external} by looking its
|
||||
name in the current process, returning \code{\#t} if it is bound and \code{\#f}
|
||||
if it is not.
|
||||
\code{Lookup-external} updates the value of \cvar{external} by looking up its
|
||||
name in the current process, returning \code{\#t} if the name is bound
|
||||
and \code{\#f} if it is not.
|
||||
\code{Lookup-all-externals} calls \code{lookup-external} on all extant
|
||||
externals, returning \code{\#f} any are unbound.
|
||||
|
||||
|
|
@ -393,7 +394,9 @@ We recommend that a dynamically-loaded file contain a single initialization
|
|||
|
||||
\section{Compatibility}
|
||||
|
||||
Scheme~48's old \code{external-call} function is still available in the structure
|
||||
% JAR says: give version number (I would if I knew what it was -RK)
|
||||
Scheme~48's old \code{external-call} function is still available in the
|
||||
structure
|
||||
\code{externals}, which now also includes \code{external-name} and
|
||||
\code{external-value}.
|
||||
The old \code{scheme48.h} file has been renamed \code{old-scheme48.h}.
|
||||
|
|
@ -402,9 +405,7 @@ The old \code{scheme48.h} file has been renamed \code{old-scheme48.h}.
|
|||
\label{sec:scheme-data}
|
||||
|
||||
The C header file \code{scheme48.h} provides
|
||||
access to Scheme~48 data structures
|
||||
(for compatibility, the old \code{scheme48.h} file is available
|
||||
as \code{old-scheme48.h}).
|
||||
access to Scheme~48 data structures.
|
||||
The type \code{s48\_value} is used for Scheme values.
|
||||
When the type of a value is known, such as the integer returned
|
||||
by \code{vector-length} or the boolean returned by \code{pair?},
|
||||
|
|
@ -417,49 +418,74 @@ Predicates return \code{1} for true and \code{0} for false.
|
|||
|
||||
The following macros denote Scheme constants:
|
||||
%
|
||||
\begin{description}
|
||||
\item[\code{S48\_FALSE}] is \verb|#f|.
|
||||
\item[\code{S48\_TRUE}] is \verb|#t|.
|
||||
\item[\code{S48\_NULL}] is the empty list.
|
||||
\item[\code{S48\_UNSPECIFIC}] is a value used for functions which have no
|
||||
\begin{itemize}
|
||||
\item \code{S48\_FALSE} is \verb|#f|.
|
||||
\item \code{S48\_TRUE} is \verb|#t|.
|
||||
\item \code{S48\_NULL} is the empty list.
|
||||
\item \code{S48\_UNSPECIFIC} is a value used for functions which have no
|
||||
meaningful return value
|
||||
(in Scheme this value returned by the nullary procedure \code{unspecific}
|
||||
(in Scheme~48 this value returned by the nullary procedure \code{unspecific}
|
||||
in the structure \code{util}).
|
||||
\item[\code{S48\_EOF}] is the end-of-file object
|
||||
(in Scheme this value is returned by the nullary procedure \code{eof-object}
|
||||
\item \code{S48\_EOF} is the end-of-file object
|
||||
(in Scheme~48 this value is returned by the nullary procedure \code{eof-object}
|
||||
in the structure \code{i/o-internal}).
|
||||
\end{description}
|
||||
\end{itemize}
|
||||
|
||||
\subsection{Converting values}
|
||||
|
||||
The following functions convert values between Scheme and C
|
||||
The following macros and functions convert values between Scheme and C
|
||||
representations.
|
||||
The `extract' ones convert from Scheme to C and the `enter's go the other
|
||||
way.
|
||||
|
||||
\begin{protos}
|
||||
\cproto{int \ \ \ \ \ \ S48\_EXTRACT\_BOOLEAN(s48\_value)}
|
||||
\cproto{unsigned char s48\_extract\_char(s48\_value)}
|
||||
\cproto{char * \ \ \ s48\_extract\_string(s48\_value)}
|
||||
\cproto{char * \ \ \ s48\_extract\_byte\_vector(s48\_value)}
|
||||
\cproto{long \ \ \ \ \ s48\_extract\_integer(s48\_value)}
|
||||
\cproto{double \ \ \ s48\_extract\_double(s48\_value)}
|
||||
\cproto{s48\_value S48\_ENTER\_BOOLEAN(int)}
|
||||
\cproto{s48\_value s48\_enter\_char(unsigned char)}
|
||||
\cgcproto{s48\_value s48\_enter\_string(char *)}
|
||||
\cgcproto{s48\_value s48\_enter\_byte\_vector(char *, long)}
|
||||
\cgcproto{s48\_value s48\_enter\_integer(long)}
|
||||
\cgcproto{s48\_value s48\_enter\_double(double)}
|
||||
\end{protos}
|
||||
|
||||
\noindent{}The value returned by \code{s48\_extract\_string} points to the actual
|
||||
storage used by the string; it is valid only until the next
|
||||
\noindent{}\code{S48\_EXTRACT\_BOOLEAN} is false if its argument is
|
||||
\code{\#f} and true otherwise.
|
||||
\code{S48\_ENTER\_BOOLEAN} is \code{\#f} if its argument is zero
|
||||
and \code{\#t} otherwise.
|
||||
|
||||
\code{s48\_extract\_string} and \code{s48\_extract\_byte\_vector} return
|
||||
pointers to the actual
|
||||
storage used by the string or byte vector.
|
||||
These pointers are valid only until the next
|
||||
\link{garbage collection}[; see Section~\ref{gc}]{gc}.
|
||||
|
||||
The second argument to \code{s48\_enter\_byte\_vector} is the length of
|
||||
byte vector.
|
||||
|
||||
\code{s48\_enter\_integer()} needs to allocate storage when
|
||||
its argument is too large to fit in a Scheme~48 fixnum.
|
||||
In cases where the number is known to fit within a fixnum (currently 30 bits
|
||||
including the sign), the following procedures can be used.
|
||||
These have the disadvantage of only having a limited range, but
|
||||
the advantage of never causing a garbage collection.
|
||||
\code{S48\_FIXNUM\_P} is a macro that true if its argument is a fixnum
|
||||
and false otherwise.
|
||||
|
||||
\begin{protos}
|
||||
\cproto{int \ \ \ \ \ \ S48\_TRUE\_P(s48\_value)}
|
||||
\cproto{int \ \ \ \ \ \ S48\_FALSE\_P(s48\_value)}
|
||||
\end{protos}
|
||||
|
||||
\noindent \code{S48\_TRUE\_P} is true if its argument is \code{S48\_TRUE}
|
||||
and \code{S48\_FALSE\_P} is true if its argument is \code{S48\_FALSE}.
|
||||
|
||||
\begin{protos}
|
||||
\cproto{int \ \ \ \ \ \ S48\_FIXNUM\_P(s48\_value)}
|
||||
\cproto{long \ \ \ \ \ s48\_extract\_fixnum(s48\_value)}
|
||||
\cproto{s48\_value s48\_enter\_fixnum(long)}
|
||||
\cproto{long \ \ \ \ \ S48\_MAX\_FIXNUM\_VALUE}
|
||||
|
|
@ -475,12 +501,11 @@ These have the disadvantage of only having a limited range, but
|
|||
|
||||
The following macros and procedures are C versions of Scheme procedures.
|
||||
The names were derived by replacing `\code{-}' with `\code{\_}',
|
||||
`\code{?}' with `\code{p}', and dropping `\code{!}.
|
||||
`\code{?}' with `\code{\_P}', and dropping `\code{!}.
|
||||
|
||||
\begin{protos}
|
||||
\cproto{int \ \ \ \ \ \ S48\_EQ\_P(s48\_value)}
|
||||
\cproto{int \ \ \ \ \ \ S48\_EQ\_P(s48\_value, s48\_VALUE)}
|
||||
\cproto{int \ \ \ \ \ \ S48\_CHAR\_P(s48\_value)}
|
||||
\cproto{int \ \ \ \ \ \ S48\_INTEGER\_P(s48\_value)}
|
||||
\end{protos}
|
||||
\begin{protos}
|
||||
\cproto{int \ \ \ \ \ \ S48\_PAIR\_P(s48\_value)}
|
||||
|
|
@ -524,11 +549,11 @@ External code that has been called from Scheme can call back to Scheme
|
|||
procedures using the following function.
|
||||
|
||||
\begin{protos}
|
||||
\cproto{scheme\_value s48\_call\_scheme(s48\_value proc, long nargs, \ldots)}
|
||||
\cproto{scheme\_value s48\_call\_scheme(s48\_value p, long nargs, \ldots)}
|
||||
\end{protos}
|
||||
\noindent{}This calls the Scheme procedure \code{proc} on \code{nargs}
|
||||
\noindent{}This calls the Scheme procedure \code{p} on \code{nargs}
|
||||
arguments, which are passed as additional arguments to \code{s48\_call\_scheme}.
|
||||
There may be at most ten arguments.
|
||||
There may be at most twelve arguments.
|
||||
The value returned by the Scheme procedure is returned by the C procedure.
|
||||
Invoking any Scheme procedure may potentially cause a garbage collection.
|
||||
|
||||
|
|
@ -561,15 +586,15 @@ For example, suppose thread \code{t0} calls a C procedure which calls back
|
|||
At this point both \code{t0} and \code{t1} have active calls to C on the
|
||||
C stack, with \code{t1}'s C frame above \code{t0}'s.
|
||||
If thread \code{t0} attempts to return from Scheme to C it will block,
|
||||
as its frame is not accessable.
|
||||
as its frame is not accessible.
|
||||
Once \code{t1} has returned to C and from there to Scheme, \code{t0} will
|
||||
be able to resume.
|
||||
The return to Scheme is required because context switches can only occur while
|
||||
C code is running.
|
||||
Scheme code is running.
|
||||
\code{T0} will also be able to resume if \code{t1} uses a continuation to
|
||||
throw past its call to C.
|
||||
|
||||
\section{Interacting with the Scheme Heap}
|
||||
\section{Interacting with the Scheme heap}
|
||||
\label{sec:heap-allocation}
|
||||
\label{gc}
|
||||
|
||||
|
|
@ -584,7 +609,7 @@ The garbage collector has no facility for updating pointers to the interiors
|
|||
\code{EXTRACT\_STRING}, will likely become invalid when a garbage collection
|
||||
occurs.
|
||||
|
||||
\subsection{Registering Objects with the GC}
|
||||
\subsection{Registering objects with the GC}
|
||||
\label{sec:gc-register}
|
||||
|
||||
A set of macros are used to manage the registration of local variables with the
|
||||
|
|
@ -598,13 +623,15 @@ A set of macros are used to manage the registration of local variables with the
|
|||
|
||||
\code{S48\_DECLARE\_GC\_PROTECT($n$)}, where $1\leq n\leq 9$, allocates
|
||||
storage for registering $n$ variables.
|
||||
At most one use of \code{S48\_DECLARE\_GC\_PROTECT} may occur in a block.
|
||||
% JAR says: what is a block? (How to describe it? -RK)
|
||||
At most one use of \code{S48\_DECLARE\_GC\_PROTECT} may occur in a
|
||||
block.
|
||||
\code{S48\_GC\_PROTECT\_$n$($v_1$, $\ldots$, $v_n$)} registers the
|
||||
$n$ variables (l-values) with the garbage collector.
|
||||
It must be within scope of a \code{S48\_DECLARE\_GC\_PROTECT($n$)}
|
||||
and be before any code which can cause a GC.
|
||||
\code{S48\_GC\_UNPROTECT} removes the block's protected variables from
|
||||
the garbage collectors list.
|
||||
the garbage collector's list.
|
||||
It must be called at the end of the block after
|
||||
any code which may cause a garbage collection.
|
||||
Omitting any of the three may cause serious and
|
||||
|
|
@ -648,7 +675,7 @@ The following macros can be used to create and access embedded C objects.
|
|||
\cvar{type}, and \code{S48\_EXTRACT\_VALUE\_POINTER} returns a pointer
|
||||
to the contents of the byte vector.
|
||||
The value returned by \code{S48\_EXTRACT\_VALUE\_POINTER} is valid only until
|
||||
the next \link{garbage collection}[(see Section~\ref{gc})]{gc}.
|
||||
the next garbage collection.
|
||||
|
||||
\code{S48\_SET\_VALUE} stores \code{value} into the byte vector.
|
||||
|
||||
|
|
@ -675,7 +702,7 @@ The Scheme~48 heap is written into a file in a machine-independent and
|
|||
The procedures described above may be used to create objects in the
|
||||
Scheme heap that contain information specific to the current
|
||||
machine, operating system, or process.
|
||||
A heap image containing such objects may not work correctly on
|
||||
A heap image containing such objects may not work correctly
|
||||
when resumed.
|
||||
|
||||
To address this problem, a record type may be given a `resumer'
|
||||
|
|
@ -738,7 +765,8 @@ For example, given the following record-type definition
|
|||
\end{example}
|
||||
\code{Thing} records can then be made in C:
|
||||
\begin{example}
|
||||
static scheme_value thing_record_type_binding = SCHFALSE;
|
||||
static scheme_value
|
||||
thing_record_type_binding = SCHFALSE;
|
||||
|
||||
void initialize_things(void)
|
||||
\{
|
||||
|
|
@ -796,7 +824,7 @@ Like \code{s48\_raise\_scheme\_exception} these never return.
|
|||
\begin{protos}
|
||||
\cproto{s48\_raise\_argument\_type\_error(scheme\_value)}
|
||||
\cproto{s48\_raise\_argument\_number\_error(int nargs, int min, int max)}
|
||||
\cproto{s48\_raise\_index\_range\_error(long value, long min, long max)}
|
||||
\cproto{s48\_raise\_range\_error(long value, long min, long max)}
|
||||
\cproto{s48\_raise\_closed\_channel\_error()}
|
||||
\cproto{s48\_raise\_os\_error(int errno)}
|
||||
\cproto{s48\_raise\_out\_of\_memory\_error()}
|
||||
|
|
@ -806,13 +834,16 @@ Like \code{s48\_raise\_scheme\_exception} these never return.
|
|||
type.
|
||||
An argument number error is raised when the number of arguments, \code{nargs},
|
||||
should be, but isn't, between \code{min} and \code{max}, inclusive.
|
||||
Similarly, and index range error is raised when \code{value} is not between
|
||||
Similarly, a range error indicates that \code{value} is not between
|
||||
between \code{min} and \code{max}, inclusive.
|
||||
|
||||
The following macros raise argument type errors if their argument does not
|
||||
have the required type.
|
||||
\code{S48\_CHECK\_BOOLEAN} raises an error if its argument is neither
|
||||
\code{\#t} or \code{\#f}.
|
||||
|
||||
\begin{protos}
|
||||
\cproto{void S48\_CHECK\_BOOLEAN(s48\_value)}
|
||||
\cproto{void S48\_CHECK\_SYMBOL(s48\_value)}
|
||||
\cproto{void S48\_CHECK\_PAIR(s48\_value)}
|
||||
\cproto{void S48\_CHECK\_STRING(s48\_value)}
|
||||
|
|
@ -884,5 +915,3 @@ They are provided for the purpose of writing more efficient code;
|
|||
\cproto{void \ \ \ \ \ S48\_UNSAFE\_SET\_VALUE(s48\_value, type, value)}
|
||||
\end{protos}
|
||||
|
||||
\end{document}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,51 @@
|
|||
\W\newcommand{\langle}{<}
|
||||
\W\newcommand{\rangle}{>}
|
||||
|
||||
\newcommand{\meta}[1]{{\noindent\mbox{\textrm{$\langle$#1$\rangle$}}}}
|
||||
\newcommand{\hyper}[1]{\meta{#1}}
|
||||
\newcommand{\hyperi}[1]{\hyper{#1$_1$}}
|
||||
\newcommand{\hyperii}[1]{\hyper{#1$_2$}}
|
||||
\newcommand{\hyperj}[1]{\hyper{#1$_i$}}
|
||||
\newcommand{\hypern}[1]{\hyper{#1$_n$}}
|
||||
\renewcommand{\var}[1]{\noindent\mbox{\textit{#1}}}
|
||||
\newcommand{\vari}[1]{\var{#1$_1$}}
|
||||
\newcommand{\varii}[1]{\var{#1$_2$}}
|
||||
\newcommand{\variii}[1]{\var{#1$_3$}}
|
||||
\newcommand{\variv}[1]{\var{#1$_4$}}
|
||||
\newcommand{\varj}[1]{\var{#1$_j$}}
|
||||
\newcommand{\varn}[1]{\var{#1$_n$}}
|
||||
|
||||
\W\newcommand{\frenchspacing}{}
|
||||
\W\newcommand{\textnormal}[1]{#1}
|
||||
|
||||
\newcommand{\defining}[1]{{\emph{#1}}}
|
||||
|
||||
\newcommand{\exprtype}{syntax}
|
||||
|
||||
\W\newcommand{\unskip}{}
|
||||
\W\newcommand{\textrm}[1]{#1}
|
||||
|
||||
\newcommand{\dotsfoo}{\ldots\texonly{\thinspace}}
|
||||
|
||||
\newcommand{\goesto}{%
|
||||
\texonly{\hbox{$\longrightarrow$}}%
|
||||
\htmlonly{\code{-->}}%
|
||||
}
|
||||
|
||||
\newcommand{\xform}{%
|
||||
\texonly{\hbox{$\Longrightarrow$}}%
|
||||
\htmlonly{\code{--->}}%
|
||||
}
|
||||
|
||||
\newcommand{\arbno}[1]{{{#1}$^*$}}
|
||||
\newcommand{\hack}{Scheme~48}
|
||||
|
||||
\T\newcommand{\alt}{$\vert$}
|
||||
\W\newcommand{\alt}{|}
|
||||
|
||||
\T\newcommand{\ok}{\discretionary{}{}{}}
|
||||
\W\newcommand{\ok}{}
|
||||
|
||||
\T\newcommand{\syn}[1]{{\noindent\mbox{\textrm{$\langle$#1$\rangle$}}}}
|
||||
\W\newcommand{\syn}[1]{{\noindent\mbox{$\langle$#1$\rangle$}}}
|
||||
|
||||
|
|
@ -28,6 +28,9 @@
|
|||
\newcommand{\texonly}[1]{#1}
|
||||
\newcommand{\T}{}
|
||||
|
||||
\lefthyphenmin=2
|
||||
\righthyphenmin=3
|
||||
|
||||
%%
|
||||
%% Treatment of special characters
|
||||
%%
|
||||
|
|
|
|||
|
|
@ -0,0 +1,171 @@
|
|||
; Program to process index entries.
|
||||
|
||||
; Script for running this in Scheme 48
|
||||
;
|
||||
; ,open tables sort define-record-types util big-util
|
||||
; (load "index.scm")
|
||||
; (process-index "manual.idx" "index.tex")
|
||||
|
||||
(define (process-index infile outfile)
|
||||
(let ((entries (call-with-input-file infile read-entries)))
|
||||
(call-with-output-file outfile
|
||||
(lambda (out)
|
||||
(write-index (sort-list entries entry<?)
|
||||
out)))))
|
||||
|
||||
; Entry records.
|
||||
|
||||
(define-record-type entry :entry
|
||||
(make-entry key font main? page)
|
||||
entry?
|
||||
(key entry-key)
|
||||
(font entry-font)
|
||||
(main? entry-main?)
|
||||
(page entry-page))
|
||||
|
||||
(define (entry<? x y)
|
||||
(let ((key1 (entry-key x))
|
||||
(key2 (entry-key y)))
|
||||
(or (string<? key1 key2)
|
||||
(and (string=? key1 key2)
|
||||
(or (and (entry-main? x)
|
||||
(not (entry-main? y)))
|
||||
(and (eq? (entry-main? x)
|
||||
(entry-main? y))
|
||||
(< (entry-page x)
|
||||
(entry-page y))))))))
|
||||
|
||||
;----------------------------------------------------------------
|
||||
; Read a file of index entries.
|
||||
|
||||
(define (read-entries in)
|
||||
(let loop ((entries '()))
|
||||
(let ((next (read-char in)))
|
||||
(cond ((eof-object? next)
|
||||
(reverse entries))
|
||||
((char=? next #\\)
|
||||
(loop (cons (read-entry in)
|
||||
entries)))
|
||||
(else
|
||||
(error "missing initial \\ in index entry" in))))))
|
||||
|
||||
; An *.idx entry looks like
|
||||
; \indexentry{define-structure!tt!main}{12}
|
||||
; We need to watch for {...} in the name, as they may be used to escape !'s.
|
||||
; The caller has eaten the initial \.
|
||||
|
||||
(define (read-entry in)
|
||||
(skip-past #\{ in)
|
||||
(let* ((key (read-field in))
|
||||
(font (read-field in))
|
||||
(main? (string=? (read-field in) "main")))
|
||||
(read-char in) ; skip #\{
|
||||
(let ((page (string->number (read-field in))))
|
||||
(skip-past #\newline in)
|
||||
(make-entry key font main? page))))
|
||||
|
||||
; Read from IN until you see CHAR.
|
||||
|
||||
(define (skip-past char in)
|
||||
(let ((ch (read-char in)))
|
||||
(cond ((eof-object? ch)
|
||||
(error "premature eof when looking for" char))
|
||||
((not (char=? ch char))
|
||||
(skip-past char in)))))
|
||||
|
||||
; Gather chars until an unnested ! or #\} is seen.
|
||||
|
||||
(define (read-field in)
|
||||
(let loop ((chars '()) (depth 0))
|
||||
(let ((next (read-char in)))
|
||||
(if (eof-object? next)
|
||||
(error "premature eof when reading field"
|
||||
(list->string (reverse chars)))
|
||||
(let ((next (char-downcase next)))
|
||||
(case next
|
||||
((#\!)
|
||||
(if (= depth 0)
|
||||
(list->string (reverse chars))
|
||||
(loop (cons next chars) depth)))
|
||||
((#\})
|
||||
(if (= depth 0)
|
||||
(list->string (reverse chars))
|
||||
(loop chars (- depth 1))))
|
||||
((#\{)
|
||||
(loop chars (+ depth 1)))
|
||||
(else
|
||||
(loop (cons next chars) depth))))))))
|
||||
|
||||
;----------------------------------------------------------------
|
||||
; Writing the entries back out again.
|
||||
|
||||
(define (write-index entries out)
|
||||
(let loop ((entries entries))
|
||||
(if (not (null? entries))
|
||||
(mvlet (((key-entries entries)
|
||||
(collect-key-entries entries)))
|
||||
(process-key key-entries out)
|
||||
(loop entries)))))
|
||||
|
||||
(define (collect-key-entries entries)
|
||||
(let ((key (entry-key (car entries))))
|
||||
(let loop ((entries (cdr entries))
|
||||
(res (list (car entries))))
|
||||
(if (or (null? entries)
|
||||
(not (string=? key
|
||||
(entry-key (car entries)))))
|
||||
(values (reverse res) entries)
|
||||
(loop (cdr entries)
|
||||
(cons (car entries) res))))))
|
||||
|
||||
(define (process-key entries out)
|
||||
(if (not (consistent? entries))
|
||||
(error "inconsistent entries" entries))
|
||||
(let ((entry (car entries)))
|
||||
(let ((key (entry-key entry))
|
||||
(font (entry-font entry))
|
||||
(pages (remove-duplicates (map entry-page entries))))
|
||||
(if (entry-main? entry)
|
||||
(write-entries key font (car pages) (cdr pages) out)
|
||||
(write-entries key font #f pages out)))))
|
||||
|
||||
(define (consistent? entries)
|
||||
(let ((x (car entries)))
|
||||
(let ((key (entry-key x))
|
||||
(font (entry-font x)))
|
||||
(every (lambda (x)
|
||||
(and (string=? key (entry-key x))
|
||||
(or (string=? font (entry-font x))
|
||||
;; different entries for t and #t aren't inconsistent
|
||||
(string=? font "sharp")
|
||||
(string=? (entry-font x) "sharp"))
|
||||
;(eq? aux (entry-main/aux x))
|
||||
))
|
||||
(cdr entries)))))
|
||||
|
||||
(define last-key "%")
|
||||
(define s1 (string-append "\\item{" (list->string '(#\\))))
|
||||
(define s2 "{")
|
||||
(define s3 "}}{\\hskip .75em}")
|
||||
(define semi "; ")
|
||||
(define comma ", ")
|
||||
|
||||
(define (write-entries key font main pages p)
|
||||
(if (and (char-alphabetic? (string-ref key 0))
|
||||
(not (char=? (string-ref last-key 0)
|
||||
(string-ref key 0))))
|
||||
(begin (display "\\indexspace" p)
|
||||
(newline p)))
|
||||
(set! last-key key)
|
||||
(display (string-append s1 font s2 key s3) p)
|
||||
(if main
|
||||
(begin (write main p)
|
||||
(if (not (null? pages))
|
||||
(display semi p))))
|
||||
(if (not (null? pages))
|
||||
(begin (write (car pages) p)
|
||||
(for-each (lambda (page)
|
||||
(display comma p)
|
||||
(write page p))
|
||||
(cdr pages))))
|
||||
(newline p))
|
||||
|
|
@ -0,0 +1,299 @@
|
|||
\indexspace
|
||||
\item{\tt{accessible?}}{\hskip .75em}72
|
||||
\item{\tt{add-signal-queue-signal!}}{\hskip .75em}68
|
||||
\item{\tt{any-match?}}{\hskip .75em}47
|
||||
\item{\tt{arithmetic-shift}}{\hskip .75em}28
|
||||
\item{\tt{array}}{\hskip .75em}30
|
||||
\item{\tt{array->vector}}{\hskip .75em}30
|
||||
\item{\tt{array-dimensions}}{\hskip .75em}30
|
||||
\item{\tt{array-ref}}{\hskip .75em}30
|
||||
\item{\tt{array-set!}}{\hskip .75em}30
|
||||
\item{\tt{array?}}{\hskip .75em}30
|
||||
\item{\tt{ascii->char}}{\hskip .75em}28
|
||||
\item{\tt{ascii-limit}}{\hskip .75em}28
|
||||
\item{\tt{ascii-range}}{\hskip .75em}45
|
||||
\item{\tt{ascii-ranges}}{\hskip .75em}45
|
||||
\item{\tt{ascii-whitespaces}}{\hskip .75em}28
|
||||
\indexspace
|
||||
\item{\tt{bit-count}}{\hskip .75em}29
|
||||
\item{\tt{bitwise-and}}{\hskip .75em}28
|
||||
\item{\tt{bitwise-ior}}{\hskip .75em}28
|
||||
\item{\tt{bitwise-not}}{\hskip .75em}28
|
||||
\item{\tt{bitwise-xor}}{\hskip .75em}28
|
||||
\item{\tt{byte-vector}}{\hskip .75em}29
|
||||
\item{\tt{byte-vector-length}}{\hskip .75em}29
|
||||
\item{\tt{byte-vector-ref}}{\hskip .75em}29
|
||||
\item{\tt{byte-vector-set!}}{\hskip .75em}29
|
||||
\item{\tt{byte-vector?}}{\hskip .75em}29
|
||||
\indexspace
|
||||
\item{\tt{call-external}}{\hskip .75em}55; 54
|
||||
\item{\tt{call-external-value}}{\hskip .75em}54
|
||||
\item{\tt{call-imported-binding}}{\hskip .75em}54
|
||||
\item{\tt{cell-ref}}{\hskip .75em}29
|
||||
\item{\tt{cell-set!}}{\hskip .75em}29
|
||||
\item{\tt{cell?}}{\hskip .75em}29
|
||||
\item{\tt{char->ascii}}{\hskip .75em}28
|
||||
\item{\tt{close-all-but}}{\hskip .75em}76
|
||||
\item{\tt{close-directory-stream}}{\hskip .75em}70
|
||||
\item{\tt{close-on-exec?}}{\hskip .75em}76
|
||||
\item{\tt{close-socket}}{\hskip .75em}38
|
||||
\item{\tt{compound-interface}}{\hskip .75em}21
|
||||
\item{\tt{copy-array}}{\hskip .75em}30
|
||||
\item{\tt{current-column}}{\hskip .75em}37
|
||||
\item{\tt{current-row}}{\hskip .75em}37
|
||||
\item{\tt{current-time}}{\hskip .75em}74
|
||||
\indexspace
|
||||
\item{\tt{default-hash-function}}{\hskip .75em}36
|
||||
\item{\tt{define-exported-binding}}{\hskip .75em}52
|
||||
\item{\tt{define-imported-binding}}{\hskip .75em}53
|
||||
\item{\tt{define-interface}}{\hskip .75em}20
|
||||
\item{\tt{define-record-discloser}}{\hskip .75em}33; 31
|
||||
\item{\tt{define-record-resumer}}{\hskip .75em}60; 33
|
||||
\item{\tt{define-structure}}{\hskip .75em}18
|
||||
\item{\tt{delete-from-queue!}}{\hskip .75em}29
|
||||
\item{\tt{dequeue!}}{\hskip .75em}29
|
||||
\item{\tt{dequeue-signal!}}{\hskip .75em}67
|
||||
\item{\tt{directory-stream?}}{\hskip .75em}70
|
||||
\item{\tt{dup}}{\hskip .75em}75
|
||||
\item{\tt{dup-switching-mode}}{\hskip .75em}75
|
||||
\item{\tt{dup2}}{\hskip .75em}75
|
||||
\item{\tt{dynamic-load}}{\hskip .75em}55
|
||||
\indexspace
|
||||
\item{\tt{enqueue!}}{\hskip .75em}29
|
||||
\item{\tt{environment-alist}}{\hskip .75em}69
|
||||
\item{\tt{exact-match?}}{\hskip .75em}47
|
||||
\item{\tt{exec}}{\hskip .75em}65
|
||||
\item{\tt{exec-file}}{\hskip .75em}65
|
||||
\item{\tt{exec-file-with-environment}}{\hskip .75em}65
|
||||
\item{\tt{exec-with-alias}}{\hskip .75em}65
|
||||
\item{\tt{exec-with-environment}}{\hskip .75em}65
|
||||
\item{\tt{exit}}{\hskip .75em}65
|
||||
\item{\tt{external-name}}{\hskip .75em}55
|
||||
\item{\tt{external-value}}{\hskip .75em}55
|
||||
\item{\tt{external?}}{\hskip .75em}55
|
||||
\indexspace
|
||||
\item{\tt{fd-port?}}{\hskip .75em}75
|
||||
\item{\tt{file-info-device}}{\hskip .75em}73
|
||||
\item{\tt{file-info-group}}{\hskip .75em}73
|
||||
\item{\tt{file-info-inode}}{\hskip .75em}73
|
||||
\item{\tt{file-info-last-access}}{\hskip .75em}73
|
||||
\item{\tt{file-info-last-info-change}}{\hskip .75em}73
|
||||
\item{\tt{file-info-last-modification}}{\hskip .75em}73
|
||||
\item{\tt{file-info-link-count}}{\hskip .75em}73
|
||||
\item{\tt{file-info-mode}}{\hskip .75em}73
|
||||
\item{\tt{file-info-name}}{\hskip .75em}72
|
||||
\item{\tt{file-info-owner}}{\hskip .75em}73
|
||||
\item{\tt{file-info-size}}{\hskip .75em}73
|
||||
\item{\tt{file-info-type}}{\hskip .75em}72
|
||||
\item{\tt{file-info?}}{\hskip .75em}72
|
||||
\item{\tt{file-mode+}}{\hskip .75em}73
|
||||
\item{\tt{file-mode-}}{\hskip .75em}73
|
||||
\item{\tt{file-mode->integer}}{\hskip .75em}74
|
||||
\item{\tt{file-mode<=?}}{\hskip .75em}73
|
||||
\item{\tt{file-mode=?}}{\hskip .75em}73
|
||||
\item{\tt{file-mode>=?}}{\hskip .75em}73
|
||||
\item{\tt{file-mode?}}{\hskip .75em}73
|
||||
\item{\tt{file-options-on?}}{\hskip .75em}71
|
||||
\item{\tt{file-type-name}}{\hskip .75em}72
|
||||
\item{\tt{file-type?}}{\hskip .75em}72
|
||||
\item{\tt{fluid}}{\hskip .75em}37
|
||||
\item{\tt{fork}}{\hskip .75em}64
|
||||
\item{\tt{fork-and-forget}}{\hskip .75em}64
|
||||
\item{\tt{fresh-line}}{\hskip .75em}37
|
||||
\indexspace
|
||||
\item{\tt{get-effective-group-id}}{\hskip .75em}68
|
||||
\item{\tt{get-effective-user-id}}{\hskip .75em}68
|
||||
\item{\tt{get-external}}{\hskip .75em}55
|
||||
\item{\tt{get-file-info}}{\hskip .75em}72
|
||||
\item{\tt{get-file/link-info}}{\hskip .75em}72
|
||||
\item{\tt{get-group-id}}{\hskip .75em}68
|
||||
\item{\tt{get-groups}}{\hskip .75em}68
|
||||
\item{\tt{get-host-name}}{\hskip .75em}38
|
||||
\item{\tt{get-login-name}}{\hskip .75em}68
|
||||
\item{\tt{get-parent-process-id}}{\hskip .75em}68
|
||||
\item{\tt{get-port-info}}{\hskip .75em}72
|
||||
\item{\tt{get-process-id}}{\hskip .75em}68
|
||||
\item{\tt{get-user-id}}{\hskip .75em}68
|
||||
\item{\tt{group-id->group-info}}{\hskip .75em}69
|
||||
\item{\tt{group-id->integer}}{\hskip .75em}69
|
||||
\item{\tt{group-id=?}}{\hskip .75em}69
|
||||
\item{\tt{group-id?}}{\hskip .75em}69
|
||||
\item{\tt{group-info-id}}{\hskip .75em}69
|
||||
\item{\tt{group-info-members}}{\hskip .75em}69
|
||||
\item{\tt{group-info-name}}{\hskip .75em}69
|
||||
\item{\tt{group-info?}}{\hskip .75em}69
|
||||
\indexspace
|
||||
\item{\tt{have-system?}}{\hskip .75em}38
|
||||
\indexspace
|
||||
\item{\tt{i/o-flags}}{\hskip .75em}76
|
||||
\item{\tt{ignore-case}}{\hskip .75em}47
|
||||
\item{\tt{integer->file-mode}}{\hskip .75em}74
|
||||
\item{\tt{integer->group-id}}{\hskip .75em}69
|
||||
\item{\tt{integer->process-id}}{\hskip .75em}65
|
||||
\item{\tt{integer->signal}}{\hskip .75em}66
|
||||
\item{\tt{integer->user-id}}{\hskip .75em}69
|
||||
\item{\tt{intersection}}{\hskip .75em}45
|
||||
\indexspace
|
||||
\item{\tt{let-fluid}}{\hskip .75em}37
|
||||
\item{\tt{let-fluids}}{\hskip .75em}37
|
||||
\item{\tt{limit-output}}{\hskip .75em}36
|
||||
\item{\tt{link}}{\hskip .75em}72
|
||||
\item{\tt{list->queue}}{\hskip .75em}29
|
||||
\item{\tt{list-directory}}{\hskip .75em}70
|
||||
\item{\tt{lookup-all-externals}}{\hskip .75em}55
|
||||
\item{\tt{lookup-environment-variable}}{\hskip .75em}69
|
||||
\item{\tt{lookup-exported-binding}}{\hskip .75em}53
|
||||
\item{\tt{lookup-external}}{\hskip .75em}55
|
||||
\item{\tt{lookup-imported-binding}}{\hskip .75em}53
|
||||
\indexspace
|
||||
\item{\tt{machine-name}}{\hskip .75em}70
|
||||
\item{\tt{make-array}}{\hskip .75em}30
|
||||
\item{\tt{make-byte-vector}}{\hskip .75em}29
|
||||
\item{\tt{make-cell}}{\hskip .75em}29
|
||||
\item{\tt{make-directory}}{\hskip .75em}72
|
||||
\item{\tt{make-fifo}}{\hskip .75em}72
|
||||
\item{\tt{make-fluid}}{\hskip .75em}37
|
||||
\item{\tt{make-integer-table}}{\hskip .75em}35
|
||||
\item{\tt{make-queue}}{\hskip .75em}29
|
||||
\item{\tt{make-record}}{\hskip .75em}32
|
||||
\item{\tt{make-record-type}}{\hskip .75em}33
|
||||
\item{\tt{make-regexp}}{\hskip .75em}76
|
||||
\item{\tt{make-shared-array}}{\hskip .75em}30
|
||||
\item{\tt{make-signal-queue}}{\hskip .75em}67
|
||||
\item{\tt{make-string-input-port}}{\hskip .75em}36
|
||||
\item{\tt{make-string-output-port}}{\hskip .75em}36
|
||||
\item{\tt{make-string-table}}{\hskip .75em}35
|
||||
\item{\tt{make-symbol-table}}{\hskip .75em}35
|
||||
\item{\tt{make-table}}{\hskip .75em}35
|
||||
\item{\tt{make-table-immutable!}}{\hskip .75em}35
|
||||
\item{\tt{make-table-maker}}{\hskip .75em}35
|
||||
\item{\tt{make-time}}{\hskip .75em}74
|
||||
\item{\tt{make-tracking-input-port}}{\hskip .75em}36
|
||||
\item{\tt{make-tracking-output-port}}{\hskip .75em}37
|
||||
\item{\tt{match}}{\hskip .75em}47
|
||||
\item{\tt{match-end}}{\hskip .75em}77; 47
|
||||
\item{\tt{match-start}}{\hskip .75em}77; 47
|
||||
\item{\tt{match-submatches}}{\hskip .75em}47
|
||||
\item{\tt{match?}}{\hskip .75em}77
|
||||
\item{\tt{maybe-dequeue-signal!}}{\hskip .75em}67
|
||||
\item{\tt{modify}}{\hskip .75em}18
|
||||
\indexspace
|
||||
\item{\tt{name->group-info}}{\hskip .75em}69
|
||||
\item{\tt{name->signal}}{\hskip .75em}66
|
||||
\item{\tt{name->user-info}}{\hskip .75em}69
|
||||
\item{\tt{negate}}{\hskip .75em}45
|
||||
\item{\tt{no-submatches}}{\hskip .75em}47
|
||||
\indexspace
|
||||
\item{\tt{one-of}}{\hskip .75em}46
|
||||
\item{\tt{open-directory-stream}}{\hskip .75em}70
|
||||
\item{\tt{open-file}}{\hskip .75em}70
|
||||
\item{\tt{open-pipe}}{\hskip .75em}75
|
||||
\item{\tt{open-socket}}{\hskip .75em}38
|
||||
\item{\tt{os-name}}{\hskip .75em}70
|
||||
\item{\tt{os-node-name}}{\hskip .75em}70
|
||||
\item{\tt{os-release-name}}{\hskip .75em}70
|
||||
\item{\tt{os-version-name}}{\hskip .75em}70
|
||||
\indexspace
|
||||
\item{\tt{port->fd}}{\hskip .75em}75
|
||||
\item{\tt{port-is-a-terminal?}}{\hskip .75em}76
|
||||
\item{\tt{port-terminal-name}}{\hskip .75em}76
|
||||
\item{\tt{prefix}}{\hskip .75em}18
|
||||
\item{\tt{process-id->integer}}{\hskip .75em}65
|
||||
\item{\tt{process-id-exit-status}}{\hskip .75em}65
|
||||
\item{\tt{process-id-terminating-signal}}{\hskip .75em}65
|
||||
\item{\tt{process-id=?}}{\hskip .75em}65
|
||||
\item{\tt{process-id?}}{\hskip .75em}65
|
||||
\indexspace
|
||||
\item{\tt{queue->list}}{\hskip .75em}29
|
||||
\item{\tt{queue-empty?}}{\hskip .75em}29
|
||||
\item{\tt{queue-length}}{\hskip .75em}29
|
||||
\item{\tt{queue?}}{\hskip .75em}29
|
||||
\indexspace
|
||||
\item{\tt{range}}{\hskip .75em}45
|
||||
\item{\tt{ranges}}{\hskip .75em}45
|
||||
\item{\tt{read-directory-stream}}{\hskip .75em}70
|
||||
\item{\tt{record}}{\hskip .75em}32
|
||||
\item{\tt{record-accessor}}{\hskip .75em}33
|
||||
\item{\tt{record-constructor}}{\hskip .75em}33
|
||||
\item{\tt{record-length}}{\hskip .75em}32
|
||||
\item{\tt{record-modifier}}{\hskip .75em}33
|
||||
\item{\tt{record-predicate}}{\hskip .75em}33
|
||||
\item{\tt{record-ref}}{\hskip .75em}32
|
||||
\item{\tt{record-set!}}{\hskip .75em}32
|
||||
\item{\tt{record-type}}{\hskip .75em}32
|
||||
\item{\tt{record-type-field-names}}{\hskip .75em}33
|
||||
\item{\tt{record-type-name}}{\hskip .75em}33
|
||||
\item{\tt{record-type?}}{\hskip .75em}33
|
||||
\item{\tt{record?}}{\hskip .75em}32
|
||||
\item{\tt{regexp-match}}{\hskip .75em}77
|
||||
\item{\tt{regexp?}}{\hskip .75em}76
|
||||
\item{\tt{remap-file-descriptors}}{\hskip .75em}75
|
||||
\item{\tt{remove-directory}}{\hskip .75em}72
|
||||
\item{\tt{remove-signal-queue-signal!}}{\hskip .75em}68
|
||||
\item{\tt{rename}}{\hskip .75em}72
|
||||
\item{\tt{repeat}}{\hskip .75em}46
|
||||
\indexspace
|
||||
\item{\tt{sequence}}{\hskip .75em}46
|
||||
\item{\tt{set}}{\hskip .75em}45
|
||||
\item{\tt{set-close-on-exec?!}}{\hskip .75em}76
|
||||
\item{\tt{set-file-creation-mask!}}{\hskip .75em}71
|
||||
\item{\tt{set-group-id!}}{\hskip .75em}68
|
||||
\item{\tt{set-i/o-flags!}}{\hskip .75em}76
|
||||
\item{\tt{set-user-id!}}{\hskip .75em}68
|
||||
\item{\tt{set-working-directory!}}{\hskip .75em}70
|
||||
\item{\tt{shared-binding-is-import?}}{\hskip .75em}53
|
||||
\item{\tt{shared-binding-name}}{\hskip .75em}53
|
||||
\item{\tt{shared-binding-ref}}{\hskip .75em}53
|
||||
\item{\tt{shared-binding-set!}}{\hskip .75em}53
|
||||
\item{\tt{shared-binding?}}{\hskip .75em}53
|
||||
\item{\tt{signal-name}}{\hskip .75em}66
|
||||
\item{\tt{signal-os-number}}{\hskip .75em}66
|
||||
\item{\tt{signal-process}}{\hskip .75em}67
|
||||
\item{\tt{signal-queue-monitored-signals}}{\hskip .75em}67
|
||||
\item{\tt{signal-queue?}}{\hskip .75em}67
|
||||
\item{\tt{signal=?}}{\hskip .75em}66
|
||||
\item{\tt{signal?}}{\hskip .75em}66
|
||||
\item{\tt{socket-accept}}{\hskip .75em}38
|
||||
\item{\tt{socket-client}}{\hskip .75em}39
|
||||
\item{\tt{socket-port-number}}{\hskip .75em}38
|
||||
\item{\tt{string-end}}{\hskip .75em}46
|
||||
\item{\tt{string-hash}}{\hskip .75em}36
|
||||
\item{\tt{string-output-port-output}}{\hskip .75em}36
|
||||
\item{\tt{string-start}}{\hskip .75em}46
|
||||
\item{\tt{submatch}}{\hskip .75em}47
|
||||
\item{\tt{subset}}{\hskip .75em}18
|
||||
\item{\tt{subtract}}{\hskip .75em}45
|
||||
\item{\tt{system}}{\hskip .75em}38
|
||||
\indexspace
|
||||
\item{\tt{table-ref}}{\hskip .75em}36
|
||||
\item{\tt{table-set!}}{\hskip .75em}36
|
||||
\item{\tt{table-walk}}{\hskip .75em}36
|
||||
\item{\tt{table?}}{\hskip .75em}36
|
||||
\item{\tt{text}}{\hskip .75em}46
|
||||
\item{\tt{time->string}}{\hskip .75em}75
|
||||
\item{\tt{time-seconds}}{\hskip .75em}74
|
||||
\item{\tt{time<=?}}{\hskip .75em}74
|
||||
\item{\tt{time<?}}{\hskip .75em}74
|
||||
\item{\tt{time=?}}{\hskip .75em}74
|
||||
\item{\tt{time>=?}}{\hskip .75em}74
|
||||
\item{\tt{time>?}}{\hskip .75em}74
|
||||
\item{\tt{time?}}{\hskip .75em}74
|
||||
\indexspace
|
||||
\item{\tt{undefine-exported-binding}}{\hskip .75em}53
|
||||
\item{\tt{undefine-imported-binding}}{\hskip .75em}53
|
||||
\item{\tt{union}}{\hskip .75em}45
|
||||
\item{\tt{unlink}}{\hskip .75em}72
|
||||
\item{\tt{use-case}}{\hskip .75em}47
|
||||
\item{\tt{user-id->integer}}{\hskip .75em}69
|
||||
\item{\tt{user-id->user-info}}{\hskip .75em}69
|
||||
\item{\tt{user-id=?}}{\hskip .75em}69
|
||||
\item{\tt{user-id?}}{\hskip .75em}69
|
||||
\item{\tt{user-info-group}}{\hskip .75em}69
|
||||
\item{\tt{user-info-home-directory}}{\hskip .75em}69
|
||||
\item{\tt{user-info-id}}{\hskip .75em}69
|
||||
\item{\tt{user-info-name}}{\hskip .75em}69
|
||||
\item{\tt{user-info-shell}}{\hskip .75em}69
|
||||
\item{\tt{user-info?}}{\hskip .75em}69
|
||||
\indexspace
|
||||
\item{\tt{wait-for-child-process}}{\hskip .75em}65
|
||||
\item{\tt{working-directory}}{\hskip .75em}70
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
|
||||
\chapter{Introduction}
|
||||
|
||||
Scheme~48 is an implementation of the Scheme programming language as
|
||||
described in the Revised$^5$ Report on the Algorithmic Language
|
||||
Scheme~\cite{R5RS}.
|
||||
It is based on a compiler and interpreter for a virtual Scheme
|
||||
machine. Scheme~48 tries to be faithful to the Revised$^5$ Scheme
|
||||
Report, providing neither more nor less in the initial user
|
||||
environment. (This is not to say that more isn't available in other
|
||||
environments; see below.) Support for numbers is weak: bignums are
|
||||
slow and floating point is almost nonexistent (see description of
|
||||
floatnums, below).
|
||||
|
||||
% JAR says: replace zurich with mumble.net or ...
|
||||
|
||||
Scheme~48 is under continual development.
|
||||
Please report bugs, especially in the VM, especially core dumps, to
|
||||
scheme-48-bugs@zurich.ai.mit.edu. Include the version number x.yy
|
||||
from the "Welcome to Scheme~48 x.yy" greeting message in your bug
|
||||
report. It is a goal of this project to produce a bullet-proof
|
||||
system; we want no bugs and, especially, no crashes. (There are a few
|
||||
known bugs, listed in the {\tt doc/todo.txt} file that comes with the
|
||||
distribution.)
|
||||
|
||||
Send mail to scheme-48-request@zurich.ai.mit.edu to be put on a
|
||||
mailing list for announcements, discussion, bug reports, and bug
|
||||
fixes.
|
||||
|
||||
The name `Scheme~48' commemorates our having written the original version
|
||||
in forty-eight hours, on August 6th and 7th, 1986.
|
||||
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
\newcommand{\mainschindex}[1]{\cindex[#1]{{\tt #1}}}
|
||||
\newcommand{\mainindex}[1]{\cindex[1]{{\rm #1}}}
|
||||
\newcommand{\schindex}[1]{}
|
||||
\newcommand{\sharpindex}[1]{}
|
||||
|
||||
\newcommand{\codemainindex}[1]{{\mainschindex{#1}\code{#1}}}
|
||||
\newcommand{\codeindex}[1]{{\mainschindex{#1}\code{#1}}}
|
||||
|
|
@ -0,0 +1,130 @@
|
|||
% Scheme 48 documentation
|
||||
|
||||
\documentclass[twoside,11pt]{report}
|
||||
\usepackage{hyperlatex}
|
||||
\T\usepackage{longtable}
|
||||
\T\usepackage{myindex}
|
||||
\T\usepackage{palatino}
|
||||
\W\include{latex-index}
|
||||
|
||||
\T\textwidth5.7in
|
||||
\T\textheight8.9in
|
||||
\T\oddsidemargin10pt\evensidemargin20pt
|
||||
%\T\advance\textwidth by 4em
|
||||
|
||||
\makeindex
|
||||
|
||||
\W\include{my-sequential}
|
||||
\include{proto}
|
||||
\include{hacks}
|
||||
|
||||
%\includeonly{posix}
|
||||
|
||||
% Make a few big HTML files, and not a lot of small ones.
|
||||
\setcounter{htmldepth}{3}
|
||||
|
||||
% Put the html code in its own directory.
|
||||
\htmldirectory{manual}
|
||||
|
||||
% Set the html base name.
|
||||
\htmlname{s48manual}
|
||||
|
||||
% Add sections to main menu
|
||||
\setcounter{htmlautomenu}{2}
|
||||
|
||||
% White background
|
||||
\htmlattributes{BODY}{BGCOLOR="#ffffff"}
|
||||
|
||||
\htmltitle{Scheme 48 Manual}
|
||||
|
||||
% Suppress navigation panel for first page.
|
||||
\htmlpanel{0}
|
||||
|
||||
%%% End preamble
|
||||
|
||||
\begin{document}
|
||||
\label{top_node}
|
||||
|
||||
\T\sloppy % Tells TeX not to worry too much about line breaks.
|
||||
|
||||
\title{{\large The Incomplete} \\ Scheme 48 Reference Manual \\
|
||||
{\large for release \input{version-number}}}
|
||||
% December 25, 1994
|
||||
\author{Richard Kelsey and Jonathan Rees \\
|
||||
{\normalsize with a chapter by Mike Sperber}}
|
||||
\date{}
|
||||
%\date{October 31, 1995}
|
||||
|
||||
\T\cleardoublepage\pagenumbering{roman}
|
||||
|
||||
\maketitle
|
||||
|
||||
% For some reason the tabbing doesn't work here in html mode.
|
||||
\texonly{
|
||||
\begin{verse}
|
||||
A line may take us hours, yet if it does not seem a moment's thought \\
|
||||
All our stitching and unstitching has been as nought.
|
||||
\end{verse}
|
||||
\begin{tabbing}
|
||||
A line may take us hours, yet if it does not seem\= \kill
|
||||
\> Yeats \\
|
||||
\> {\em Adam's Curse}
|
||||
\end{tabbing}
|
||||
}
|
||||
|
||||
\htmlonly{
|
||||
\begin{center}
|
||||
\begin{tabbing}
|
||||
A line may take us hours, yet if it does not seem\= a moment's thought \\
|
||||
All our stitching and unstitching has been as nought. \\
|
||||
\> Yeats \\
|
||||
\> {\em Adam's Curse}
|
||||
\end{tabbing}
|
||||
\end{center}
|
||||
}
|
||||
|
||||
\htmlpanel{1}
|
||||
|
||||
\chapter*{Acknowledgements}
|
||||
|
||||
Thanks to Scheme~48's users for their suggestions, bug reports,
|
||||
and forbearance.
|
||||
Thanks also to Deborah Tatar for providing the Yeats quotation.
|
||||
|
||||
\T\tableofcontents
|
||||
|
||||
\T\cleardoublepage\pagenumbering{arabic}\setcounter{page}{1}
|
||||
|
||||
\setcounter{htmlautomenu}{1}
|
||||
|
||||
|
||||
\include{intro}
|
||||
\include{user-guide}
|
||||
\include{command}
|
||||
\include{module}
|
||||
\include{utilities}
|
||||
\include{external}
|
||||
\include{posix}
|
||||
\include{ascii}
|
||||
\include{bibliography}
|
||||
|
||||
\texonly{
|
||||
\begin{myindex}
|
||||
\addtocounter{chapter}{1}
|
||||
\addcontentsline{toc}{chapter}{\protect\numberline{\thechapter}{Index}}
|
||||
|
||||
The principal entry for each term, procedure, or keyword is listed
|
||||
first, separated from the other entries by a semicolon.
|
||||
|
||||
\bigskip
|
||||
|
||||
\input{index}
|
||||
\end{myindex}
|
||||
}
|
||||
|
||||
\htmlonly{
|
||||
\chapter*{Index}
|
||||
\htmlprintindex
|
||||
}
|
||||
|
||||
\end{document}
|
||||
|
|
@ -1,45 +1,41 @@
|
|||
\documentstyle[11pt]{article}
|
||||
|
||||
\include{code}
|
||||
\include{latex-stuff}
|
||||
%\htmltitle{Another Module System for Scheme}
|
||||
%
|
||||
%\begin{center}
|
||||
%{\Large\bf Another Module System for Scheme}
|
||||
%
|
||||
%\T\vspace{2ex}
|
||||
%Jonathan Rees \\
|
||||
%3 January 1993 (updated 15 January 1994)
|
||||
%\end{center}
|
||||
%
|
||||
%\T\vspace{3ex}}
|
||||
%
|
||||
%\W\begin{abstract}
|
||||
|
||||
\newcommand{\goesto}{\hbox{$\longrightarrow$}}
|
||||
\newcommand{\alt}{$\vert$}
|
||||
\newcommand{\arbno}[1]{{{#1}$^*$}}
|
||||
\newcommand{\hack}{Scheme~48}
|
||||
\chapter{Module system}
|
||||
\label{chapter:modules}
|
||||
|
||||
\begin{document}
|
||||
|
||||
\begin{center}
|
||||
{\Large\bf Another Module System for Scheme}
|
||||
|
||||
\vspace{2ex}
|
||||
Jonathan Rees \\
|
||||
3 January 1993 (updated 15 January 1994)
|
||||
\end{center}
|
||||
|
||||
\vspace{3ex}
|
||||
|
||||
This memo describes a module system for the Scheme programming
|
||||
language. The module system is unique in the extent to which it
|
||||
This chapter describes Scheme~48's module system.
|
||||
The module system is unique in the extent to which it
|
||||
supports both static linking and rapid turnaround during program
|
||||
development. The design was influenced by Standard ML
|
||||
modules\cite{MacQueen:Modules} and by the module system for Scheme
|
||||
Xerox\cite{Curtis-Rauen:Modules}. It has also been shaped by the
|
||||
needs of \hack{}, a virtual-machine-based Scheme implementation
|
||||
designed to run both on workstations and on relatively small (less
|
||||
than 1 Mbyte) embedded controllers.
|
||||
needs of \hack{}, which is designed to run both on workstations and
|
||||
on relatively small (less than 1 Mbyte) embedded controllers.
|
||||
|
||||
Except where noted, everything described here is implemented in
|
||||
\hack{}, and exercised by the \hack{} implementation and a few
|
||||
\hack{}, and exercised by the \hack{} implementation and some
|
||||
application programs.
|
||||
|
||||
Unlike the Common Lisp package system, the module system described
|
||||
here controls the mapping of names to denotations, not the
|
||||
mapping of strings to symbols.
|
||||
|
||||
%\W\end{abstract}
|
||||
|
||||
\subsection*{Introduction}
|
||||
\section{Introduction}
|
||||
|
||||
The module system supports the structured division of a corpus of
|
||||
Scheme software into a set of modules. Each module has its own
|
||||
|
|
@ -49,7 +45,7 @@ descriptions written in a special {\em configuration language.}
|
|||
A module may be instantiated multiple times, producing several {\em
|
||||
packages}, just as a lambda-expression can be instantiated multiple
|
||||
times to produce several different procedures. Since single
|
||||
instantiation is the normal case, I will defer discussion of multiple
|
||||
instantiation is the normal case, we will defer discussion of multiple
|
||||
instantiation until a later section. For now you can think of a
|
||||
package as simply a module's internal environment mapping names to
|
||||
denotations.
|
||||
|
|
@ -64,22 +60,23 @@ interface}.
|
|||
A module imports bindings from other modules by either {\em opening}
|
||||
or {\em accessing} some structures that are built on other packages.
|
||||
When a structure is opened, all of its exported bindings are visible
|
||||
in the client package. On the other hand, bindings from an accessed
|
||||
structure require explicitly qualified references written with the
|
||||
{\tt structure-ref} operator.
|
||||
in the client package.
|
||||
%On the other hand, bindings from an accessed
|
||||
%structure require explicitly qualified references written with the
|
||||
%{\tt structure-ref} operator.
|
||||
|
||||
For example:
|
||||
\begin{code}
|
||||
(define-structure foo (export a c cons)
|
||||
(open scheme)
|
||||
(begin (define a 1)
|
||||
(define (b x) (+ a x))
|
||||
(define (c y) (* (b a) y))))
|
||||
\codeskip
|
||||
(define-structure bar (export d)
|
||||
(open scheme foo)
|
||||
(begin (define (d w) (+ a (c w)))))
|
||||
\end{code}
|
||||
\begin{example}
|
||||
(define-structure foo (export a c cons)
|
||||
(open scheme)
|
||||
(begin (define a 1)
|
||||
(define (b x) (+ a x))
|
||||
(define (c y) (* (b a) y))))
|
||||
|
||||
(define-structure bar (export d)
|
||||
(open scheme foo)
|
||||
(begin (define (d w) (+ a (c w)))))
|
||||
\end{example}
|
||||
This configuration defines two structures, {\tt foo} and {\tt bar}.
|
||||
{\tt foo} is a view on a package in which the {\tt scheme} structure's
|
||||
bindings (including {\tt define} and {\tt +}) are visible, together
|
||||
|
|
@ -100,18 +97,19 @@ bindings from the {\tt scheme} structure aren't visible unless they
|
|||
become so by {\tt scheme} (or an equivalent structure) being opened.
|
||||
|
||||
|
||||
\subsection*{The configuration language}
|
||||
\section{The configuration language}
|
||||
%\renewcommand{\topfraction}{0.8}
|
||||
|
||||
The configuration language consists of top-level defining forms for
|
||||
modules and interfaces. Its syntax is given in figure~1.
|
||||
modules and interfaces.
|
||||
\T{Its syntax is given in figure~\ref{module-language-figure}.}
|
||||
\W{Its syntax is as follows:}
|
||||
|
||||
\setbox0\hbox{\goesto}
|
||||
\newcommand{\altz}{\hbox to 1\wd0{\hfil\alt}}
|
||||
\T\setbox0\hbox{\goesto}
|
||||
\T\newcommand{\altz}{\hbox to 1\wd0{\hfil\alt}}
|
||||
\W\newcommand{\altz}{\goesto}
|
||||
|
||||
%%%%% Put the figure inside a box ?
|
||||
|
||||
\begin{figure}
|
||||
%\begin{frameit}
|
||||
\begin{figure}[htb]
|
||||
\begin{tabbing}
|
||||
\syn{configuration} \=\goesto{}~\arbno{\syn{definition}} \\
|
||||
\syn{definition} \=\goesto{}~
|
||||
|
|
@ -121,7 +119,7 @@ modules and interfaces. Its syntax is given in figure~1.
|
|||
\arbno{\syn{clause}}) \\
|
||||
\>\altz{}~ \tt(define-interface \syn{name} \syn{interface}) \\
|
||||
\>\altz{}~ \tt(define-syntax \syn{name} \syn{transformer-spec}) \\
|
||||
\syn{clause} \=\goesto{}~ \tt(open \arbno{\syn{name}}) \\
|
||||
\syn{clause} \=\goesto{}~ \tt(open \arbno{\syn{structure}}) \\
|
||||
\>\altz{}~ \tt(access \arbno{\syn{name}}) \\
|
||||
\>\altz{}~ \tt(begin \syn{program}) \\
|
||||
\>\altz{}~ \tt(files \arbno{\syn{filespec}}) \\
|
||||
|
|
@ -130,16 +128,24 @@ modules and interfaces. Its syntax is given in figure~1.
|
|||
\syn{interface} \=\goesto{}~ \tt(export \arbno{\syn{item}}) \\
|
||||
\>\altz{}~ \syn{name} \\
|
||||
\>\altz{}~ \tt(compound-interface \arbno{\syn{interface}}) \\
|
||||
\syn{item} \=\goesto{}~ \syn{name}~
|
||||
\alt{}~ \tt(\syn{name} \syn{type})
|
||||
\alt{}~ \tt((\arbno{\syn{name}}) \syn{type})
|
||||
\syn{item} \=\goesto{}~ \syn{name} \\
|
||||
\>\altz{}~ \tt(\syn{name} \syn{type}) \\
|
||||
\>\altz{}~ \tt((\arbno{\syn{name}}) \syn{type}) \\
|
||||
\syn{structure} \=\goesto{}~ \syn{name} \\
|
||||
\>\altz{}~ \tt(modify \syn{structure} \arbno{\syn{modifier}}) \\
|
||||
\>\altz{}~ \tt(subset \syn{structure} (\arbno{\syn{name}})) \\
|
||||
\>\altz{}~ \tt(with-prefix \syn{structure} \syn{name}) \\
|
||||
\syn{modifier} \=\goesto{}~ \tt(expose \arbno{\syn{name}}) \\
|
||||
\>\altz{}~ \tt(hide \arbno{\syn{name}}) \\
|
||||
\>\altz{}~ \tt(rename \arbno{(\syn{name}$_0$ \syn{name}$_1$)}) \\
|
||||
\>\altz{}~ \tt(alias \arbno{(\syn{name}$_0$ \syn{name}$_1$)}) \\
|
||||
\>\altz{}~ \tt(prefix \syn{name}) \\
|
||||
\end{tabbing}
|
||||
\caption{The configuration language.}
|
||||
%\end{frameit}
|
||||
\end{figure}
|
||||
\label{module-language-figure}
|
||||
|
||||
|
||||
A {\tt define-structure} form introduces a binding of a name to a
|
||||
A \codemainindex{{define-structure}} form introduces a binding of a name to a
|
||||
structure. A structure is a view on an underlying package which is
|
||||
created according to the clauses of the {\tt define-structure} form.
|
||||
Each structure has an interface that specifies which bindings in the
|
||||
|
|
@ -147,31 +153,69 @@ structure's underlying package can be seen via that structure in other
|
|||
packages.
|
||||
|
||||
An {\tt open} clause specifies which structures will be opened up for
|
||||
use inside the new package. At least one package must be specified or
|
||||
else it will be impossible to write any useful programs inside the
|
||||
package, since {\tt define}, {\tt lambda}, {\tt cons}, {\tt
|
||||
structure-ref}, etc.\ will be unavailable. Typical packages to list
|
||||
in the {\tt open} clause are {\tt scheme}, which exports all bindings
|
||||
appropriate to Revised$^5$ Scheme, and {\tt structure-refs}, which
|
||||
exports the {\tt structure-ref} operator (see below). For building
|
||||
structures that export structures, there is a {\tt defpackage} package
|
||||
that exports the operators of the configuration language. Many other
|
||||
structures, such as record and hash table facilities, are also
|
||||
available in the \hack{} implementation.
|
||||
use inside the new package.
|
||||
At least one structure must be specified or else it will be impossible to
|
||||
write any useful programs inside the package, since {\tt define},
|
||||
{\tt lambda}, {\tt cons}, etc.\ will be unavailable.
|
||||
Packages typically include {\tt scheme}, which exports all bindings
|
||||
appropriate to Revised$^5$ Scheme, in an {\tt open} clause.
|
||||
For building structures that export structures, there is a {\tt defpackage}
|
||||
package that exports the operators of the configuration language.
|
||||
Many other structures, such as record and hash table facilities, are also
|
||||
available in the \hack{} implementation.
|
||||
|
||||
An {\tt access} clause specifies which bindings of names to structures
|
||||
will be visible inside the package body for use in {\tt structure-ref}
|
||||
forms. {\tt structure-\ok{}ref} has the following syntax:
|
||||
\begin{tabbing}
|
||||
\qquad \syn{expression} \goesto{}~
|
||||
\tt(structure-ref \syn{struct-name} \syn{name})
|
||||
\end{tabbing}
|
||||
The \syn{struct-name} must be the name of an {\tt access}ed structure,
|
||||
and \syn{name} must be something that the structure exports. Only
|
||||
structures listed in an {\tt access} clause are valid in a {\tt
|
||||
structure-ref}. If a package accesses any structures, it should
|
||||
probably open the {\tt structure-refs} structure so that the {\tt
|
||||
structure-ref} operator itself will be available.
|
||||
The \codemainindex{{modify}}, \codemainindex{{subset}}, and
|
||||
\codemainindex{{prefix}} forms produce new
|
||||
views on existing structures by renaming or hiding exported names.
|
||||
\code{Subset} returns a new structure that exports only the listed names
|
||||
from its \syn{structure} argument.
|
||||
\code{With-prefix} returns a new structure that adds \syn{prefix}
|
||||
to each of the names exported by the \syn{structure} argument.
|
||||
For example, if structure \code{s} exports \code{a} and \code{b},
|
||||
then
|
||||
\begin{example}
|
||||
(subset s (a))
|
||||
\end{example}
|
||||
exports only \code{a} and
|
||||
\begin{example}
|
||||
(with-prefix s p/)
|
||||
\end{example}
|
||||
exports \code{a} as \code{p/a} and \code{b} as \code{p/b}.
|
||||
|
||||
Both \code{subset} and \code{with-prefix} are simple macros that
|
||||
expand into uses of \code{modify}, a more general renaming form.
|
||||
In a \code{modify} structure specification the \syn{command}s are applied to
|
||||
the names exported
|
||||
by \syn{structure} to produce a new set of names for the \syn{structure}'s
|
||||
bindings.
|
||||
\code{Expose} makes only the listed names visible.
|
||||
\code{Hide} makes all but the listed names visible.
|
||||
\code{Rename} makes each \syn{name}$_0$ visible as \syn{name}$_1$
|
||||
name and not visible as \syn{name}$_0$ , while
|
||||
\code{alias} makes each \syn{name}$_0$ visible as both \syn{name}$_0$
|
||||
and \syn{name}$_1$.
|
||||
\code{Prefix} adds \syn{name} to the beginning of each exported name.
|
||||
The modifiers are applied from right to left. Thus
|
||||
\begin{example}
|
||||
(modify scheme (prefix foo/) (rename (car bus))))
|
||||
\end{example}
|
||||
makes \code{car} available as \code{foo/bus}..
|
||||
|
||||
% Use modify instead of structure-ref.
|
||||
%
|
||||
%An {\tt access} clause specifies which bindings of names to structures
|
||||
%will be visible inside the package body for use in {\tt structure-ref}
|
||||
%forms. {\tt structure-\ok{}ref} has the following syntax:
|
||||
%\begin{tabbing}
|
||||
%\qquad \syn{expression} \goesto{}~
|
||||
% \tt(structure-ref \syn{struct-name} \syn{name})
|
||||
%\end{tabbing}
|
||||
%The \syn{struct-name} must be the name of an {\tt access}ed structure,
|
||||
%and \syn{name} must be something that the structure exports. Only
|
||||
%structures listed in an {\tt access} clause are valid in a {\tt
|
||||
%structure-ref}. If a package accesses any structures, it should
|
||||
%probably open the {\tt structure-refs} structure so that the {\tt
|
||||
%structure-ref} operator itself will be available.
|
||||
|
||||
The package's body is specified by {\tt begin} and/or {\tt files}
|
||||
clauses. {\tt begin} and {\tt files} have the same semantics, except
|
||||
|
|
@ -179,11 +223,11 @@ that for {\tt begin} the text is given directly in the package
|
|||
definition, while for {\tt files} the text is stored somewhere in the
|
||||
file system. The body consists of a Scheme program, that is, a
|
||||
sequence of definitions and expressions to be evaluated in order. In
|
||||
practice, I always use {\tt files} in preference to {\tt begin}; {\tt
|
||||
practice, we always use {\tt files} in preference to {\tt begin}; {\tt
|
||||
begin} exists mainly for expository purposes.
|
||||
|
||||
A name's imported binding may be lexically overridden or {\em shadowed}
|
||||
by simply defining the name using a defining form such as {\tt define}
|
||||
by defining the name using a defining form such as {\tt define}
|
||||
or {\tt define-\ok{}syntax}. This will create a new binding without having
|
||||
any effect on the binding in the opened package. For example, one can
|
||||
do {\tt(define car 'chevy)} without affecting the binding of the name
|
||||
|
|
@ -205,7 +249,7 @@ File names in a {\tt files} clause can be symbols, strings, or lists
|
|||
(Maclisp-style ``namelists''). A ``{\tt.scm}'' file type suffix is
|
||||
assumed. Symbols are converted to file names by converting to upper
|
||||
or lower case as appropriate for the host operating system. A
|
||||
namelist is an operating-system-indepedent way to specify a file
|
||||
namelist is an operating-system-independent way to specify a file
|
||||
obtained from a subdirectory. For example, the namelist {\tt(rts
|
||||
record)} specifies the file {\tt record.scm} in the {\tt rts}
|
||||
subdirectory.
|
||||
|
|
@ -217,22 +261,24 @@ was found. You can't at present put an absolute path name in the {\tt
|
|||
files} list.
|
||||
|
||||
|
||||
\subsection*{Interfaces}
|
||||
\section{Interfaces}
|
||||
\codemainindex{{define-interface}}
|
||||
|
||||
An interface can be thought of as the type of a structure. In its
|
||||
basic form it is just a list of variable names, written {\tt(export
|
||||
\var{name} \etc)}. However, in place of
|
||||
a name one may write {\tt(\var{name} \var{type})}, indicating the type
|
||||
of \var{name}'s binding. Currently the type field is ignored, except
|
||||
that exported macros must be indicated with type {\tt :syntax}.
|
||||
\cvar{name} \ldots)}. However, in place of
|
||||
a name one may write {\tt (\cvar{name} \cvar{type})}, indicating the type
|
||||
of \cvar{name}'s binding.
|
||||
The type field is optional, except
|
||||
that exported macros must be indicated with type {\tt :syntax}.
|
||||
|
||||
Interfaces may be either anonymous, as in the example in the
|
||||
introduction, or they may be given names by a {\tt define-interface}
|
||||
form, for example
|
||||
\begin{code}
|
||||
(define-interface foo-interface (export a c cons))
|
||||
(define-structure foo foo-interface \etc)
|
||||
\end{code}
|
||||
\begin{example}
|
||||
(define-interface foo-interface (export a c cons))
|
||||
(define-structure foo foo-interface \ldots)
|
||||
\end{example}
|
||||
In principle, interfaces needn't ever be named. If an interface
|
||||
had to be given at the point of a structure's use as well as at the
|
||||
point of its definition, it would be important to name interfaces in
|
||||
|
|
@ -246,26 +292,28 @@ package definitions when there are multiple distinct structures that
|
|||
have the same interface --- that is, multiple implementations of the
|
||||
same abstraction.
|
||||
|
||||
\item It is conceptually cleaner, and useful for documentation
|
||||
\item It is conceptually cleaner, and often useful for documentation
|
||||
purposes, to separate a module's specification (interface) from its
|
||||
implementation (package).
|
||||
|
||||
\item My experience is that configurations that are separated into
|
||||
\item Our experience is that configurations that are separated into
|
||||
interface definitions and package definitions are easier to read; the
|
||||
long lists of exported bindings just get in the way most of the time.
|
||||
\end{enumerate}
|
||||
|
||||
The {\tt compound-interface} operator forms an interface that is the
|
||||
% The double {{ }} around the index entries are there to help
|
||||
% Hyperlatex sort the index properly.
|
||||
The \codemainindex{{compound-interface}} operator forms an interface that is the
|
||||
union of two or more component interfaces. For example,
|
||||
\begin{code}
|
||||
(define-interface bar-interface
|
||||
(compound-interface foo-interface (export mumble)))
|
||||
\end{code}
|
||||
\begin{example}
|
||||
(define-interface bar-interface
|
||||
(compound-interface foo-interface (export mumble)))
|
||||
\end{example}
|
||||
defines {\tt bar-interface} to be {\tt foo-interface} with the name
|
||||
{\tt mumble} added.
|
||||
{\tt mumble} ad\-ded.
|
||||
|
||||
|
||||
\subsection*{Macros}
|
||||
\section{Macros}
|
||||
|
||||
Hygienic macros, as described in
|
||||
\cite{Clinger-Rees:Macros,Clinger-Rees:R4RS}, are implemented.
|
||||
|
|
@ -274,9 +322,9 @@ expansion are resolved in the environment of the macro's definition.
|
|||
|
||||
For example, the {\tt scheme} structure's {\tt delay} macro
|
||||
is defined by the rewrite rule
|
||||
\begin{code}
|
||||
(delay \var{exp}) \xform (make-promise (lambda () \var{exp}))\rm.
|
||||
\end{code}
|
||||
\begin{example}
|
||||
(delay \cvar{exp}) \xform (make-promise (lambda () \cvar{exp})).
|
||||
\end{example}
|
||||
The variable {\tt make-promise} is defined in the {\tt scheme}
|
||||
structure's underlying package, but is not exported. A use of the
|
||||
{\tt delay} macro, however, always accesses the correct definition
|
||||
|
|
@ -286,28 +334,29 @@ by {\tt scheme}, but their correct bindings will be found even if they
|
|||
are shadowed by definitions in the client package.
|
||||
|
||||
|
||||
\subsection*{Higher-order modules}
|
||||
\section{Higher-order modules}
|
||||
|
||||
There are {\tt define-module} and {\tt define} forms for
|
||||
defining modules that are intended to be instantiated multiple times.
|
||||
But these are pretty kludgey --- for example, compiled code isn't
|
||||
shared between the instantiations --- so I won't describe them yet.
|
||||
shared between the instantiations --- so we won't describe them yet.
|
||||
If you must know, figure it out from the following grammar.
|
||||
\begin{tabbing}
|
||||
\qquad
|
||||
\syn{definition} \=\goesto{}~
|
||||
\tt(d\=\tt{}efine-module (\syn{name} \arbno{(\syn{name} \syn{interface})}) \\
|
||||
\tt(d\=\tt efine-module (\syn{name} \arbno{(\syn{name} \syn{interface})}) \\
|
||||
\> \>\arbno{\syn{definition}} \\
|
||||
\> \>\syn{name}\tt) \\
|
||||
\>\altz{}~ \tt(define \syn{name}
|
||||
(\syn{name} \arbno{\syn{name}}))
|
||||
\end{tabbing}
|
||||
% JAR says: Different instantiations of of a module may see different
|
||||
% definitions of macros and inlines.
|
||||
|
||||
|
||||
\subsection*{Compiling and linking}
|
||||
\section{Compiling and linking}
|
||||
|
||||
\hack{} has a static linker that produces stand-alone heap images
|
||||
from module descriptions. One specifies a particular procedure in a
|
||||
from module descriptions. The programmer specifies a particular procedure in a
|
||||
particular structure to be the image's startup procedure (entry
|
||||
point), and the linker traces dependency links as given by {\tt open}
|
||||
and {\tt access} clauses to determine the composition of the heap
|
||||
|
|
@ -322,7 +371,7 @@ extent of extracting its macro definitions. The compiler knows from
|
|||
the interface of an opened or accessed structure which of its exports
|
||||
are macros. Except for macros, a module may be compiled without any
|
||||
knowledge of the implementation of its opened and accessed structures.
|
||||
However, inter-module optimization will be available as an option.
|
||||
However, inter-module optimization may be available as an option.
|
||||
|
||||
The main difficulty with separate compilation is resolution of
|
||||
auxiliary bindings introduced into macro expansions. The module
|
||||
|
|
@ -333,10 +382,9 @@ or linker needs to know that the desired binding of {\tt make-promise}
|
|||
is the one apparent in {\tt delay}'s defining package, not in the
|
||||
package being loaded or linked.
|
||||
|
||||
[I need to describe structure reification.]
|
||||
%[I need to describe structure reification.]
|
||||
|
||||
|
||||
\subsection*{Semantics of configuration mutation}
|
||||
\section{Semantics of configuration mutation}
|
||||
|
||||
During program development it is often desirable to make changes to
|
||||
packages and interfaces. In static languages it may be necessary to
|
||||
|
|
@ -355,24 +403,24 @@ rule is that variable bindings in a running program are always
|
|||
resolved according to current structure and interface bindings, even
|
||||
when these bindings change as a result of edits to the configuration.
|
||||
For example, consider the following:
|
||||
\begin{code}
|
||||
(define-interface foo-interface (export a c))
|
||||
(define-structure foo foo-interface
|
||||
(open scheme)
|
||||
(begin (define a 1)
|
||||
(define (b x) (+ a x))
|
||||
(define (c y) (* (b a) y))))
|
||||
(define-structure bar (export d)
|
||||
(open scheme foo)
|
||||
(begin (define (d w) (+ (b w) a))))
|
||||
\end{code}
|
||||
\begin{example}
|
||||
(define-interface foo-interface (export a c))
|
||||
(define-structure foo foo-interface
|
||||
(open scheme)
|
||||
(begin (define a 1)
|
||||
(define (b x) (+ a x))
|
||||
(define (c y) (* (b a) y))))
|
||||
(define-structure bar (export d)
|
||||
(open scheme foo)
|
||||
(begin (define (d w) (+ (b w) a))))
|
||||
\end{example}
|
||||
This program has a bug. The variable {\tt b}, which is free in the
|
||||
definition of {\tt d}, has no binding in {\tt bar}'s package. Suppose
|
||||
that {\tt b} was supposed to be exported by {\tt foo}, but was omitted
|
||||
from {\tt foo-interface} by mistake. It is not necessary to
|
||||
re-process {\tt bar} or any of {\tt foo}'s other clients at this point.
|
||||
One need only change {\tt foo-interface} and inform the development
|
||||
system of that one change (using, say, an appropriate Emacs command),
|
||||
system of that change (using, say, an appropriate Emacs command),
|
||||
and {\tt foo}'s binding of {\tt b} will be found when procedure {\tt
|
||||
d} is called.
|
||||
|
||||
|
|
@ -396,7 +444,8 @@ development environment uses caching with cache invalidation to make
|
|||
variable references fast.
|
||||
|
||||
|
||||
\subsection*{Command processor support}
|
||||
\section{Command processor support}
|
||||
\label{module-commands}
|
||||
|
||||
While it is possible to use the \hack{} static linker for program
|
||||
development, it is far more convenient to use the development
|
||||
|
|
@ -411,7 +460,7 @@ borrowed from the Symbolics Lisp Machine system, and is reminiscent of
|
|||
non-Lisp debuggers. Commands are a little easier to type than Scheme
|
||||
forms (no parentheses, so you don't have to shift), but more
|
||||
importantly, making them distinct from Scheme forms ensures that
|
||||
programs' namespaces aren't clutterred with inappropriate bindings.
|
||||
programs' namespaces aren't cluttered with inappropriate bindings.
|
||||
Equivalently, the command set is available for use regardless of what
|
||||
bindings happen to be visible in the current program. This is
|
||||
especially important in conjunction with the module system, which puts
|
||||
|
|
@ -429,44 +478,47 @@ Commands are introduced by a comma ({\tt,}) and end at the end of
|
|||
line. The command processor's prompt consists of the name of the
|
||||
current package followed by a greater-than ({\tt>}).
|
||||
|
||||
\begin{list}{}{}{}
|
||||
\begin{description}
|
||||
\item \code{,open \arbno{\cvar{struct-name}}} \\
|
||||
The {\tt,open} command opens a new structure in the current
|
||||
package, as if the package's definition's {\tt open} clause
|
||||
had listed \cvar{struct-name}.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,config
|
||||
\end{code}
|
||||
\item \code{,config} \\
|
||||
The {\tt,config} command sets the command processor's current
|
||||
package to be the current configuration package. Forms entered at
|
||||
this point are interpreted as being configuration language forms,
|
||||
not Scheme forms.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,config \var{command}
|
||||
\end{code}
|
||||
\item \code{,config \cvar{command}} \\
|
||||
This form of the {\tt,config} command executes another command in
|
||||
the current configuration package. For example,
|
||||
\begin{code}
|
||||
,config ,load foo.scm
|
||||
\end{code}
|
||||
\begin{example}
|
||||
,config ,load foo.scm
|
||||
\end{example}
|
||||
interprets configuration language forms from the file {\tt
|
||||
foo.scm} in the current configuration package.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,in \var{struct-name}
|
||||
\end{code}
|
||||
\item \code{,config-package-is \cvar{struct-name}} \\
|
||||
The {\tt,config-package-is} command designates a new configuration
|
||||
package for use by the {\tt,config} command and resolution of
|
||||
\cvar{struct-name}s for other commands such as {\tt,in} and
|
||||
{\tt,open}. See
|
||||
\link*{below}[Section~\Ref]{config-packages}
|
||||
for information on making new configuration packages.
|
||||
|
||||
\item \code{,in \cvar{struct-name}} \\
|
||||
The {\tt ,in} command moves the command processor to a specified
|
||||
structure's underlying package. For example:
|
||||
\begin{code}
|
||||
user> ,config
|
||||
config> (define-structure foo (export a)
|
||||
(open scheme))
|
||||
config> ,in foo
|
||||
foo> (define a 13)
|
||||
foo> a
|
||||
13
|
||||
\end{code}
|
||||
\begin{example}
|
||||
user> ,config
|
||||
config> (define-structure foo (export a)
|
||||
(open scheme))
|
||||
config> ,in foo
|
||||
foo> (define a 13)
|
||||
foo> a
|
||||
13
|
||||
\end{example}
|
||||
In this example the command processor starts in a package called
|
||||
{\tt user}, but the {\tt ,config} command moves it into the
|
||||
configuration package, which has the name {\tt config}. The {\tt
|
||||
|
|
@ -479,86 +531,72 @@ current package followed by a greater-than ({\tt>}).
|
|||
{\em loaded}, which is accomplished by the {\tt ,load-package}
|
||||
command.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,in \var{struct-name} \var{command}
|
||||
\end{code}
|
||||
\item \code{,in \cvar{struct-name} \cvar{command}} \\
|
||||
This form of the {\tt,in} command executes a single command in the
|
||||
specified package without moving the command processor into that
|
||||
package. Example:
|
||||
\begin{code}
|
||||
,in mumble (cons 1 2)
|
||||
,in mumble ,trace foo
|
||||
\end{code}
|
||||
\begin{example}
|
||||
,in mumble (cons 1 2)
|
||||
,in mumble ,trace foo
|
||||
\end{example}
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,user $[$\var{command}$]$
|
||||
\end{code}
|
||||
\item \code{,user [\cvar{command}]} \\
|
||||
This is similar to the {\tt ,config} and {\tt ,in} commands. It
|
||||
moves to or executes a command in the user package (which is the
|
||||
default package when the \hack{} command processor starts).
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,for-syntax $[$\var{command}$]$
|
||||
\end{code}
|
||||
This is similar to the {\tt ,config} and {\tt ,in} commands. It
|
||||
moves to or executes a command in the current package's ``package
|
||||
for syntax,'' which is the package in which the forms $f$ in
|
||||
{\tt (define-syntax \var{name} $f$)} are evaluated.
|
||||
\item \code{,user-package-is \cvar{name}} \\
|
||||
The {\tt,user-package-is} command designates a new user
|
||||
package for use by the {\tt,user} command.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,load-package \var{struct-name}
|
||||
\end{code}
|
||||
\item \code{,load-package \cvar{struct-name}} \\
|
||||
The {\tt,load-package} command ensures that the specified structure's
|
||||
underlying package's program has been loaded. This
|
||||
consists of (1) recursively ensuring that the packages of any
|
||||
opened or accessed structures are loaded, followed by (2)
|
||||
executing the package's body as specified by its definition's {\tt
|
||||
begin} and {\tt files} forms.
|
||||
% (Note that
|
||||
% commands related to packages, such as \code{load-package}, take structures
|
||||
% as arguments.
|
||||
% This is because packages are usually anonymous while structures are
|
||||
% usually named and each has a unique package associated with it.)
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,reload-package \var{struct-name}
|
||||
\end{code}
|
||||
\item \code{,reload-package \cvar{struct-name}} \\
|
||||
This command re-executes the structure's package's program. It
|
||||
is most useful if the program comes from a file or files, when
|
||||
it will update the package's bindings after mutations to its
|
||||
source file.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,load \var{filespec} \etc
|
||||
\end{code}
|
||||
\item \code{,load \cvar{filespec} \ldots} \\
|
||||
The {\tt,load} command executes forms from the specified file or
|
||||
files in the current package. {\tt,load \var{filespec}} is similar
|
||||
to {\tt(load "\var{filespec}")}
|
||||
files in the current package. {\tt,load \cvar{filespec}} is similar
|
||||
to {\tt(load "\cvar{filespec}")}
|
||||
except that the name {\tt load} needn't be bound in the current
|
||||
package to Scheme's {\tt load} procedure.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,structure \var{name} \var{interface}
|
||||
\end{code}
|
||||
The {\tt,structure} command defines \var{name} in the
|
||||
\item \code{,for-syntax [\cvar{command}]} \\
|
||||
This is similar to the {\tt ,config} and {\tt ,in} commands. It
|
||||
moves to or executes a command in the current package's ``package
|
||||
for syntax,'' which is the package in which the forms $f$ in
|
||||
{\tt (define-syntax \cvar{name} \cvar{f})} are evaluated.
|
||||
|
||||
\item \code{,new-package} \\
|
||||
The {\tt,new-package} command creates a new package, in which only
|
||||
the standard Scheme bindings are visible, and moves the command
|
||||
processor to it.
|
||||
|
||||
\item \code{,structure \cvar{name} \cvar{interface}} \\
|
||||
The {\tt ,structure} command defines \cvar{name} in the
|
||||
configuration package to be a structure with interface
|
||||
\var{interface} based on the current package.
|
||||
\cvar{interface} based on the current package.
|
||||
|
||||
\item
|
||||
\begin{code}
|
||||
,open \arbno{\var{struct-name}}
|
||||
\end{code}
|
||||
The {\tt,open} command opens a new structure in the current
|
||||
package, as if the package's definition's {\tt open} clause
|
||||
had listed \var{struct-name}.
|
||||
|
||||
\end{list}
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subsection*{Configuration packages}
|
||||
\section{Configuration packages}
|
||||
\label{config-packages}
|
||||
|
||||
It is possible to set up multiple configuration packages. The default
|
||||
configuration package opens the following structures:
|
||||
|
|
@ -567,50 +605,77 @@ configuration package opens the following structures:
|
|||
other configuration language keywords, as well as standard types
|
||||
and type constructors ({\tt :syntax}, {\tt :value}, {\tt proc}, etc.).
|
||||
\item {\tt built-in-structures}, which exports structures that are
|
||||
built into the initial \hack{} image; these include {\tt
|
||||
scheme}, {\tt tables}, and {\tt records}.
|
||||
built into the initial \hack{} image; these include
|
||||
{\tt scheme}, {\tt threads}, {\tt tables}, and {\tt records}.
|
||||
\item {\tt more-structures}, which exports additional structures that
|
||||
are available in the development environment; these include
|
||||
{\tt sort}, {\tt random}, and {\tt threads}.
|
||||
are available in the development environment.
|
||||
A complete listing
|
||||
can be found in the definition of \code{more-structures-interface}
|
||||
at the end of the file \code{scheme/more-packages.scm}.
|
||||
\end{itemize}
|
||||
Note that it does not open {\tt scheme}.
|
||||
|
||||
You can define other configuration packages by simply making a package
|
||||
that opens {\tt module-system} and, optionally, {\tt
|
||||
built-in-\ok{}structures}, {\tt more-\ok{}structures}, or other structures that
|
||||
export structures and interfaces.
|
||||
You can define additional configuration packages by making a package
|
||||
that opens {\tt module-\ok{}system} and, optionally,
|
||||
{\tt built-in-\ok{}structures},
|
||||
{\tt more-\ok{}structures}, or other structures that
|
||||
export structures and interfaces.
|
||||
|
||||
For example:
|
||||
\begin{code}
|
||||
> ,config (define-structure foo (export )
|
||||
(open module-system
|
||||
built-in-structures
|
||||
more-structures))
|
||||
> ,in foo
|
||||
foo> (define-structure x (export a b)
|
||||
(open scheme)
|
||||
(files x))
|
||||
foo>
|
||||
\end{code}
|
||||
\begin{example}
|
||||
> ,config (define-structure foo (export)
|
||||
(open module-system
|
||||
built-in-structures
|
||||
more-structures))
|
||||
> ,in foo
|
||||
foo> (define-structure x (export a b)
|
||||
(open scheme)
|
||||
(files x))
|
||||
foo>
|
||||
\end{example}
|
||||
|
||||
\begin{list}{}{}{}
|
||||
\item
|
||||
\begin{code}
|
||||
,config-package-is \var{struct-name}
|
||||
\end{code}
|
||||
The {\tt,config-package-is} command designates a new configuration
|
||||
package for use by the {\tt,config} command and resolution of
|
||||
\var{struct-name}s for other commands such as {\tt,in} and
|
||||
{\tt,open}.
|
||||
\end{list}
|
||||
Unfortunately, the above example does not work.
|
||||
The problem is that every environment in which
|
||||
\code{define-structure} is defined must also have a way to
|
||||
create ``reflective towers'' (a misnomer; a better name would be
|
||||
``syntactic towers'').
|
||||
% JAR says: fix this?
|
||||
A new reflective tower is required whenever a new environment is created for
|
||||
compiling the source code in the package associated with a new structure.
|
||||
The environment's tower is used at compile time for
|
||||
evaluating the \cvar{macro-source} in
|
||||
\begin{example}
|
||||
(define-syntax \cvar{name} \cvar{macro-source})
|
||||
(let-syntax ((\cvar{name} \cvar{macro-source}) \cvar{...}) \cvar{body})
|
||||
\end{example}
|
||||
and so forth.
|
||||
It is a ``tower'' because that environment, in turn, has to say what environment
|
||||
to use if \code{macro-source} itself contains a use of \code{let-syntax}.
|
||||
|
||||
The simplest way to provide a tower maker is to pass on the one used by
|
||||
an existing configuration package.
|
||||
The special form \code{export-reflective-tower} creates an interface
|
||||
that exports a configuration package's tower.
|
||||
The following example uses \code{export-reflective-tower} and
|
||||
the \code{,structure} command to obtain a tower maker and create a new
|
||||
configuration environment.
|
||||
|
||||
\begin{example}
|
||||
> ,config ,structure t (export-reflective-tower-maker)
|
||||
> ,config (define-structure foo (export)
|
||||
(open module-system
|
||||
t
|
||||
built-in-structures
|
||||
more-structures))
|
||||
\end{example}
|
||||
|
||||
\subsection*{Discussion}
|
||||
%Talk about bootstrapping, define-all-operators, and usual-transforms?
|
||||
|
||||
\section{Discussion}
|
||||
|
||||
This module system was not designed as the be-all and end-all of
|
||||
Scheme module systems; it was only intended to help Richard Kelsey and
|
||||
me to organize the \hack{} system. Not only does the module system
|
||||
Scheme module systems; it was only intended to help us
|
||||
organize the \hack{} system. Not only does the module system
|
||||
help avoid name clashes by keeping different subsystems in different
|
||||
namespaces, it has also helped us to tighten up and generalize
|
||||
\hack{}'s internal interfaces. \hack{} is unusual among Lisp
|
||||
|
|
@ -656,7 +721,7 @@ do not generally show up within module bodies, an individual module
|
|||
may be understood by someone who is not familiar with the module
|
||||
system. This is a great aid to code presentation and portability. If
|
||||
a few simple conditions are met (no name conflicts between packages,
|
||||
no use of {\tt structure-ref}, and use of {\tt files} in preference to
|
||||
and use of {\tt files} in preference to
|
||||
{\tt begin}), then a multi-module program can be loaded into a Scheme
|
||||
implementation that does not support the module system. The \hack{}
|
||||
static linker satisfies these conditions, and can therefore run in
|
||||
|
|
@ -685,44 +750,3 @@ modules, which Scheme Xerox considers unimportant.
|
|||
%[Future work: ideas for anonymous structures and more of a module
|
||||
%calculus; dealing with name conflicts; interface subtraction.]
|
||||
|
||||
|
||||
\begin{thebibliography}{10}
|
||||
|
||||
\bibitem{Clinger-Rees:Macros}
|
||||
William Clinger and Jonathan~Rees.
|
||||
\newblock Macros that work.
|
||||
\newblock {\em Principles of Programming Languages}, January 1991.
|
||||
|
||||
\bibitem{Clinger-Rees:R4RS}
|
||||
William Clinger and Jonathan~Rees (editors).
|
||||
\newblock Revised${}^4$ report on the algorithmic language {S}cheme.
|
||||
\newblock {\em LISP Pointers} IV(3):1--55, July-September 1991.
|
||||
|
||||
\bibitem{Curtis-Rauen:Modules}
|
||||
Pavel Curtis and James Rauen.
|
||||
\newblock A module system for Scheme.
|
||||
\newblock {\em ACM Conference on Lisp and Functional Programming,}
|
||||
pages 13--19, 1990.
|
||||
|
||||
\bibitem{MacQueen:Modules}
|
||||
David MacQueen.
|
||||
\newblock Modules for Standard ML.
|
||||
\newblock {\em ACM Conference on Lisp and Functional Programming,}
|
||||
1984.
|
||||
|
||||
\bibitem{Rees-Donald:Program}
|
||||
Jonathan Rees and Bruce Donald.
|
||||
\newblock Program mobile robots in Scheme.
|
||||
\newblock {\em International Conference on Robotics and
|
||||
Automation,} IEEE, 1992.
|
||||
|
||||
\bibitem{Sheldon-Gifford:Static}
|
||||
Mark A.~Sheldon and David K.~Gifford.
|
||||
\newblock Static dependent types for first-class modules.
|
||||
\newblock {\em ACM Conference on Lisp and Functional Programming,}
|
||||
pages 20--29, 1990.
|
||||
|
||||
\end{thebibliography}
|
||||
|
||||
|
||||
\end{document}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,39 @@
|
|||
%% -*-latex-*-
|
||||
%% Navigation menus for the Scheme 48 report.
|
||||
|
||||
\newcommand{\previousnextmenu}{\EmptyP{\HlxBackUrl\HlxForwUrl}{%
|
||||
\EmptyP{\HlxBackUrl}
|
||||
{Previous: \xlink{\HlxBackTitle}{\HlxBackUrl}}
|
||||
{}%
|
||||
\EmptyP{\HlxForwUrl}
|
||||
{\EmptyP{\HlxBackUrl}{{} | {}}{}%
|
||||
Next: \xlink{\HlxForwTitle}{\HlxForwUrl}}
|
||||
{}%
|
||||
}{}}
|
||||
|
||||
\newcommand{\toppanel}{%
|
||||
{\em Scheme 48 Manual} | {\link{Contents}{top_node}}%
|
||||
\EmptyP{\HlxUpUrl}
|
||||
{{} | In Chapter: \xlink{\HlxUpTitle}{\HlxUpUrl}}
|
||||
{}%
|
||||
\\%
|
||||
\previousnextmenu}
|
||||
|
||||
\newcommand{\chaptertoppanel}{%
|
||||
{\em Scheme 48 Manual} | {\link{Contents}{top_node}}%
|
||||
\EmptyP{\HlxPrevUrl}
|
||||
{{} | Previous Chapter: \xlink{\HlxPrevTitle}{\HlxPrevUrl}}
|
||||
{}%
|
||||
\EmptyP{\HlxNextUrl}
|
||||
{{} | Next Chapter: \xlink{\HlxNextTitle}{\HlxNextUrl}}
|
||||
{}%
|
||||
\\%
|
||||
\previousnextmenu{}}
|
||||
|
||||
\newcommand{\bottommatter}{%
|
||||
%\htmlrule
|
||||
\html{P}
|
||||
\EmptyP{\HlxAddress}
|
||||
{\par{}\html{ADDRESS}\HlxAddress\html{/ADDRESS}\\}{}}
|
||||
|
||||
\newcommand{\bottompanel}{\previousnextmenu}
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
%%
|
||||
%% LaTeX style to for manual index.
|
||||
%%
|
||||
\NeedsTeXFormat{LaTeX2e}
|
||||
|
||||
\ProvidesPackage{myindex}
|
||||
|
||||
% \reallyindex{SORTKEY}{HEADCS}{TYPE}
|
||||
% writes (index-entry "SORTKEY" "HEADCS" TYPE PAGENUMBER)
|
||||
% which becomes \item \HEADCS{SORTKEY} mainpagenumber ; auxpagenumber ...
|
||||
|
||||
\newcommand{\mainschindex}[1]{\index{#1!tt!main}}
|
||||
\newcommand{\mainindex}[1]{\index{#1!rm!main}}
|
||||
\newcommand{\schindex}[1]{\index{#1!tt!aux}}
|
||||
\newcommand{\sharpindex}[1]{\index{#1!sharp!aux}}
|
||||
|
||||
\newcommand{\codemainindex}[1]{{\mainschindex{{#1}}\code{#1}}}
|
||||
\newcommand{\codeindex}[1]{{\schindex{#1}\code{#1}}}
|
||||
|
||||
\newenvironment{myindex}
|
||||
{\if@twocolumn
|
||||
\@restonecolfalse
|
||||
\else
|
||||
\@restonecoltrue
|
||||
\fi
|
||||
\columnseprule \z@
|
||||
%!! \columnsep 35\p@
|
||||
\twocolumn[\@makeschapterhead{\indexname}]%
|
||||
\@mkboth{\MakeUppercase\indexname}%
|
||||
{\MakeUppercase\indexname}%
|
||||
\thispagestyle{plain}\parindent\z@
|
||||
\parskip\z@ \@plus .3\p@\relax
|
||||
\let\item\@idxitem}
|
||||
{\if@restonecol\onecolumn\else\clearpage\fi}
|
||||
\renewcommand\@idxitem{\par\hangindent 40\p@}
|
||||
\renewcommand\subitem{\@idxitem \hspace*{20\p@}}
|
||||
\renewcommand\subsubitem{\@idxitem \hspace*{30\p@}}
|
||||
\renewcommand\indexspace{\par \vskip 10\p@ \@plus5\p@ \@minus3\p@\relax}
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,192 @@
|
|||
% Scheme 48 documentation
|
||||
|
||||
\documentclass[twoside]{report}
|
||||
\usepackage{hyperlatex}
|
||||
\T\usepackage{longtable}
|
||||
\T\usepackage{myindex}
|
||||
\W\include{latex-index}
|
||||
|
||||
\W\include{my-sequential}
|
||||
\include{proto}
|
||||
\include{hacks}
|
||||
|
||||
% Make a few big HTML files, and not a lot of small ones.
|
||||
\setcounter{htmldepth}{3}
|
||||
|
||||
% Put the html code in its own directory.
|
||||
\htmldirectory{manual}
|
||||
|
||||
% Set the html base name.
|
||||
\htmlname{s48manual}
|
||||
|
||||
% Add sections to main menu
|
||||
\setcounter{htmlautomenu}{2}
|
||||
|
||||
% White background
|
||||
\htmlattributes{BODY}{BGCOLOR="#ffffff"}
|
||||
|
||||
\htmltitle{Scheme 48 Manual}
|
||||
|
||||
% Suppress navigation panel for first page.
|
||||
\htmlpanel{0}
|
||||
|
||||
%%% End preamble
|
||||
|
||||
\begin{document}
|
||||
\label{top_node}
|
||||
|
||||
\section{Optimistic concurrency}
|
||||
|
||||
A \cvar{proposal} is a record of reads from and and writes to locations in
|
||||
memory.
|
||||
The \cvar{logging} operations listed below record any values read or
|
||||
written in the current proposal.
|
||||
A reading operation, such as \code{provisional-vector-ref}, first checks to
|
||||
see if the current proposal contains a value for the relevent location.
|
||||
If so, that value is returned as the result of the read.
|
||||
If not, the current contents of the location are stored in the proposal and
|
||||
then returned as the result of the read.
|
||||
A logging write to a location stores the new value as the current contents of
|
||||
the location in the current proposal; the contents of the location itself
|
||||
remain unchanged.
|
||||
|
||||
\cvar{Committing} to a proposal verifies that any reads logged in
|
||||
the proposal are still valid and, if so, performs any writes that
|
||||
the proposal contains.
|
||||
A logged read is valid if, at the time of the commit, the location contains
|
||||
the same value it had at the time of the original read (note that this does
|
||||
not mean that no change occured, simply that the value now is the same as
|
||||
the value then).
|
||||
If a proposal has an invalid read then the effort to commit fails no change
|
||||
is made to the value of any location.
|
||||
|
||||
\begin{protos}
|
||||
\proto{ensure-atomicity}{ thunk}{value(s)}
|
||||
\protonoresult{ensure-atomicity!}{ thunk}
|
||||
\end{protos}
|
||||
\noindent
|
||||
If there is a proposal in place
|
||||
\code{ensure-atomicity} and \code{ensure-atomicity!}
|
||||
simply make a (tail-recursive) call to \cvar{thunk}.
|
||||
If the current proposal is \code{\#f} they create a new proposal,
|
||||
install it, call \cvar{thunk}, and then try to commit to the proposal.
|
||||
This process repeats, with a new proposal on each iteration, until
|
||||
the commit succeeds.
|
||||
\code{Ensure-atomicity} returns whatever values are returned by \cvar{thunk}
|
||||
on its final invocation, while \code{ensure-atomicity!} discards any such
|
||||
values and returns nothing.
|
||||
|
||||
\begin{protos}
|
||||
\proto{provisional-car}{ pair}{value}
|
||||
\proto{provisional-cdr}{ pair}{value}
|
||||
\protonoresult{provisional-set-car!}{ pair value}
|
||||
\protonoresult{provisional-set-cdr!}{ pair value}
|
||||
\proto{provisional-cell-ref}{ cell}{value}
|
||||
\protonoresult{provisional-cell-set!}{ cell value}
|
||||
\proto{provisional-vector-ref}{ vector i}{value}
|
||||
\protonoresult{provisional-vector-set!}{ vector i value}
|
||||
\proto{provisional-string-ref}{ vector i}{char}
|
||||
\protonoresult{provisional-string-set!}{ vector i char}
|
||||
\proto{provisional-byte-vector-ref}{ vector i}{k}
|
||||
\protonoresult{provisional-byte-vector-set!}{ vector i k}
|
||||
\end{protos}
|
||||
\noindent
|
||||
These are all logging versions of their Scheme counterparts.
|
||||
Reads are checked when the current proposal is committed and writes are
|
||||
delayed until the commit succeeds.
|
||||
If the current proposal is \code{\#f} these perform exactly as their Scheme
|
||||
counterparts.
|
||||
|
||||
The following implementation of a simple counter may not function
|
||||
if used by multiple threads.
|
||||
\begin{example}
|
||||
(define (make-counter)
|
||||
(let ((value 0))
|
||||
(lambda ()
|
||||
(set! value (+ value 1))
|
||||
value)))
|
||||
\end{example}
|
||||
|
||||
Here is the same procedure using a proposal to ensure that each
|
||||
increment operation happens atomically.
|
||||
The value of the counter is kept in a vector to allow the use of
|
||||
logging operations.
|
||||
\begin{example}
|
||||
(define (make-counter)
|
||||
(let ((value (make-cell 0)))
|
||||
(lambda ()
|
||||
(ensure-atomicity
|
||||
(lambda ()
|
||||
(let ((v (+ (provisional-cell-ref value)
|
||||
1)))
|
||||
(provisional-cell-set! value v)
|
||||
v))))))
|
||||
\end{example}
|
||||
|
||||
Because \code{ensure-atomicity} creates a new proposal only if there is
|
||||
no existing proposal in place, multiple atomic actions can be performed
|
||||
simultaneously.
|
||||
The following procedure increments an arbitrary number of counters at the same
|
||||
time.
|
||||
This works even if the same counter appears multiple times;
|
||||
\code{(step-counters! c0 c0)} would add two to the value of counter \code{c0}.
|
||||
\begin{example}
|
||||
(define (step-counters! . counters)
|
||||
(ensure-atomicity
|
||||
(lambda ()
|
||||
(for-each (lambda (counter)
|
||||
(counter))
|
||||
counters))))
|
||||
\end{example}
|
||||
|
||||
\begin{example}
|
||||
(define-synchronized-record-type \cvar{tag} \cvar{type-name}
|
||||
(\cvar{constructor-name} \cvar{field-tag} \ldots)
|
||||
[(\cvar \cvar{field-tag} \ldots)]
|
||||
\cvar{predicate-name}
|
||||
(\cvar{field-tag} \cvar{accessor-name} [\cvar{modifier-name}])
|
||||
\ldots)
|
||||
\end{example}
|
||||
This is the same as \code{define-record-type} except all field reads and
|
||||
writes are logged in the current proposal.
|
||||
If the optional list of field tags is present then only those fields will
|
||||
be logged.
|
||||
|
||||
\begin{protos}
|
||||
\proto{atomically}{ thunk}{value(s)}
|
||||
\protonoresult{atomically!}{ thunk}
|
||||
\end{protos}
|
||||
\noindent
|
||||
\code{Atomically} and \code{atomically!} are identical
|
||||
to \code{ensure-atomicity} and \code{ensure-atomicity!} except that they
|
||||
always install a new proposal before calling \code{thunk}.
|
||||
The current proposal is saved and then restored after \code{thunk} returns.
|
||||
\code{Atomically} and \code{atomically!} are useful if \code{thunk} contains
|
||||
code that should not be combined with any other operation (example?).
|
||||
|
||||
The following procedures give access to the low-leve proposal mechanism for
|
||||
use when necessary.
|
||||
\begin{protos}
|
||||
\proto{make-proposal}{}{proposal}
|
||||
\proto{current-proposal}{}{proposal}
|
||||
\protonoresult{set-current-proposal!}{ proposal}
|
||||
\proto{with-proposal}{ proposal thunk}{value(s)}
|
||||
\proto{maybe-commit}{ proposal}{boolean}
|
||||
\end{protos}
|
||||
\noindent
|
||||
\code{With-proposal} saves the current proposal, installs \cvar{proposal} as
|
||||
the current proposal, and then calls \cvar{thunk}.
|
||||
When \cvar{thunk} returns the saved proposal is reinstalled as the current
|
||||
proposal
|
||||
and the value(s) returned by \cvar{thunk} are returned.
|
||||
|
||||
\code{Maybe-commit} verifies that any reads logged in \cvar{proposal} are
|
||||
still valid and, if so, performs any writes that \cvar{proposal} contains.
|
||||
A logged read is valid if, at the time of the commit, the location contains
|
||||
the same value it had at the time of the original read (note that this does
|
||||
not mean that no change occured, simply that the value now is the same as
|
||||
the value then).
|
||||
\code{Maybe-commit} returns \code{\#t} if the commit succeeds and \code{\#f}
|
||||
if it fails.
|
||||
|
||||
\end{document}
|
||||
|
|
@ -22,8 +22,11 @@
|
|||
% The following is for prototypes that have return types.
|
||||
% (foo int int) -> int
|
||||
|
||||
\newcommand{\proto}[3]{\item\noindent\unskip%
|
||||
\cindex{\code{#1}}%
|
||||
\newcommand{\proto}[3]{%
|
||||
\protonoindex{{#1}}{{#2}}{{#3}}%
|
||||
\mainschindex{{#1}}}%
|
||||
|
||||
\newcommand{\protonoindex}[3]{\item\noindent\unskip%
|
||||
\hbox{\spaceskip=0.5em\code{({#1}{\it#2\/})} {$\rightarrow$} {\it#3}}}
|
||||
|
||||
\newcommand{\cproto}[1]{\item\noindent\unskip%
|
||||
|
|
@ -33,26 +36,40 @@
|
|||
\hbox{\spaceskip=0.5em\code{{#1}}}\hfill\penalty 0%
|
||||
\hbox{ }\nobreak\hfill\hbox{\rm (may GC)}}
|
||||
|
||||
\newcommand{\protonoresult}[2]{\item\noindent\unskip%
|
||||
\newcommand{\protonoresultnoindex}[2]{\item\noindent\unskip%
|
||||
\hbox{\spaceskip=0.5em\code{(\hbox{#1}{\it#2\/})}}}
|
||||
|
||||
\newcommand{\protonoresult}[2]{%
|
||||
\protonoresultnoindex{{#1}}{{#2}}%
|
||||
\mainschindex{{#1}}}%
|
||||
|
||||
\newcommand{\protoresult}[1]{\newline\unskip%
|
||||
{\hspace*{2em}\code{{$\rightarrow$} {\it#1}}\hfill}}
|
||||
|
||||
% Syntax prototypes
|
||||
|
||||
\newcommand{\syntaxprotonoresult}[2]{\item\noindent\unskip%
|
||||
\newcommand{\syntaxprotonoresultnoindex}[2]{\item\noindent\unskip%
|
||||
\hbox{\spaceskip=0.5em\code{(\hbox{#1}{#2})}}\hfill\penalty 0%
|
||||
\hbox{ }\nobreak\hfill\hbox{\rm syntax}}
|
||||
|
||||
\newcommand{\syntaxproto}[3]{\syntaxprotonoresult{#1}{#2}%
|
||||
\hspace*{24pt}{$\rightarrow$} {\it#3}}
|
||||
\newcommand{\syntaxprotonoresult}[2]{%
|
||||
\syntaxprotonoresultnoindex{{#1}}{{#2}}\mainschindex{{#1}}}
|
||||
|
||||
\newcommand{\syntaxproto}[3]{\item\noindent\unskip%
|
||||
\hbox{\spaceskip=0.5em\code{(\hbox{#1}{#2})}} {$\rightarrow$} {\it#3}%
|
||||
\hfill\penalty 0%
|
||||
\hbox{ }\nobreak\hfill\hbox{\rm syntax}}
|
||||
|
||||
% This can be reduced
|
||||
|
||||
\newcommand{\pconstproto}[2]{\item\noindent\unskip%
|
||||
\hbox{\spaceskip=0.5em#1}\code\hfill\penalty 0%
|
||||
\hbox{\spaceskip=0.5em\code{#1}}\hfill\penalty 0%
|
||||
\hbox{ }\nobreak\hfill\hbox{\rm #2}}
|
||||
|
||||
% Variable prototype
|
||||
\newcommand{\constproto}[2]{\pconstproto{#1}{#2}}
|
||||
\newcommand{\constproto}[2]{\pconstproto{{#1}}{{#2}}\mainschindex{{#1}}}
|
||||
|
||||
\newcommand{\constprotonoindex}[2]{\pconstproto{{#1}}{{#2}}}
|
||||
|
||||
}
|
||||
%%%%%%%%%%%%%%%% end of Latex proto definitions
|
||||
|
|
@ -64,17 +81,30 @@
|
|||
% The following is for prototypes that have return types.
|
||||
% (foo int int) -> int
|
||||
|
||||
\newcommand{\proto}[3]{%
|
||||
\newcommand{\protonoindex}[3]{%
|
||||
%\cindex{\code{#1}}%
|
||||
\item\noindent\code{({#1}{\var{#2}\/})~-->~{\var{#3}}}}
|
||||
|
||||
\newcommand{\protonoresult}[2]{%
|
||||
\newcommand{\proto}[3]{%
|
||||
\protonoindex{{#1}}{{#2}}{{#3}}%
|
||||
\mainschindex{{#1}}}%
|
||||
|
||||
\newcommand{\protonoresultnoindex}[2]{%
|
||||
%\cindex{\code{#1}}%
|
||||
\item\noindent\code{({#1}{\var{#2}\/})}}
|
||||
|
||||
\newcommand{\constproto}[2]{%
|
||||
\newcommand{\protonoresult}[2]{%
|
||||
\protonoresultnoindex{{#1}}{{#2}}%
|
||||
\mainschindex{{#1}}}%
|
||||
|
||||
\newcommand{\pconstproto}[2]{%
|
||||
\item\noindent\prototagstart\code{{#1}}\prototag{{#2}}}
|
||||
|
||||
% Variable prototype
|
||||
\newcommand{\constproto}[2]{\pconstproto{{#1}}{{#2}}\mainschindex{{#1}}}
|
||||
|
||||
\newcommand{\constprotonoindex}[2]{\pconstproto{{#1}}{{#2}}}
|
||||
|
||||
\newcommand{\cproto}[1]{%
|
||||
\item\noindent\code{{#1}}}
|
||||
|
||||
|
|
@ -82,8 +112,17 @@
|
|||
\item\noindent\prototagstart\code{{#1}}\prototag{(may GC)}}
|
||||
|
||||
\newcommand{\syntaxprotonoresult}[2]{%
|
||||
\syntaxprotonoresultnoindex{{#1}}{{#2}}\mainschindex{{#1}}}
|
||||
|
||||
\newcommand{\syntaxprotonoresultnoindex}[2]{%
|
||||
\item\noindent\prototagstart\code{({#1}{#2})}\prototag{syntax}}
|
||||
|
||||
\newcommand{\protoresult}[1]{%
|
||||
\\{}\noindent\code{\ \ \ \ -->~{\it{#1}}}}
|
||||
|
||||
\newcommand{\syntaxproto}[3]{%
|
||||
\item\noindent\prototagstart\code{({#1}{#2})~-->~{\var{#3}}}\prototag{syntax}}
|
||||
|
||||
\newcommand{\prototagstart}{%
|
||||
\begin{rawhtml}<table border=0 cellspacing=0 cellpadding=0 width=80%>
|
||||
<tr> <td>\end{rawhtml}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,255 @@
|
|||
|
||||
\chapter{threads}
|
||||
|
||||
safety (and the lack thereof)
|
||||
|
||||
\section{Creating and controlling threads}
|
||||
|
||||
\begin{protos}
|
||||
\proto{spawn}{ thunk}{thread}
|
||||
\proto{spawn}{ thunk name}{thread}
|
||||
\proto{thread?}{ thing}{boolean}
|
||||
\proto{thread-name}{ thread}{name}
|
||||
\proto{thread-uid}{ thread}{integer}
|
||||
\protonoresult{relinquish-timeslice}{}
|
||||
\protonoresult{sleep}{ time-in-?}
|
||||
\protonoresult{terminate-current-thread}{}
|
||||
\end{protos}
|
||||
|
||||
\section{Debugging multithreaded programs}
|
||||
|
||||
Debugging multithreaded programs can be difficult.
|
||||
|
||||
As described in {section whatever}, when any thread raises an
|
||||
error, Scheme~48 stops running all of the threads at that command level.
|
||||
|
||||
The following procedure is useful in debugging multi-threaded programs.
|
||||
\begin{protos}
|
||||
\protonoresult{debug-message}{ element$_0$ \ldots}
|
||||
\end{protos}
|
||||
\code{Debug-message} prints the elements to `\code{stderr}', followed by a
|
||||
newline.
|
||||
The only types of values that \code{debug-message} prints in full are small
|
||||
integers (fixnums), strings, characters, symbols, boolean, and the empty list.
|
||||
Values of other types are abbreviated as follows.
|
||||
|
||||
\begin{tabular}{ll}
|
||||
pair & \code{(...)}\\
|
||||
vector & \code{\#(...)}\\
|
||||
procedure & \code{\#\{procedure\}}\\
|
||||
record & \code{\#\{<name of record type>\}}\\
|
||||
all others & \code{???}\\
|
||||
\end{tabular}
|
||||
|
||||
The great thing about \code{debug-message} is that it bypasses Scheme~48's
|
||||
I/O and thread handling.
|
||||
The message appears immediately, with no delays
|
||||
or errors.
|
||||
|
||||
\code{Debug-message} is exported by the structure \code{debug-messages}.
|
||||
|
||||
\section{Mutual exclusion}
|
||||
|
||||
locks
|
||||
|
||||
make-lock
|
||||
lock?
|
||||
obtain-lock
|
||||
maybe-obtain-lock
|
||||
release-lock
|
||||
|
||||
\begin{protos}
|
||||
\proto{make-lock}{ }{lock}
|
||||
\proto{lock?}{ thing}{boolean}
|
||||
\protonoresult{obtain-lock}{ lock}
|
||||
\proto{maybe-obtain-lock}{ lock}{boolean}
|
||||
\protonoresult{release-lock}{ lock}
|
||||
\end{protos}
|
||||
|
||||
|
||||
condition variables
|
||||
% these require proposals
|
||||
|
||||
(make-condvar [id]) -> condvar
|
||||
|
||||
% add condvar?
|
||||
|
||||
(maybe-commit-and-wait-for-condvar condvar) -> boolean
|
||||
(maybe-commit-and-set-condvar! condvar value)
|
||||
(condvar-has-value? condvar) -> boolean
|
||||
(set-condvar-value! condvar boolean)
|
||||
(condvar-value condvar) -> value
|
||||
(set-condvar-value! condvar value)
|
||||
|
||||
placeholders
|
||||
|
||||
make-placeholder
|
||||
placeholder?
|
||||
placeholder-value
|
||||
placeholder-set!
|
||||
|
||||
\section{Optimistic concurrency}
|
||||
|
||||
%add an overview
|
||||
|
||||
A \cvar{proposal} is a record of reads from and and writes to locations in
|
||||
memory.
|
||||
The \cvar{logging} operations listed below record any values read or
|
||||
written in the current proposal.
|
||||
A reading operation, such as \code{provisional-vector-ref}, first checks to
|
||||
see if the current proposal contains a value for the relevent location.
|
||||
If so, that value is returned as the result of the read.
|
||||
If not, the current contents of the location are stored in the proposal and
|
||||
then returned as the result of the read.
|
||||
A logging write to a location stores the new value as the current contents of
|
||||
the location in the current proposal; the contents of the location itself
|
||||
remain unchanged.
|
||||
|
||||
\cvar{Committing} to a proposal verifies that any reads logged in
|
||||
the proposal are still valid and, if so, performs any writes that
|
||||
the proposal contains.
|
||||
A logged read is valid if, at the time of the commit, the location contains
|
||||
the same value it had at the time of the original read (note that this does
|
||||
not mean that no change occured, simply that the value now is the same as
|
||||
the value then).
|
||||
If a proposal has an invalid read then the effort to commit fails no change
|
||||
is made to the value of any location.
|
||||
The verifications and subsequent writes to memory are performed atomically
|
||||
with respect to other proposal commit attempts.
|
||||
% Explain better. Add an example?
|
||||
|
||||
\begin{protos}
|
||||
\proto{ensure-atomicity}{ thunk}{value(s)}
|
||||
\protonoresult{ensure-atomicity!}{ thunk}
|
||||
\end{protos}
|
||||
\noindent
|
||||
If there is a proposal in place
|
||||
\code{ensure-atomicity} and \code{ensure-atomicity!}
|
||||
simply make a (tail-recursive) call to \cvar{thunk}.
|
||||
If the current proposal is \code{\#f} they create a new proposal,
|
||||
install it, call \cvar{thunk}, and then try to commit to the proposal.
|
||||
This process repeats, with a new proposal on each iteration, until
|
||||
the commit succeeds.
|
||||
\code{Ensure-atomicity} returns whatever values are returned by \cvar{thunk}
|
||||
on its final invocation, while \code{ensure-atomicity!} discards any such
|
||||
values and returns nothing.
|
||||
|
||||
\begin{protos}
|
||||
\proto{provisional-car}{ pair}{value}
|
||||
\proto{provisional-cdr}{ pair}{value}
|
||||
\protonoresult{provisional-set-car!}{ pair value}
|
||||
\protonoresult{provisional-set-cdr!}{ pair value}
|
||||
\proto{provisional-cell-ref}{ cell}{value}
|
||||
\protonoresult{provisional-cell-set!}{ cell value}
|
||||
\proto{provisional-vector-ref}{ vector i}{value}
|
||||
\protonoresult{provisional-vector-set!}{ vector i value}
|
||||
\proto{provisional-string-ref}{ vector i}{char}
|
||||
\protonoresult{provisional-string-set!}{ vector i char}
|
||||
\proto{provisional-byte-vector-ref}{ vector i}{k}
|
||||
\protonoresult{provisional-byte-vector-set!}{ vector i k}
|
||||
\end{protos}
|
||||
\noindent
|
||||
These are all logging versions of their Scheme counterparts.
|
||||
Reads are checked when the current proposal is committed and writes are
|
||||
delayed until the commit succeeds.
|
||||
If the current proposal is \code{\#f} these perform exactly as their Scheme
|
||||
counterparts.
|
||||
|
||||
The following implementation of a simple counter may not function properly
|
||||
when used by multiple threads.
|
||||
\begin{example}
|
||||
(define (make-counter)
|
||||
(let ((value 0))
|
||||
(lambda ()
|
||||
(set! value (+ value 1))
|
||||
value)))
|
||||
\end{example}
|
||||
|
||||
Here is the same procedure using a proposal to ensure that each
|
||||
increment operation happens atomically.
|
||||
The value of the counter is kept in a
|
||||
\link*{cell}[cell (see section~\Ref]{cells}
|
||||
to allow the use of
|
||||
logging operations.
|
||||
\begin{example}
|
||||
(define (make-counter)
|
||||
(let ((value (make-cell 0)))
|
||||
(lambda ()
|
||||
(ensure-atomicity
|
||||
(lambda ()
|
||||
(let ((v (+ (provisional-cell-ref value)
|
||||
1)))
|
||||
(provisional-cell-set! value v)
|
||||
v))))))
|
||||
\end{example}
|
||||
|
||||
Because \code{ensure-atomicity} creates a new proposal only if there is
|
||||
no existing proposal in place, multiple atomic actions can be performed
|
||||
simultaneously.
|
||||
The following procedure increments an arbitrary number of counters at the same
|
||||
time.
|
||||
This works even if the same counter appears multiple times;
|
||||
\code{(step-counters! c0 c0)} would add two to the value of counter \code{c0}.
|
||||
\begin{example}
|
||||
(define (step-counters! . counters)
|
||||
(ensure-atomicity
|
||||
(lambda ()
|
||||
(for-each (lambda (counter)
|
||||
(counter))
|
||||
counters))))
|
||||
\end{example}
|
||||
|
||||
\begin{example}
|
||||
(define-synchronized-record-type \cvar{tag} \cvar{type-name}
|
||||
(\cvar{constructor-name} \cvar{field-tag} \ldots)
|
||||
[(\cvar \cvar{field-tag} \ldots)]
|
||||
\cvar{predicate-name}
|
||||
(\cvar{field-tag} \cvar{accessor-name} [\cvar{modifier-name}])
|
||||
\ldots)
|
||||
\end{example}
|
||||
This is the same as \code{define-record-type}
|
||||
except all field reads and
|
||||
writes are logged in the current proposal.
|
||||
If the optional list of field tags is present then only those fields will
|
||||
be logged.
|
||||
|
||||
\begin{protos}
|
||||
\proto{atomically}{ thunk}{value(s)}
|
||||
\protonoresult{atomically!}{ thunk}
|
||||
\end{protos}
|
||||
\noindent
|
||||
\code{Atomically} and \code{atomically!} are identical
|
||||
to \code{ensure-atomicity} and \code{ensure-atomicity!} except that they
|
||||
always install a new proposal before calling \code{thunk}.
|
||||
The current proposal is saved and then restored after \code{thunk} returns.
|
||||
\code{Atomically} and \code{atomically!} are useful if \code{thunk} contains
|
||||
code that should not be combined with any other operation (example?).
|
||||
|
||||
The following procedures give access to the low-level proposal mechanism.
|
||||
\begin{protos}
|
||||
\proto{make-proposal}{}{proposal}
|
||||
\proto{current-proposal}{}{proposal}
|
||||
\protonoresult{set-current-proposal!}{ proposal}
|
||||
\proto{with-proposal}{ proposal thunk}{value \ldots}
|
||||
\proto{maybe-commit}{ proposal}{boolean}
|
||||
\end{protos}
|
||||
\noindent
|
||||
\code{Make-proposal} creates a new proposal.
|
||||
\code{Current-proposal} and \code{set-current-proposal} access and set
|
||||
the current thread's proposal.
|
||||
It is an error to pass to \code{set-current-proposal!} a proposal that
|
||||
is already in use.
|
||||
\code{With-proposal} saves the current proposal, installs \cvar{proposal} as
|
||||
the current proposal, and then calls \cvar{thunk}.
|
||||
When \cvar{thunk} returns the saved proposal is reinstalled as the current
|
||||
proposal
|
||||
and the value(s) returned by \cvar{thunk} are returned.
|
||||
|
||||
\code{Maybe-commit} verifies that any reads logged in \cvar{proposal} are
|
||||
still valid and, if so, performs any writes that \cvar{proposal} contains.
|
||||
A logged read is valid if, at the time of the commit, the location read contains
|
||||
the same value it had at the time of the original read (note that this does
|
||||
not mean that no change occured, simply that the value now is the same as
|
||||
the value then).
|
||||
\code{Maybe-commit} returns \code{\#t} if the commit succeeds and \code{\#f}
|
||||
if it fails.
|
||||
|
|
@ -0,0 +1,444 @@
|
|||
|
||||
\chapter{User's guide}
|
||||
|
||||
This chapter details Scheme~48's user interface: its command-line arguments,
|
||||
command processor, debugger, and so forth.
|
||||
|
||||
\section{Command line arguments}
|
||||
|
||||
A few command line arguments are processed by Scheme~48 as
|
||||
it starts up.
|
||||
|
||||
\code{scheme48}
|
||||
[\code{-i} \cvar{image}]
|
||||
[\code{-h} \cvar{heapsize}]
|
||||
% [\code{-s} \cvar{stacksize}]
|
||||
[\code{-a} \cvar{argument \ldots}]
|
||||
|
||||
\begin{description}
|
||||
\item[{\tt -i} \cvar{image}]
|
||||
specifies a heap image file to resume. This defaults to a heap
|
||||
image that runs a Scheme command processor. Heap images are
|
||||
created by the \code{,dump} and \code{,build commands}, for which see below.
|
||||
|
||||
\item[{\tt -h} \cvar{heapsize}]
|
||||
specifies how much space should be reserved for allocation.
|
||||
\cvar{Heapsize} is in words (where one word = 4 bytes), and covers both
|
||||
semispaces, only one of which is in use at any given time (except
|
||||
during garbage collection). Cons cells are currently 3 words, so
|
||||
if you want to make sure you can allocate a million cons cells,
|
||||
you should specify \code{-h 6000000} (actually somewhat more than this,
|
||||
to account for the initial heap image and breathing room).
|
||||
The default heap size is 3000000 words. The system will use a
|
||||
larger heap if the specified (or default) size is less than
|
||||
the size of the image being resumed.
|
||||
|
||||
%\item[{\tt -s} \cvar{stacksize}]
|
||||
% specifies how much space should be reserved for the continuation
|
||||
% and environment stack. If this space is exhausted, continuations
|
||||
% and environments are copied to the heap. \cvar{Stacksize} is in words
|
||||
% and defaults to 2500.
|
||||
|
||||
\item[{\tt -a} \cvar{argument \ldots}]
|
||||
is only useful with images built using \code{,build}.
|
||||
The arguments are passed as a list of strings to the procedure specified
|
||||
in the \code{,build} command as for example:
|
||||
\begin{example}
|
||||
> (define (f a) (for-each display a) (newline) 0)
|
||||
> ,build f foo.image
|
||||
> ,exit
|
||||
\% scheme48vm -i foo.image -a mumble "foo x"
|
||||
mumblefoo x
|
||||
\%
|
||||
\end{example}
|
||||
\end{description}
|
||||
|
||||
The usual definition of the \code{s48} or \code{scheme48} command is actually a
|
||||
shell script that starts up the Scheme~48 virtual machine with a
|
||||
\code{-i \cvar{imagefile}}
|
||||
specifying the development environment heap image and a
|
||||
\code{-o \cvar{vm-executable}} specifying the location of the virtual-machine
|
||||
executable (the executable is needed for loading external code on some
|
||||
versions of Unix; see section~\ref{dynamic-externals}
|
||||
\link*{for more information}
|
||||
[for more information]
|
||||
{dynamic-externals}).
|
||||
The file \code{go} in the Scheme~48 installation source directory is an example
|
||||
of such a shell script.
|
||||
|
||||
\section{Command processor}
|
||||
|
||||
When you invoke the default heap image, a command processor starts
|
||||
running.
|
||||
The command processor acts as both a read-eval-print loop, reading
|
||||
expressions, evaluating them, and printing the results, and as
|
||||
an interactive debugger and data inspector.
|
||||
See Chapter~\ref{chapter:command-processor} for
|
||||
\link*{a description of the command processor}
|
||||
[a description of the command processor]
|
||||
{chapter:command-processor}.
|
||||
|
||||
\section{Editing}
|
||||
|
||||
We recommend running Scheme~48 under GNU Emacs or XEmacs using the
|
||||
\code{cmuscheme48} command package.
|
||||
This is in the Scheme~48 distribution's \code{emacs/} subdirectory and
|
||||
is included in XEmacs's \code{scheme} package.
|
||||
It is a variant of the \code{cmuscheme} library, which
|
||||
comes to us courtesy of Olin Shivers, formerly of CMU.
|
||||
You might want to put the following in your Emacs init file (\code{.emacs}):
|
||||
\begin{example}
|
||||
(setq scheme-program-name "scheme48")
|
||||
(autoload 'run-scheme
|
||||
"cmuscheme48"
|
||||
"Run an inferior Scheme process."
|
||||
t)
|
||||
\end{example}
|
||||
The Emacs function \code{run-scheme} can then be used to start a process
|
||||
running the program \code{scheme48} in a new buffer.
|
||||
To make the \code{autoload} and \code{(require \ldots)} forms work, you will
|
||||
also need
|
||||
to put the directory containing \code{cmuscheme} and related files in your
|
||||
emacs load-path:
|
||||
\begin{example}
|
||||
(setq load-path
|
||||
(append load-path '("\cvar{scheme-48-directory}/emacs")))
|
||||
\end{example}
|
||||
Further documentation can be found in the files \code{emacs/cmuscheme48.el} and
|
||||
\code{emacs/comint.el}.
|
||||
|
||||
\section{Performance}
|
||||
\label{section:performance}
|
||||
|
||||
If you want to generally have your code run faster than it normally
|
||||
would, enter \code{inline-values} mode before loading anything. Otherwise
|
||||
calls to primitives (like \code{+} and \code{cons}) and in-line procedures
|
||||
(like \code{not} and \code{cadr}) won't be open-coded, and programs will run
|
||||
more slowly.
|
||||
|
||||
The system doesn't start in \code{inline-values} mode by default because the
|
||||
Scheme report permits redefinitions of built-in procedures. With
|
||||
this mode set, such redefinitions don't work according to the report,
|
||||
because previously compiled calls may have in-lined the old
|
||||
definition, leaving no opportunity to call the new definition.
|
||||
|
||||
\code{Inline-values} mode is controlled by the \code{inline-values} switch.
|
||||
\code{,set inline-values} and \code{,unset inline-values} turn it on and off.
|
||||
|
||||
\section{Disassembler}
|
||||
|
||||
The \code{,dis} command prints out the disassembled byte codes of a procedure.
|
||||
\begin{example}
|
||||
> ,dis cons
|
||||
cons
|
||||
0 (protocol 2)
|
||||
2 (pop)
|
||||
3 (make-stored-object 2 pair)
|
||||
6 (return)
|
||||
>
|
||||
\end{example}
|
||||
The current byte codes are listed in the file \code{scheme/vm/arch.scm}.
|
||||
A somewhat out-of-date description of them can be found in
|
||||
\cite{Kelsey-Rees:Scheme48}.
|
||||
|
||||
The command argument is optional; if unsupplied it defaults to the
|
||||
current focus object (\code{\#\#}).
|
||||
|
||||
The disassembler can also be invoked on continuations and templates.
|
||||
|
||||
\section{Module system}
|
||||
\label{module-guide}
|
||||
|
||||
This section gives a brief description of modules and related entities.
|
||||
For detailed information, including a description of the module
|
||||
configuration language, see
|
||||
\link*{the module chapter}[chapter~\Ref]{chapter:modules}.
|
||||
|
||||
% JAR says: this paragraph is muddy.
|
||||
|
||||
A {\em module} is an isolated namespace, with visibility of bindings
|
||||
controlled by module descriptions written in a special
|
||||
configuration language.
|
||||
A module may be instantiated as a {\em package}, which is an environment
|
||||
in which code can be evaluated.
|
||||
Most modules are instantiated only once and so have a unique package.
|
||||
A {\em structure} is a subset of the bindings in a package.
|
||||
Only by being included in a structure can a binding be
|
||||
made visible in other packages.
|
||||
A structure has two parts, the package whose bindings are being exported
|
||||
and the set of names that are to be exported.
|
||||
This set of names is called an {\em interface}.
|
||||
A module then has three parts:
|
||||
\begin{itemize}
|
||||
\item a set of structures whose bindings are to be visible within the module
|
||||
\item the source code to be evaluated within the module
|
||||
\item a set of exported interfaces
|
||||
\end{itemize}
|
||||
Instantiating a module produces a package and a set of structures, one for
|
||||
each of the exported interfaces.
|
||||
|
||||
The following example uses \code{define-structure} to create a module that
|
||||
implements simple cells as pairs, instantiates this module, and binds the
|
||||
resulting structure to \code{cells}.
|
||||
The syntax \code{(export \cvar{name \ldots})} creates an interface
|
||||
containing \cvar{name \ldots}.
|
||||
The \code{open} clause lists structures whose bindings are visible
|
||||
within the module.
|
||||
The \code{begin} clause contains source code.
|
||||
\begin{example}
|
||||
(define-structure cells (export make-cell
|
||||
cell-ref
|
||||
cell-set!)
|
||||
(open scheme)
|
||||
(begin (define (make-cell x)
|
||||
(cons 'cell x))
|
||||
(define cell-ref cdr)
|
||||
(define cell-set! set-cdr!)))
|
||||
\end{example}
|
||||
|
||||
Cells could also have been implemented using the
|
||||
\link*{record facility}[record facility described in section~\Ref]{records}
|
||||
and available in structure \code{define-record-type}.
|
||||
\begin{example}
|
||||
(define-structure cells (export make-cell
|
||||
cell-ref
|
||||
cell-set!)
|
||||
(open scheme define-record-types)
|
||||
(begin (define-record-type cell :cell
|
||||
(make-cell value)
|
||||
cell?
|
||||
(value cell-ref cell-set!))))
|
||||
\end{example}
|
||||
|
||||
With either definition the resulting structure can be used in other
|
||||
modules by including \code{cells} in an \code{open} clause.
|
||||
|
||||
The command interpreter is always operating within a particular package.
|
||||
Initially this is a package in which only the standard Scheme bindings
|
||||
are visible.
|
||||
The bindings of other structures can be made visible by using the
|
||||
\link*{\code{,open} command}
|
||||
[\code{,open} command described in section~\Ref{} below]{module-command-guide}.
|
||||
|
||||
Note that this initial package does not include the configuration language.
|
||||
Module code needs to be evaluated in the configuration package, which can
|
||||
be done by using the {\code ,config} command:
|
||||
\begin{example}
|
||||
> ,config (define-structure cells \ldots)
|
||||
> ,open cells
|
||||
> (make-cell 4)
|
||||
'(cell . 4)
|
||||
> (define c (make-cell 4))
|
||||
> (cell-ref c)
|
||||
4
|
||||
\end{example}
|
||||
|
||||
\section{Library}
|
||||
|
||||
A number of useful utilities are either built in to Scheme~48 or can
|
||||
be loaded from an external library. These utilities are not visible
|
||||
in the user environment by default, but can be made available with the
|
||||
\code{open} command. For example, to use the \code{tables} structure, do
|
||||
\begin{example}
|
||||
> ,open tables
|
||||
>
|
||||
\end{example}
|
||||
|
||||
If the utility is not already loaded, then the \code{,open} command will
|
||||
load it.
|
||||
Or, you can load something explicitly (without opening it) using the
|
||||
\code{load-package} command:
|
||||
\begin{example}
|
||||
> ,load-package queues
|
||||
> ,open queues
|
||||
\end{example}
|
||||
|
||||
When loading a utility, the message "Note: optional optimizer not
|
||||
invoked" is innocuous. Feel free to ignore it.
|
||||
|
||||
See also the package system documentation, in
|
||||
\link*{the module chapter}[chapter~\Ref]{chapter:modules}.
|
||||
|
||||
Not all of the the libraries available in Scheme~48 are described in this
|
||||
manual.
|
||||
All are listed in files \code{rts-packages.scm},
|
||||
\code{comp-packages.scm}, \code{env-packages.scm}, and
|
||||
\code{more-packages.scm} in the \code{scheme} directory of the distribution,
|
||||
and the bindings they
|
||||
export are listed in \code{interfaces.scm} and
|
||||
\code{more-interfaces.scm} in the same directory.
|
||||
|
||||
%architecture
|
||||
% Information about the virtual machine. E.g.
|
||||
% (enum op eq?) => the integer opcode of the EQ? instruction
|
||||
%
|
||||
%big-scheme
|
||||
% Many generally useful features. See doc/big-scheme.txt.
|
||||
%
|
||||
%bigbit
|
||||
% Extensions to the bitwise logical operators (exported by
|
||||
% the BITWISE structure) so that they operate on bignums.
|
||||
% To use these you should do
|
||||
%
|
||||
% ,load-package bigbit
|
||||
% ,open bitwise
|
||||
%
|
||||
%conditions
|
||||
% Part of the condition system: DEFINE-CONDITION-PREDICATE and
|
||||
% routines for examining condition objects. (See also handle,
|
||||
% signals.)
|
||||
%
|
||||
%defpackage
|
||||
% The module system: DEFINE-STRUCTURE and DEFINE-INTERFACE.
|
||||
%
|
||||
%destructuring
|
||||
% DESTRUCTURE macro. See doc/big-scheme.txt.
|
||||
%
|
||||
%display-conditions
|
||||
% Displaying condition objects.
|
||||
% (DISPLAY-CONDITION condition port) \goesto{} unspecific
|
||||
% Display condition in an easily readable form. E.g.
|
||||
%\begin{example}
|
||||
% > ,open display-conditions handle conditions
|
||||
% > (display-condition
|
||||
% (call-with-current-continuation
|
||||
% (lambda (k)
|
||||
% (with-handler (lambda (c punt)
|
||||
% (if (error? c)
|
||||
% (k c)
|
||||
% (punt)))
|
||||
% (lambda () (+ 1 'a)))))
|
||||
% (current-output-port))
|
||||
%
|
||||
% Error: exception
|
||||
% (+ 1 'a)
|
||||
% >
|
||||
%\end{example}
|
||||
%
|
||||
%extended-ports
|
||||
% Ports for reading from and writing to strings, and related things.
|
||||
% See doc/big-scheme.txt.
|
||||
%
|
||||
%filenames
|
||||
% Rudimentary file name parsing and synthesis. E.g.
|
||||
% file-name-directory and file-name-nondirectory are as in Gnu emacs.
|
||||
%
|
||||
%floatnums
|
||||
% Floating point numbers. These are in a very crude state; use at
|
||||
% your own risk. They are slow and do not read or print correctly.
|
||||
%
|
||||
%fluids
|
||||
% Dynamically bound "variables."
|
||||
% (MAKE-FLUID top-level-value) \goesto{} a "fluid" object
|
||||
% (FLUID fluid) \goesto{} current value of fluid object
|
||||
% (SET-FLUID! fluid value) \goesto{} unspecific; changes current value of
|
||||
% fluid object
|
||||
% (LET-FLUID fluid value thunk) \goesto{} whatever thunk returns
|
||||
% Within the dynamic extent of execution of (thunk), the fluid
|
||||
% object has value as its binding (unless changed by SET-FLUID!
|
||||
% or overridden by another LET-FLUID).
|
||||
% E.g.
|
||||
% (define f (make-fluid 7))
|
||||
% (define (baz) (+ (fluid f) 1))
|
||||
% (baz) ;\goesto{} 8
|
||||
% (let-fluid f 4 (lambda () (+ (baz) 1))) ;\goesto{} 6
|
||||
%
|
||||
%formats
|
||||
% A simple FORMAT procedure, similar to Common Lisp's or T's.
|
||||
% See doc/big-scheme.txt for documentation.
|
||||
%
|
||||
%handle
|
||||
% Part of the condition system.
|
||||
% (WITH-HANDLER handler thunk) \goesto{} whatever thunk returns.
|
||||
% handler is a procedure of two arguments. The first argument
|
||||
% is a condition object, and the second is a "punt" procedure.
|
||||
% The handler should examine the condition object (using ERROR?,
|
||||
% etc. from the CONDITIONS structure). If it decides not to do
|
||||
% anything special, it should tail-call the "punt" procedure.
|
||||
% Otherwise it should take appropriate action and perform a
|
||||
% non-local exit. It should not just return unless it knows
|
||||
% damn well what it's doing; returns in certain situations can
|
||||
% cause VM crashes.
|
||||
%
|
||||
%interrupts
|
||||
% Interrupt system
|
||||
%
|
||||
%ports
|
||||
% A few extra port-related operations, notably FORCE-OUTPUT.
|
||||
%
|
||||
%pp
|
||||
% A pretty-printer. (p \cvar{exp}) will pretty-print the result of \cvar{exp},
|
||||
% which must be an S-expression. (Source code for procedures is not
|
||||
% retained or reconstructed.) You can also do (p \cvar{exp} \cvar{port}) to
|
||||
% print to a specific port.
|
||||
%
|
||||
% The procedure pretty-print takes three arguments: the object to be
|
||||
% printed, a port to write to, and the current horizontal cursor
|
||||
% position. If you've just done a newline, then pass in zero for
|
||||
% the position argument.
|
||||
%
|
||||
% The algorithm is very peculiar, and sometimes buggy.
|
||||
%
|
||||
%queues
|
||||
% FIFO queues.
|
||||
%
|
||||
%random
|
||||
% Not-very-random random number generator. The \cvar{seed} should be between
|
||||
% 0 and 2$^{28}$ exclusive.
|
||||
%
|
||||
% > (define random (make-random \cvar{seed}))
|
||||
% > (random) \goesto{} pseudo-random number between 0 and 2$^{28}$
|
||||
%
|
||||
%receiving
|
||||
% Convenient interface to the call-with-values procedure, like
|
||||
% Common Lisp's multiple-value-bind macro. See doc/big-scheme.txt.
|
||||
%
|
||||
%records
|
||||
% MAKE-RECORD-TYPE and friends. See the Scheme of Things column in
|
||||
% Lisp Pointers, volume 4, number 1, for documentation.
|
||||
%
|
||||
%recnums
|
||||
% Complex numbers. This should be loaded (e.g. with ,load-package)
|
||||
% but needn't be opened.
|
||||
%
|
||||
%search-trees
|
||||
% Balanced binary search trees. See comments at top of
|
||||
% big/search-tree.scm.
|
||||
%
|
||||
%signals
|
||||
% ERROR, WARN, and related procedures.
|
||||
%
|
||||
%sort
|
||||
% Online merge sort (see comment at top of file big/sort.scm).
|
||||
%
|
||||
% (sort-list \cvar{list} \cvar{pred})
|
||||
% (sort-list! \cvar{list} \cvar{pred})
|
||||
%
|
||||
%sicp
|
||||
% Compatibility package for the Scheme dialect used in the book
|
||||
% "Structure and Interpretation of Computer Programs."
|
||||
%
|
||||
%sockets
|
||||
% Interface to Unix BSD sockets. See comments at top of file
|
||||
% misc/socket.scm.
|
||||
%
|
||||
%threads
|
||||
% Multitasking. See doc/threads.txt.
|
||||
%
|
||||
%util
|
||||
% SUBLIST, ANY, REDUCE, FILTER, and some other useful things.
|
||||
%
|
||||
%weak
|
||||
% Weak pointers and populations.
|
||||
% (MAKE-WEAK-POINTER thing) => weak-pointer
|
||||
% (WEAK-POINTER-REF weak-pointer) => thing or \code{\#f}
|
||||
% \code{\#f} if the thing has been gc'ed.
|
||||
%
|
||||
%writing
|
||||
% (RECURRING-WRITE thing port recur) => unspecific
|
||||
% This is the same as WRITE except that recursive calls invoke
|
||||
% the recur argument instead of WRITE. For an example, see
|
||||
% the definition of LIMITED-WRITE in env/dispcond.scm, which
|
||||
% implements processing similar to common Lisp's *print-level*
|
||||
% and *print-length*.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1 @@
|
|||
1.0
|
||||
Loading…
Reference in New Issue