Commit | Line | Data |
---|---|---|
a0e07ba4 NJ |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename r5rs.info | |
4 | @settitle Revised(5) Scheme | |
5 | ||
6 | @c This copy of r5rs.texi differs from Aubrey Jaffer's master copy | |
7 | @c by a set of changes to allow the building of r5rs.dvi from r5rs.texi. | |
8 | @c Aubrey Jaffer's view - which I agree with - is that, given that | |
9 | @c people have the option of building r5rs.dvi from the original | |
10 | @c LaTeX distribution for R5RS, it is not worth fixing his master | |
11 | @c copy of r5rs.texi and the tool which autogenerates it. On the | |
12 | @c other hand, it is a marginal convenience for people to be able to | |
13 | @c build hardcopy from r5rs.texi, even if the results are less good | |
14 | @c than with the original LaTeX. Hence the following fixes. | |
15 | @c (lines 714, 725, 728, 1614, 2258): Remove invalid parentheses from | |
16 | @c @deffn statements. | |
17 | @c (line 2316): Change @deffnx to @deffn, and insert `@end deffn' to | |
18 | @c terminate preceding @deffn. | |
19 | @c (line 7320): Insert `@c ' at beginning of lines that are intended | |
20 | @c to be @ignore'd. | |
21 | @c | |
22 | @c NJ 2001/1/26 | |
23 | ||
24 | @c \documentclass[twoside]{algol60} | |
25 | ||
26 | @c \pagestyle{headings} | |
27 | @c \showboxdepth=0 | |
28 | ||
29 | ||
30 | ||
31 | @c \def\headertitle{Revised$^{5}$ Scheme} | |
32 | @c \def\integerversion{5} | |
33 | ||
34 | @c Sizes and dimensions | |
35 | ||
36 | @c \topmargin -.375in % Nominal distance from top of page to top of | |
37 | ||
38 | @c box containing running head. | |
39 | @c \headsep 15pt % Space between running head and text. | |
40 | ||
41 | @c \textheight 663pt % Height of text (including footnotes and figures, | |
42 | ||
43 | @c excluding running head and foot). | |
44 | ||
45 | @c \textwidth 523pt % Width of text line. | |
46 | @c \columnsep 15pt % Space between columns | |
47 | @c \columnseprule 0pt % Width of rule between columns. | |
48 | ||
49 | @c \parskip 5pt plus 2pt minus 2pt % Extra vertical space between paragraphs. | |
50 | @c \parindent 0pt % Width of paragraph indentation. | |
51 | @c \topsep 0pt plus 2pt % Extra vertical space, in addition to | |
52 | ||
53 | @c \parskip, added above and below list and | |
54 | ||
55 | @c paragraphing environments. | |
56 | ||
57 | @c \oddsidemargin -.5in % Left margin on odd-numbered pages. | |
58 | @c \evensidemargin -.5in % Left margin on even-numbered pages. | |
59 | ||
60 | @c % End of sizes and dimensions | |
61 | ||
62 | @paragraphindent 0 | |
63 | @c %**end of header | |
64 | @c syncodeindex fn cp | |
65 | ||
66 | @ifinfo | |
67 | @dircategory The Algorithmic Language Scheme | |
68 | @direntry | |
69 | * R5RS: (r5rs). The Revised(5) Report on Scheme. | |
70 | @end direntry | |
71 | @end ifinfo | |
72 | ||
73 | ||
74 | @c \parindent 0pt %!! 15pt % Width of paragraph indentation. | |
75 | ||
76 | @b{20 February 1998} | |
77 | @c \hfil \today{} | |
78 | ||
79 | @c @include{first} | |
80 | @titlepage | |
81 | ||
82 | @c HTML first page | |
83 | @title Scheme | |
84 | @subtitle Revised(5) Report on the Algorithmic Language Scheme | |
85 | @c First page | |
86 | ||
87 | @c \thispagestyle{empty} | |
88 | ||
89 | @c \todo{"another" report?} | |
90 | ||
91 | ||
92 | @author R@sc{ICHARD} K@sc{ELSEY}, W@sc{ILLIAM} C@sc{LINGER, AND} J@sc{ONATHAN} R@sc{EES} (@i{Editors}) | |
93 | @author H. A@sc{BELSON} | |
94 | @author R. K. D@sc{YBVIG} | |
95 | @author C. T. H@sc{AYNES} | |
96 | @author G. J. R@sc{OZAS} | |
97 | @author N. I. A@sc{DAMS IV} | |
98 | @author D. P. F@sc{RIEDMAN} | |
99 | @author E. K@sc{OHLBECKER} | |
100 | @author G. L. S@sc{TEELE} J@sc{R}. | |
101 | @author D. H. B@sc{ARTLEY} | |
102 | @author R. H@sc{ALSTEAD} | |
103 | @author D. O@sc{XLEY} | |
104 | @author G. J. S@sc{USSMAN} | |
105 | @author G. B@sc{ROOKS} | |
106 | @author C. H@sc{ANSON} | |
107 | @author K. M. P@sc{ITMAN} | |
108 | @author M. W@sc{AND} | |
109 | @author | |
110 | ||
111 | ||
112 | @c {\it Dedicated to the Memory of ALGOL 60} | |
113 | @i{Dedicated to the Memory of Robert Hieb} | |
114 | @c [For the macros in R5RS -RK] | |
115 | ||
116 | ||
117 | ||
118 | ||
119 | @unnumbered Summary | |
120 | ||
121 | ||
122 | The report gives a defining description of the programming language | |
123 | Scheme. Scheme is a statically scoped and properly tail-recursive | |
124 | dialect of the Lisp programming language invented by Guy Lewis | |
125 | Steele Jr.@: and Gerald Jay Sussman. It was designed to have an | |
126 | exceptionally clear and simple semantics and few different ways to | |
127 | form expressions. A wide variety of programming paradigms, including | |
128 | imperative, functional, and message passing styles, find convenient | |
129 | expression in Scheme. | |
130 | ||
131 | The introduction offers a brief history of the language and of | |
132 | the report. | |
133 | ||
134 | The first three chapters present the fundamental ideas of the | |
135 | language and describe the notational conventions used for describing the | |
136 | language and for writing programs in the language. | |
137 | ||
138 | Chapters @ref{Expressions} and @ref{Program structure} describe | |
139 | the syntax and semantics of expressions, programs, and definitions. | |
140 | ||
141 | Chapter @ref{Standard procedures} describes Scheme's built-in | |
142 | procedures, which include all of the language's data manipulation and | |
143 | input/output primitives. | |
144 | ||
145 | Chapter @ref{Formal syntax and semantics} provides a formal syntax for Scheme | |
146 | written in extended BNF, along with a formal denotational semantics. | |
147 | An example of the use of the language follows the formal syntax and | |
148 | semantics. | |
149 | ||
150 | The report concludes with a list of references and an | |
151 | alphabetic index. | |
152 | ||
153 | @ignore todo | |
154 | expand the summary so that it fills up the column. | |
155 | @end ignore | |
156 | ||
157 | ||
158 | @c \vfill | |
159 | @c \begin{center} | |
160 | @c {\large \bf | |
161 | @c *** DRAFT*** \\ | |
162 | @c %August 31, 1989 | |
163 | @c \today | |
164 | @c }\end{center} | |
165 | ||
166 | ||
167 | ||
168 | ||
169 | ||
170 | @c \addvspace{3.5pt} % don't shrink this gap | |
171 | @c \renewcommand{\tocshrink}{-3.5pt} % value determined experimentally | |
172 | ||
173 | ||
174 | ||
175 | ||
176 | ||
177 | ||
178 | @page | |
179 | ||
180 | @end titlepage | |
181 | ||
182 | @c INFO first page | |
6e4de0cc | 183 | @ifnottex |
a0e07ba4 NJ |
184 | |
185 | @c First page | |
186 | ||
187 | @c \thispagestyle{empty} | |
188 | ||
189 | @c \todo{"another" report?} | |
190 | ||
191 | ||
192 | @node top, Introduction, (dir), (dir) | |
193 | @top Revised(5) Report on the Algorithmic Language Scheme | |
194 | ||
195 | @sp 1 | |
196 | ||
197 | ||
a0e07ba4 | 198 | @quotation |
6e4de0cc MV |
199 | R@sc{ichard} K@sc{elsey}, W@sc{illiam} C@sc{linger, and} J@sc{onathan} R@sc{ees} (@i{Editors}) |
200 | @sp 1 | |
a0e07ba4 | 201 | @multitable @columnfractions 0.25 0.25 0.25 0.25 |
6e4de0cc MV |
202 | @item H. A@sc{belson} @tab R. K. D@sc{ybvig} @tab C. T. H@sc{aynes} @tab G. J. R@sc{ozas} |
203 | @item N. I. A@sc{dams IV} @tab D. P. F@sc{riedman} @tab E. K@sc{ohlbecker} @tab G. L. S@sc{teele} J@sc{r}. | |
204 | @item D. H. B@sc{artley} @tab R. H@sc{alstead} @tab D. O@sc{xley} @tab G. J. S@sc{ussman} | |
205 | @item G. B@sc{rooks} @tab C. H@sc{anson} @tab K. M. P@sc{itman} @tab M. W@sc{and} | |
a0e07ba4 NJ |
206 | @item |
207 | @end multitable | |
208 | @end quotation | |
209 | ||
210 | ||
211 | @sp 2 | |
212 | ||
213 | @c {\it Dedicated to the Memory of ALGOL 60} | |
214 | @i{Dedicated to the Memory of Robert Hieb} | |
215 | @c [For the macros in R5RS -RK] | |
216 | ||
217 | @sp 3 | |
218 | ||
219 | ||
220 | ||
221 | ||
222 | @majorheading Summary | |
223 | ||
224 | ||
225 | The report gives a defining description of the programming language | |
226 | Scheme. Scheme is a statically scoped and properly tail-recursive | |
227 | dialect of the Lisp programming language invented by Guy Lewis | |
228 | Steele Jr.@: and Gerald Jay Sussman. It was designed to have an | |
229 | exceptionally clear and simple semantics and few different ways to | |
230 | form expressions. A wide variety of programming paradigms, including | |
231 | imperative, functional, and message passing styles, find convenient | |
232 | expression in Scheme. | |
233 | ||
234 | The introduction offers a brief history of the language and of | |
235 | the report. | |
236 | ||
237 | The first three chapters present the fundamental ideas of the | |
238 | language and describe the notational conventions used for describing the | |
239 | language and for writing programs in the language. | |
240 | ||
241 | Chapters @ref{Expressions} and @ref{Program structure} describe | |
242 | the syntax and semantics of expressions, programs, and definitions. | |
243 | ||
244 | Chapter @ref{Standard procedures} describes Scheme's built-in | |
245 | procedures, which include all of the language's data manipulation and | |
246 | input/output primitives. | |
247 | ||
248 | Chapter @ref{Formal syntax and semantics} provides a formal syntax for Scheme | |
249 | written in extended BNF, along with a formal denotational semantics. | |
250 | An example of the use of the language follows the formal syntax and | |
251 | semantics. | |
252 | ||
253 | The report concludes with a list of references and an | |
254 | alphabetic index. | |
255 | ||
256 | @ignore todo | |
257 | expand the summary so that it fills up the column. | |
258 | @end ignore | |
259 | ||
260 | ||
261 | @c \vfill | |
262 | @c \begin{center} | |
263 | @c {\large \bf | |
264 | @c *** DRAFT*** \\ | |
265 | @c %August 31, 1989 | |
266 | @c \today | |
267 | @c }\end{center} | |
268 | ||
269 | ||
270 | ||
271 | ||
272 | ||
273 | @c \addvspace{3.5pt} % don't shrink this gap | |
274 | @c \renewcommand{\tocshrink}{-3.5pt} % value determined experimentally | |
275 | ||
276 | @unnumbered Contents | |
277 | ||
278 | @menu | |
279 | * Introduction:: | |
280 | * Overview of Scheme:: | |
281 | * Lexical conventions:: | |
282 | * Basic concepts:: | |
283 | * Expressions:: | |
284 | * Program structure:: | |
285 | * Standard procedures:: | |
286 | * Formal syntax and semantics:: | |
287 | * Notes:: | |
288 | * Additional material:: | |
289 | * Example:: | |
290 | * Bibliography:: | |
291 | * Index:: | |
292 | @end menu | |
293 | ||
294 | ||
295 | ||
296 | ||
297 | ||
298 | @page | |
299 | ||
6e4de0cc | 300 | @end ifnottex |
a0e07ba4 NJ |
301 | |
302 | ||
303 | @c @include{intro} | |
304 | @node Introduction, Overview of Scheme, top, top | |
305 | @unnumbered Introduction | |
306 | ||
307 | @menu | |
308 | * Background:: | |
309 | * Acknowledgements:: | |
310 | @end menu | |
311 | ||
312 | ||
313 | ||
314 | ||
315 | Programming languages should be designed not by piling feature on top of | |
316 | feature, but by removing the weaknesses and restrictions that make additional | |
317 | features appear necessary. Scheme demonstrates that a very small number | |
318 | of rules for forming expressions, with no restrictions on how they are | |
319 | composed, suffice to form a practical and efficient programming language | |
320 | that is flexible enough to support most of the major programming | |
321 | paradigms in use today. | |
322 | ||
323 | @c Scheme has influenced the evolution of Lisp. | |
324 | Scheme | |
325 | was one of the first programming languages to incorporate first class | |
326 | procedures as in the lambda calculus, thereby proving the usefulness of | |
327 | static scope rules and block structure in a dynamically typed language. | |
328 | Scheme was the first major dialect of Lisp to distinguish procedures | |
329 | from lambda expressions and symbols, to use a single lexical | |
330 | environment for all variables, and to evaluate the operator position | |
331 | of a procedure call in the same way as an operand position. By relying | |
332 | entirely on procedure calls to express iteration, Scheme emphasized the | |
333 | fact that tail-recursive procedure calls are essentially goto's that | |
334 | pass arguments. Scheme was the first widely used programming language to | |
335 | embrace first class escape procedures, from which all previously known | |
336 | sequential control structures can be synthesized. A subsequent | |
337 | version of Scheme introduced the concept of exact and inexact numbers, | |
338 | an extension of Common Lisp's generic arithmetic. | |
339 | More recently, Scheme became the first programming language to support | |
340 | hygienic macros, which permit the syntax of a block-structured language | |
341 | to be extended in a consistent and reliable manner. | |
342 | @c A few | |
343 | @c of these innovations have recently been incorporated into Common Lisp, while | |
344 | @c others remain to be adopted. | |
345 | ||
346 | @ignore todo | |
347 | Ramsdell: | |
348 | I would like to make a few comments on presentation. The most | |
349 | important comment is about section organization. Newspaper writers | |
350 | spend most of their time writing the first three paragraphs of any | |
351 | article. This part of the article is often the only part read by | |
352 | readers, and is important in enticing readers to continue. In the | |
353 | same way, The first page is most likely to be the only page read by | |
354 | many SIGPLAN readers. If I had my choice of what I would ask them to | |
355 | read, it would be the material in section 1.1, the Semantics section | |
356 | that notes that scheme is lexically scoped, tail recursive, weakly | |
357 | typed, ... etc. I would expand on the discussion on continuations, | |
358 | as they represent one important difference between Scheme and other | |
359 | languages. The introduction, with its history of scheme, its history | |
360 | of scheme reports and meetings, and acknowledgements giving names of | |
361 | people that the reader will not likely know, is not that one page I | |
362 | would like all to read. I suggest moving the history to the back of | |
363 | the report, and use the first couple of pages to convince the reader | |
364 | that the language documented in this report is worth studying. | |
365 | ||
366 | @end ignore | |
367 | ||
368 | ||
369 | @node Background, Acknowledgements, Introduction, Introduction | |
370 | @unnumberedsec Background | |
371 | ||
372 | ||
373 | The first description of Scheme was written in | |
374 | 1975 [Scheme75]. A revised report [Scheme78] | |
375 | @ignore todo | |
376 | italicize or not? | |
377 | @end ignore | |
378 | appeared in 1978, which described the evolution | |
379 | of the language as its MIT implementation was upgraded to support an | |
380 | innovative compiler [Rabbit]. Three distinct projects began in | |
381 | 1981 and 1982 to use variants of Scheme for courses at MIT, Yale, and | |
382 | Indiana University [Rees82], [MITScheme], [Scheme311]. An introductory | |
383 | computer science textbook using Scheme was published in | |
384 | 1984 [SICP]. | |
385 | ||
386 | @c \vest As might be expected of a language used primarily for education and | |
387 | @c research, Scheme has always evolved rapidly. This was no problem when | |
388 | @c Scheme was used only within MIT, but | |
389 | As Scheme became more widespread, | |
390 | local dialects began to diverge until students and researchers | |
391 | occasionally found it difficult to understand code written at other | |
392 | sites. | |
393 | Fifteen representatives of the major implementations of Scheme therefore | |
394 | met in October 1984 to work toward a better and more widely accepted | |
395 | standard for Scheme. | |
396 | @c Participating in this workshop were Hal Abelson, Norman Adams, David | |
397 | @c Bartley, Gary Brooks, William Clinger, Daniel Friedman, Robert Halstead, | |
398 | @c Chris Hanson, Christopher Haynes, Eugene Kohlbecker, Don Oxley, Jonathan Rees, | |
399 | @c Guillermo Rozas, Gerald Jay Sussman, and Mitchell Wand. Kent Pitman | |
400 | @c made valuable contributions to the agenda for the workshop but was | |
401 | @c unable to attend the sessions. | |
402 | ||
403 | @c Subsequent electronic mail discussions and committee work completed the | |
404 | @c definition of the language. | |
405 | @c Gerry Sussman drafted the section on numbers, Chris Hanson drafted the | |
406 | @c sections on characters and strings, and Gary Brooks and William Clinger | |
407 | @c drafted the sections on input and output. | |
408 | @c William Clinger recorded the decisions of the workshop and | |
409 | @c compiled the pieces into a coherent document. | |
410 | @c The ``Revised revised report on Scheme''~\cite{RRRS} | |
411 | Their report [RRRS] | |
412 | was published at MIT and Indiana University in the summer of 1985. | |
413 | Further revision took place in the spring of 1986 [R3RS], | |
414 | @c , again accomplished | |
415 | @c almost entirely by electronic mail, resulted in the present report. | |
416 | and in the spring of 1988 [R4RS]. | |
417 | The present report reflects further revisions agreed upon in a meeting | |
418 | at Xerox PARC in June 1992. | |
419 | ||
420 | @c \vest The number 3 in the title is part of the title, not a reference to | |
421 | @c a footnote. The word ``revised'' is raised to the third power because | |
422 | @c the report is a revision of a report that was already twice revised. | |
423 | ||
424 | @ignore todo | |
425 | Write an editors' note? | |
426 | @end ignore | |
427 | ||
428 | ||
429 | ||
430 | @sp 3 | |
431 | ||
432 | We intend this report to belong to the entire Scheme community, and so | |
433 | we grant permission to copy it in whole or in part without fee. In | |
434 | particular, we encourage implementors of Scheme to use this report as | |
435 | a starting point for manuals and other documentation, modifying it as | |
436 | necessary. | |
437 | ||
438 | ||
439 | ||
440 | ||
441 | @node Acknowledgements, , Background, Introduction | |
442 | @unnumberedsec Acknowledgements | |
443 | ||
444 | ||
445 | We would like to thank the following people for their help: Alan Bawden, Michael | |
446 | Blair, George Carrette, Andy Cromarty, Pavel Curtis, Jeff Dalton, Olivier Danvy, | |
447 | Ken Dickey, Bruce Duba, Marc Feeley, | |
448 | Andy Freeman, Richard Gabriel, Yekta G"ursel, Ken Haase, Robert | |
449 | Hieb, Paul Hudak, Morry Katz, Chris Lindblad, Mark Meyer, Jim Miller, Jim Philbin, | |
450 | John Ramsdell, Mike Shaff, Jonathan Shapiro, Julie Sussman, | |
451 | Perry Wagle, Daniel Weise, Henry Wu, and Ozan Yigit. | |
452 | We thank Carol Fessenden, Daniel | |
453 | Friedman, and Christopher Haynes for permission to use text from the Scheme 311 | |
454 | version 4 reference manual. We thank Texas Instruments, Inc. for permission to | |
455 | use text from the @emph{TI Scheme Language Reference Manual}[TImanual85]. | |
456 | We gladly acknowledge the influence of manuals for MIT Scheme[MITScheme], | |
457 | T[Rees84], Scheme 84[Scheme84],Common Lisp[CLtL], | |
458 | and Algol 60[Naur63]. | |
459 | ||
460 | We also thank Betty Dexter for the extreme effort she put into | |
461 | setting this report in @TeX{}, and Donald Knuth for designing the program | |
462 | that caused her troubles. | |
463 | ||
464 | The Artificial Intelligence Laboratory of the | |
465 | Massachusetts Institute of Technology, the Computer Science | |
466 | Department of Indiana University, the Computer and Information | |
467 | Sciences Department of the University of Oregon, and the NEC Research | |
468 | Institute supported the preparation of this report. Support for the MIT | |
469 | work was provided in part by | |
470 | the Advanced Research Projects Agency of the Department of Defense under Office | |
471 | of Naval Research contract N00014-80-C-0505. Support for the Indiana | |
472 | University work was provided by NSF grants NCS 83-04567 and NCS | |
473 | 83-03325. | |
474 | ||
475 | ||
476 | ||
477 | ||
478 | @sp 2 | |
479 | ||
480 | @c \clearchapterstar{Description of the language} %\unskip\vskip -2ex | |
481 | @c @include{struct} | |
482 | ||
483 | @c 1. Structure of the language | |
484 | ||
485 | @node Overview of Scheme, Lexical conventions, Introduction, top | |
486 | @chapter Overview of Scheme | |
487 | ||
488 | @menu | |
489 | * Semantics:: | |
490 | * Syntax:: | |
491 | * Notation and terminology:: | |
492 | @end menu | |
493 | ||
494 | ||
495 | @node Semantics, Syntax, Overview of Scheme, Overview of Scheme | |
496 | @section Semantics | |
497 | ||
498 | ||
499 | ||
500 | This section gives an overview of Scheme's semantics. A | |
501 | detailed informal semantics is the subject of | |
502 | chapters @ref{Basic concepts} through @ref{Standard procedures}. For reference | |
503 | purposes, section @ref{Formal semantics} provides a formal | |
504 | semantics of Scheme. | |
505 | ||
506 | Following Algol, Scheme is a statically scoped programming | |
507 | language. Each use of a variable is associated with a lexically | |
508 | apparent binding of that variable. | |
509 | ||
510 | Scheme has latent as opposed to manifest types. Types | |
511 | are associated with values (also called objects) rather than | |
512 | @cindex @w{object} | |
513 | with variables. (Some authors refer to languages with latent types as | |
514 | weakly typed or dynamically typed languages.) Other languages with | |
515 | latent types are APL, Snobol, and other dialects of Lisp. Languages | |
516 | with manifest types (sometimes referred to as strongly typed or | |
517 | statically typed languages) include Algol 60, Pascal, and C. | |
518 | ||
519 | All objects created in the course of a Scheme computation, including | |
520 | procedures and continuations, have unlimited extent. | |
521 | No Scheme object is ever destroyed. The reason that | |
522 | implementations of Scheme do not (usually!) run out of storage is that | |
523 | they are permitted to reclaim the storage occupied by an object if | |
524 | they can prove that the object cannot possibly matter to any future | |
525 | computation. Other languages in which most objects have unlimited | |
526 | extent include APL and other Lisp dialects. | |
527 | ||
528 | Implementations of Scheme are required to be properly tail-recursive. | |
529 | This allows the execution of an iterative computation in constant space, | |
530 | even if the iterative computation is described by a syntactically | |
531 | recursive procedure. Thus with a properly tail-recursive implementation, | |
532 | iteration can be expressed using the ordinary procedure-call | |
533 | mechanics, so that special iteration constructs are useful only as | |
534 | syntactic sugar. See section @ref{Proper tail recursion}. | |
535 | ||
536 | Scheme procedures are objects in their own right. Procedures can be | |
537 | created dynamically, stored in data structures, returned as results of | |
538 | procedures, and so on. Other languages with these properties include | |
539 | Common Lisp and ML. | |
540 | @ignore todo | |
541 | Rozas: Scheme had them first. | |
542 | @end ignore | |
543 | ||
544 | ||
545 | One distinguishing feature of Scheme is that continuations, which | |
546 | in most other languages only operate behind the scenes, also have | |
547 | ``first-class'' status. Continuations are useful for implementing a | |
548 | wide variety of advanced control constructs, including non-local exits, | |
549 | backtracking, and coroutines. See section @ref{Control features}. | |
550 | ||
551 | Arguments to Scheme procedures are always passed by value, which | |
552 | means that the actual argument expressions are evaluated before the | |
553 | procedure gains control, whether the procedure needs the result of the | |
554 | evaluation or not. ML, C, and APL are three other languages that always | |
555 | pass arguments by value. | |
556 | This is distinct from the lazy-evaluation semantics of Haskell, | |
557 | or the call-by-name semantics of Algol 60, where an argument | |
558 | expression is not evaluated unless its value is needed by the | |
559 | procedure. | |
560 | ||
561 | @ignore todo | |
562 | Lisp's call by value should be explained more | |
563 | accurately. What's funny is that all values are references. | |
564 | @end ignore | |
565 | ||
566 | ||
567 | Scheme's model of arithmetic is designed to remain as independent as | |
568 | possible of the particular ways in which numbers are represented within a | |
569 | computer. In Scheme, every integer is a rational number, every rational is a | |
570 | real, and every real is a complex number. Thus the distinction between integer | |
571 | and real arithmetic, so important to many programming languages, does not | |
572 | appear in Scheme. In its place is a distinction between exact arithmetic, | |
573 | which corresponds to the mathematical ideal, and inexact arithmetic on | |
574 | approximations. As in Common Lisp, exact arithmetic is not limited to | |
575 | integers. | |
576 | ||
577 | @node Syntax, Notation and terminology, Semantics, Overview of Scheme | |
578 | @section Syntax | |
579 | ||
580 | ||
581 | Scheme, like most dialects of Lisp, employs a fully parenthesized prefix | |
582 | notation for programs and (other) data; the grammar of Scheme generates a | |
583 | sublanguage of the language used for data. An important | |
584 | consequence of this simple, uniform representation is the susceptibility of | |
585 | Scheme programs and data to uniform treatment by other Scheme programs. | |
586 | For example, the @samp{eval} procedure evaluates a Scheme program expressed | |
587 | as data. | |
588 | ||
589 | The @samp{read} procedure performs syntactic as well as lexical decomposition of | |
590 | the data it reads. The @samp{read} procedure parses its input as data | |
591 | (section @pxref{External representation}), not as program. | |
592 | ||
593 | The formal syntax of Scheme is described in section @ref{Formal syntax}. | |
594 | ||
595 | ||
596 | @node Notation and terminology, , Syntax, Overview of Scheme | |
597 | @section Notation and terminology | |
598 | ||
599 | @menu | |
600 | * Primitive; library; and optional features:: | |
601 | * Error situations and unspecified behavior:: | |
602 | * Entry format:: | |
603 | * Evaluation examples:: | |
604 | * Naming conventions:: | |
605 | @end menu | |
606 | ||
607 | ||
608 | ||
609 | @node Primitive; library; and optional features, Error situations and unspecified behavior, Notation and terminology, Notation and terminology | |
610 | @subsection Primitive; library; and optional features | |
611 | ||
612 | ||
613 | ||
614 | It is required that every implementation of Scheme support all | |
615 | features that are not marked as being @dfn{optional}. Implementations are | |
616 | @cindex @w{optional} | |
617 | free to omit optional features of Scheme or to add extensions, | |
618 | provided the extensions are not in conflict with the language reported | |
619 | here. In particular, implementations must support portable code by | |
620 | providing a syntactic mode that preempts no lexical conventions of this | |
621 | report. | |
622 | ||
623 | To aid in understanding and implementing Scheme, some features are marked | |
624 | as @dfn{library}. These can be easily implemented in terms of the other, | |
625 | @cindex @w{library} | |
626 | primitive, features. They are redundant in the strict sense of | |
627 | the word, but they capture common patterns of usage, and are therefore | |
628 | provided as convenient abbreviations. | |
629 | ||
630 | @node Error situations and unspecified behavior, Entry format, Primitive; library; and optional features, Notation and terminology | |
631 | @subsection Error situations and unspecified behavior | |
632 | ||
633 | ||
634 | ||
635 | @cindex @w{error} | |
636 | When speaking of an error situation, this report uses the phrase ``an | |
637 | error is signalled'' to indicate that implementations must detect and | |
638 | report the error. If such wording does not appear in the discussion of | |
639 | an error, then implementations are not required to detect or report the | |
640 | error, though they are encouraged to do so. An error situation that | |
641 | implementations are not required to detect is usually referred to simply | |
642 | as ``an error.'' | |
643 | ||
644 | For example, it is an error for a procedure to be passed an argument that | |
645 | the procedure is not explicitly specified to handle, even though such | |
646 | domain errors are seldom mentioned in this report. Implementations may | |
647 | extend a procedure's domain of definition to include such arguments. | |
648 | ||
649 | This report uses the phrase ``may report a violation of an | |
650 | implementation restriction'' to indicate circumstances under which an | |
651 | implementation is permitted to report that it is unable to continue | |
652 | execution of a correct program because of some restriction imposed by the | |
653 | implementation. Implementation restrictions are of course discouraged, | |
654 | but implementations are encouraged to report violations of implementation | |
655 | restrictions. | |
656 | @cindex @w{implementation restriction} | |
657 | ||
658 | For example, an implementation may report a violation of an | |
659 | implementation restriction if it does not have enough storage to run a | |
660 | program. | |
661 | ||
662 | If the value of an expression is said to be ``unspecified,'' then | |
663 | the expression must evaluate to some object without signalling an error, | |
664 | but the value depends on the implementation; this report explicitly does | |
665 | not say what value should be returned. | |
666 | @cindex @w{unspecified} | |
667 | ||
668 | @ignore todo | |
669 | Talk about unspecified behavior vs. unspecified values. | |
670 | @end ignore | |
671 | ||
672 | ||
673 | @ignore todo | |
674 | Look at KMP's situations paper. | |
675 | @end ignore | |
676 | ||
677 | ||
678 | ||
679 | @node Entry format, Evaluation examples, Error situations and unspecified behavior, Notation and terminology | |
680 | @subsection Entry format | |
681 | ||
682 | ||
683 | Chapters @ref{Expressions} and @ref{Standard procedures} are organized | |
684 | into entries. Each entry describes one language feature or a group of | |
685 | related features, where a feature is either a syntactic construct or a | |
686 | built-in procedure. An entry begins with one or more header lines of the form | |
687 | ||
688 | ||
689 | @noindent | |
690 | @deffn {@var{category}} @var{template} | |
691 | ||
692 | @end deffn | |
693 | ||
694 | for required, primitive features, or | |
695 | ||
696 | ||
697 | @noindent | |
698 | @deffn {@var{qualifier} @var{category}} @var{template} | |
699 | ||
700 | @end deffn | |
701 | ||
702 | where @var{qualifier} is either ``library'' or ``optional'' as defined | |
703 | in section @ref{Primitive; library; and optional features}. | |
704 | ||
705 | If @var{category} is ``syntax'', the entry describes an expression | |
706 | type, and the template gives the syntax of the expression type. | |
707 | Components of expressions are designated by syntactic variables, which | |
708 | are written using angle brackets, for example, @r{<expression>}, | |
709 | @r{<variable>}. Syntactic variables should be understood to denote segments of | |
710 | program text; for example, @r{<expression>} stands for any string of | |
711 | characters which is a syntactically valid expression. The notation | |
712 | ||
713 | @format | |
714 | @r{<thing1>} @dots{} | |
715 | @end format | |
716 | ||
717 | indicates zero or more occurrences of a @r{<thing>}, and | |
718 | ||
719 | @format | |
720 | @r{<thing1>} @r{<thing2>} @dots{} | |
721 | @end format | |
722 | ||
723 | indicates one or more occurrences of a @r{<thing>}. | |
724 | ||
725 | If @var{category} is ``procedure'', then the entry describes a procedure, and | |
726 | the header line gives a template for a call to the procedure. Argument | |
727 | names in the template are @var{italicized}. Thus the header line | |
728 | ||
729 | ||
730 | @noindent | |
731 | @deffn {procedure} vector-ref @var{vector} @var{k} | |
732 | ||
733 | @end deffn | |
734 | ||
735 | indicates that the built-in procedure @t{vector-ref} takes | |
736 | two arguments, a vector @var{vector} and an exact non-negative integer | |
737 | @var{k} (see below). The header lines | |
738 | ||
739 | ||
740 | @noindent | |
741 | ||
742 | @deffn {procedure} make-vector @var{k} | |
743 | ||
744 | ||
745 | @deffnx {procedure} make-vector @var{k} @var{fill} | |
746 | ||
747 | @end deffn | |
748 | ||
749 | indicate that the @t{make-vector} procedure must be defined to take | |
750 | either one or two arguments. | |
751 | ||
752 | ||
753 | It is an error for an operation to be presented with an argument that it | |
754 | is not specified to handle. For succinctness, we follow the convention | |
755 | that if an argument name is also the name of a type listed in | |
756 | section @ref{Disjointness of types}, then that argument must be of the named type. | |
757 | For example, the header line for @t{vector-ref} given above dictates that the | |
758 | first argument to @t{vector-ref} must be a vector. The following naming | |
759 | conventions also imply type restrictions: | |
760 | @c \newcommand{\foo}[1]{\vr{#1}, \vri{#1}, $\ldots$ \vrj{#1}, $\ldots$} | |
761 | ||
762 | ||
763 | @center @c begin-tabular | |
764 | @quotation | |
765 | @table @asis | |
766 | @item @var{obj} | |
767 | any object | |
768 | @item @var{list}, @var{list1}, @dots{} @var{listj}, @dots{} | |
769 | list (see section @pxref{Pairs and lists}) | |
770 | @item @var{z}, @var{z1}, @dots{} @var{zj}, @dots{} | |
771 | complex number | |
772 | @item @var{x}, @var{x1}, @dots{} @var{xj}, @dots{} | |
773 | real number | |
774 | @item @var{y}, @var{y1}, @dots{} @var{yj}, @dots{} | |
775 | real number | |
776 | @item @var{q}, @var{q1}, @dots{} @var{qj}, @dots{} | |
777 | rational number | |
778 | @item @var{n}, @var{n1}, @dots{} @var{nj}, @dots{} | |
779 | integer | |
780 | @item @var{k}, @var{k1}, @dots{} @var{kj}, @dots{} | |
781 | exact non-negative integer | |
782 | @item | |
783 | @end table | |
784 | @end quotation | |
785 | ||
786 | ||
787 | ||
788 | ||
789 | @ignore todo | |
790 | Provide an example entry?? | |
791 | @end ignore | |
792 | ||
793 | ||
794 | ||
795 | @node Evaluation examples, Naming conventions, Entry format, Notation and terminology | |
796 | @subsection Evaluation examples | |
797 | ||
798 | ||
799 | The symbol ``@result{}'' used in program examples should be read | |
800 | ``evaluates to.'' For example, | |
801 | ||
802 | ||
803 | @example | |
804 | ||
805 | (* 5 8) ==> 40 | |
806 | ||
807 | @end example | |
808 | ||
809 | ||
810 | means that the expression @t{(* 5 8)} evaluates to the object @t{40}. | |
811 | Or, more precisely: the expression given by the sequence of characters | |
812 | ``@t{(* 5 8)}'' evaluates, in the initial environment, to an object | |
813 | that may be represented externally by the sequence of characters ``@t{40}''. See section @ref{External representations} for a discussion of external | |
814 | representations of objects. | |
815 | ||
816 | @node Naming conventions, , Evaluation examples, Notation and terminology | |
817 | @subsection Naming conventions | |
818 | ||
819 | ||
820 | By convention, the names of procedures that always return a boolean | |
821 | value usually end | |
822 | in ``@code{?}''. Such procedures are called predicates. | |
823 | @vindex @w{?} | |
824 | ||
825 | By convention, the names of procedures that store values into previously | |
826 | allocated locations (see section @pxref{Storage model}) usually end in | |
827 | ``@code{!}''. | |
828 | @vindex @w{!} | |
829 | Such procedures are called mutation procedures. | |
830 | By convention, the value returned by a mutation procedure is unspecified. | |
831 | ||
832 | By convention, ``@code{->}'' appears within the names of procedures that | |
833 | @vindex @w{->} | |
834 | take an object of one type and return an analogous object of another type. | |
835 | For example, @samp{list->vector} takes a list and returns a vector whose | |
836 | elements are the same as those of the list. | |
837 | ||
838 | ||
839 | ||
840 | @ignore todo | |
841 | Terms that need defining: thunk, command (what else?). | |
842 | @end ignore | |
843 | ||
844 | ||
845 | @c @include{lex} | |
846 | ||
847 | @c Lexical structure | |
848 | ||
849 | @c %\vfill\eject | |
850 | @node Lexical conventions, Basic concepts, Overview of Scheme, top | |
851 | @chapter Lexical conventions | |
852 | ||
853 | @menu | |
854 | * Identifiers:: | |
855 | * Whitespace and comments:: | |
856 | * Other notations:: | |
857 | @end menu | |
858 | ||
859 | ||
860 | This section gives an informal account of some of the lexical | |
861 | conventions used in writing Scheme programs. For a formal syntax of | |
862 | Scheme, see section @ref{Formal syntax}. | |
863 | ||
864 | Upper and lower case forms of a letter are never distinguished | |
865 | except within character and string constants. For example, @samp{Foo} is | |
866 | the same identifier as @samp{FOO}, and @t{#x1AB} is the same number as | |
867 | @t{#X1ab}. | |
868 | ||
869 | @node Identifiers, Whitespace and comments, Lexical conventions, Lexical conventions | |
870 | @section Identifiers | |
871 | ||
872 | ||
873 | ||
874 | Most identifiers allowed by other programming | |
875 | @cindex @w{identifier} | |
876 | languages are also acceptable to Scheme. The precise rules for forming | |
877 | identifiers vary among implementations of Scheme, but in all | |
878 | implementations a sequence of letters, digits, and ``extended alphabetic | |
879 | characters'' that begins with a character that cannot begin a number is | |
880 | an identifier. In addition, @code{+}, @code{-}, and @code{...} are identifiers. | |
881 | @vindex @w{...} | |
882 | @vindex @w{-} | |
883 | @vindex @w{+} | |
884 | Here are some examples of identifiers: | |
885 | ||
886 | ||
887 | @example | |
888 | ||
889 | lambda q | |
890 | list->vector soup | |
891 | + V17a | |
892 | <=? a34kTMNs | |
893 | the-word-recursion-has-many-meanings | |
894 | ||
895 | @end example | |
896 | ||
897 | ||
898 | Extended alphabetic characters may be used within identifiers as if | |
899 | they were letters. The following are extended alphabetic characters: | |
900 | ||
901 | ||
902 | @example | |
903 | ||
904 | ! $ % & * + - . / : < = > ? @@ ^ _ ~ | |
905 | @end example | |
906 | ||
907 | ||
908 | See section @ref{Lexical structure} for a formal syntax of identifiers. | |
909 | ||
910 | Identifiers have two uses within Scheme programs: | |
911 | ||
912 | ||
913 | @itemize @bullet | |
914 | ||
915 | @item | |
916 | Any identifier may be used as a variable | |
917 | or as a syntactic keyword | |
918 | (see sections @pxref{Variables; syntactic keywords; and regions} and @pxref{Macros}). | |
919 | ||
920 | @item | |
921 | When an identifier appears as a literal or within a literal | |
922 | (see section @pxref{Literal expressions}), it is being used to denote a @emph{symbol} | |
923 | (see section @pxref{Symbols}). | |
924 | ||
925 | ||
926 | @end itemize | |
927 | ||
928 | @cindex @w{syntactic keyword} | |
929 | @cindex @w{variable} | |
930 | ||
931 | @c \label{keywordsection} | |
932 | @c The following identifiers are syntactic keywords, and should not be used | |
933 | @c as variables: | |
934 | ||
935 | @c \begin{scheme} | |
936 | @c => do or | |
937 | @c and else quasiquote | |
938 | @c begin if quote | |
939 | @c case lambda set! | |
940 | @c cond let unquote | |
941 | @c define let* unquote-splicing | |
942 | @c delay letrec% | |
943 | @c \end{scheme} | |
944 | ||
945 | @c Some implementations allow all identifiers, including syntactic | |
946 | @c keywords, to be used as variables. This is a compatible extension to | |
947 | @c the language, but ambiguities in the language result when the | |
948 | @c restriction is relaxed, and the ways in which these ambiguities are | |
949 | @c resolved vary between implementations. | |
950 | ||
951 | ||
952 | @node Whitespace and comments, Other notations, Identifiers, Lexical conventions | |
953 | @section Whitespace and comments | |
954 | ||
955 | ||
956 | @dfn{Whitespace} characters are spaces and newlines. | |
957 | @cindex @w{Whitespace} | |
958 | (Implementations typically provide additional whitespace characters such | |
959 | as tab or page break.) Whitespace is used for improved readability and | |
960 | as necessary to separate tokens from each other, a token being an | |
961 | indivisible lexical unit such as an identifier or number, but is | |
962 | otherwise insignificant. Whitespace may occur between any two tokens, | |
963 | but not within a token. Whitespace may also occur inside a string, | |
964 | where it is significant. | |
965 | ||
966 | A semicolon (@t{;}) indicates the start of a | |
967 | comment. The comment continues to the | |
968 | @cindex @w{;} | |
969 | @cindex @w{comment} | |
970 | end of the line on which the semicolon appears. Comments are invisible | |
971 | to Scheme, but the end of the line is visible as whitespace. This | |
972 | prevents a comment from appearing in the middle of an identifier or | |
973 | number. | |
974 | ||
975 | ||
976 | @example | |
977 | ||
978 | ;;; The FACT procedure computes the factorial | |
979 | ;;; of a non-negative integer. | |
980 | (define fact | |
981 | (lambda (n) | |
982 | (if (= n 0) | |
983 | 1 ;Base case: return 1 | |
984 | (* n (fact (- n 1)))))) | |
985 | ||
986 | @end example | |
987 | ||
988 | ||
989 | ||
990 | @node Other notations, , Whitespace and comments, Lexical conventions | |
991 | @section Other notations | |
992 | ||
993 | ||
994 | @ignore todo | |
995 | Rewrite? | |
996 | @end ignore | |
997 | ||
998 | ||
999 | For a description of the notations used for numbers, see | |
1000 | section @ref{Numbers}. | |
1001 | ||
1002 | ||
1003 | @table @t | |
1004 | ||
1005 | ||
1006 | @item @t{.@: + -} | |
1007 | These are used in numbers, and may also occur anywhere in an identifier | |
1008 | except as the first character. A delimited plus or minus sign by itself | |
1009 | is also an identifier. | |
1010 | A delimited period (not occurring within a number or identifier) is used | |
1011 | in the notation for pairs (section @pxref{Pairs and lists}), and to indicate a | |
1012 | rest-parameter in a formal parameter list (section @pxref{Procedures}). | |
1013 | A delimited sequence of three successive periods is also an identifier. | |
1014 | ||
1015 | @item @t{( )} | |
1016 | Parentheses are used for grouping and to notate lists | |
1017 | (section @pxref{Pairs and lists}). | |
1018 | ||
1019 | @item @t{'} | |
1020 | The single quote character is used to indicate literal data (section @pxref{Literal expressions}). | |
1021 | ||
1022 | @item @t{`} | |
1023 | The backquote character is used to indicate almost-constant | |
1024 | data (section @pxref{Quasiquotation}). | |
1025 | ||
1026 | @item @t{, ,@@} | |
1027 | The character comma and the sequence comma at-sign are used in conjunction | |
1028 | with backquote (section @pxref{Quasiquotation}). | |
1029 | ||
1030 | @item @t{"} | |
1031 | The double quote character is used to delimit strings (section @pxref{Strings}). | |
1032 | ||
1033 | @item \ | |
1034 | Backslash is used in the syntax for character constants | |
1035 | (section @pxref{Characters}) and as an escape character within string | |
1036 | constants (section @pxref{Strings}). | |
1037 | ||
1038 | @c A box used because \verb is not allowed in command arguments. | |
1039 | ||
1040 | @item @w{@t{[ ] @{ @} |}} | |
1041 | Left and right square brackets and curly braces and vertical bar | |
1042 | are reserved for possible future extensions to the language. | |
1043 | ||
1044 | @item # | |
1045 | Sharp sign is used for a variety of purposes depending on | |
1046 | the character that immediately follows it: | |
1047 | ||
1048 | @item @t{#t} @t{#f} | |
1049 | These are the boolean constants (section @pxref{Booleans}). | |
1050 | ||
1051 | @item #\ | |
1052 | This introduces a character constant (section @pxref{Characters}). | |
1053 | ||
1054 | @item #@t{(} | |
1055 | This introduces a vector constant (section @pxref{Vectors}). Vector constants | |
1056 | are terminated by @t{)} . | |
1057 | ||
1058 | @item @t{#e #i #b #o #d #x} | |
1059 | These are used in the notation for numbers (section @pxref{Syntax of numerical constants}). | |
1060 | ||
1061 | @end table | |
1062 | ||
1063 | ||
1064 | @c @include{basic} | |
1065 | ||
1066 | @c \vfill\eject | |
1067 | @node Basic concepts, Expressions, Lexical conventions, top | |
1068 | @chapter Basic concepts | |
1069 | ||
1070 | @menu | |
1071 | * Variables; syntactic keywords; and regions:: | |
1072 | * Disjointness of types:: | |
1073 | * External representations:: | |
1074 | * Storage model:: | |
1075 | * Proper tail recursion:: | |
1076 | @end menu | |
1077 | ||
1078 | ||
1079 | ||
1080 | @node Variables; syntactic keywords; and regions, Disjointness of types, Basic concepts, Basic concepts | |
1081 | @section Variables; syntactic keywords; and regions | |
1082 | ||
1083 | ||
1084 | ||
1085 | ||
1086 | An identifier may name a type of syntax, or it may name | |
1087 | @cindex @w{identifier} | |
1088 | a location where a value can be stored. An identifier that names a type | |
1089 | of syntax is called a @emph{syntactic keyword} | |
1090 | @cindex @w{syntactic keyword} | |
1091 | and is said to be @emph{bound} to that syntax. An identifier that names a | |
1092 | location is called a @emph{variable} and is said to be | |
1093 | @cindex @w{variable} | |
1094 | @emph{bound} to that location. The set of all visible | |
1095 | bindings in effect at some point in a program is | |
1096 | @cindex @w{binding} | |
1097 | known as the @emph{environment} in effect at that point. The value | |
1098 | stored in the location to which a variable is bound is called the | |
1099 | variable's value. By abuse of terminology, the variable is sometimes | |
1100 | said to name the value or to be bound to the value. This is not quite | |
1101 | accurate, but confusion rarely results from this practice. | |
1102 | ||
1103 | @ignore todo | |
1104 | Define ``assigned'' and ``unassigned'' perhaps? | |
1105 | @end ignore | |
1106 | ||
1107 | ||
1108 | @ignore todo | |
1109 | In programs without side effects, one can safely pretend that the | |
1110 | variables are bound directly to the arguments. Or: | |
1111 | In programs without @code{set!}, one can safely pretend that the | |
1112 | @vindex @w{set!} | |
1113 | variable is bound directly to the value. | |
1114 | @end ignore | |
1115 | ||
1116 | ||
1117 | Certain expression types are used to create new kinds of syntax | |
1118 | and bind syntactic keywords to those new syntaxes, while other | |
1119 | expression types create new locations and bind variables to those | |
1120 | locations. These expression types are called @emph{binding constructs}. | |
1121 | ||
1122 | @cindex @w{binding construct} | |
1123 | Those that bind syntactic keywords are listed in section @ref{Macros}. | |
1124 | The most fundamental of the variable binding constructs is the | |
1125 | @samp{lambda} expression, because all other variable binding constructs | |
1126 | can be explained in terms of @samp{lambda} expressions. The other | |
1127 | variable binding constructs are @samp{let}, @samp{let*}, @samp{letrec}, | |
1128 | and @samp{do} expressions (see sections @pxref{Procedures}, @pxref{Binding constructs}, and | |
1129 | @pxref{Iteration}). | |
1130 | ||
1131 | @c Note: internal definitions not mentioned here. | |
1132 | ||
1133 | Like Algol and Pascal, and unlike most other dialects of Lisp | |
1134 | except for Common Lisp, Scheme is a statically scoped language with | |
1135 | block structure. To each place where an identifier is bound in a program | |
1136 | there corresponds a @dfn{region} of the program text within which | |
1137 | @cindex @w{region} | |
1138 | the binding is visible. The region is determined by the particular | |
1139 | binding construct that establishes the binding; if the binding is | |
1140 | established by a @samp{lambda} expression, for example, then its region | |
1141 | is the entire @samp{lambda} expression. Every mention of an identifier | |
1142 | refers to the binding of the identifier that established the | |
1143 | innermost of the regions containing the use. If there is no binding of | |
1144 | the identifier whose region contains the use, then the use refers to the | |
1145 | binding for the variable in the top level environment, if any | |
1146 | (chapters @pxref{Expressions} and @pxref{Standard procedures}); if there is no | |
1147 | binding for the identifier, | |
1148 | it is said to be @dfn{unbound}. | |
1149 | @cindex @w{top level environment} | |
1150 | @cindex @w{bound} | |
1151 | @cindex @w{unbound} | |
1152 | ||
1153 | @ignore todo | |
1154 | Mention that some implementations have multiple top level environments? | |
1155 | @end ignore | |
1156 | ||
1157 | ||
1158 | @ignore todo | |
1159 | Pitman sez: needs elaboration in case of @t{(let ...)} | |
1160 | @end ignore | |
1161 | ||
1162 | ||
1163 | @ignore todo | |
1164 | Pitman asks: say something about vars created after scheme starts? | |
1165 | @t{(define x 3) (define (f) x) (define (g) y) (define y 4)} | |
1166 | Clinger replies: The language was explicitly | |
1167 | designed to permit a view in which no variables are created after | |
1168 | Scheme starts. In files, you can scan out the definitions beforehand. | |
1169 | I think we're agreed on the principle that interactive use should | |
1170 | approximate that behavior as closely as possible, though we don't yet | |
1171 | agree on which programming environment provides the best approximation. | |
1172 | @end ignore | |
1173 | ||
1174 | ||
1175 | @node Disjointness of types, External representations, Variables; syntactic keywords; and regions, Basic concepts | |
1176 | @section Disjointness of types | |
1177 | ||
1178 | ||
1179 | ||
1180 | No object satisfies more than one of the following predicates: | |
1181 | ||
1182 | ||
1183 | @example | |
1184 | ||
1185 | boolean? pair? | |
1186 | symbol? number? | |
1187 | char? string? | |
1188 | vector? port? | |
1189 | procedure? | |
1190 | ||
1191 | @end example | |
1192 | ||
1193 | ||
1194 | These predicates define the types @emph{boolean}, @emph{pair}, @emph{symbol}, @emph{number}, @emph{char} (or @emph{character}), @emph{string}, @emph{vector}, @emph{port}, and @emph{procedure}. The empty list is a special | |
1195 | object of its own type; it satisfies none of the above predicates. | |
1196 | ||
1197 | @vindex symbol? | |
1198 | @vindex pair? | |
1199 | @vindex boolean? | |
1200 | @cindex @w{type} | |
1201 | ||
1202 | @vindex vector? | |
1203 | @vindex string? | |
1204 | @vindex char? | |
1205 | @vindex number? | |
1206 | ||
1207 | @cindex @w{empty list} | |
1208 | @vindex procedure? | |
1209 | @vindex port? | |
1210 | ||
1211 | Although there is a separate boolean type, | |
1212 | any Scheme value can be used as a boolean value for the purpose of a | |
1213 | conditional test. As explained in section @ref{Booleans}, all | |
1214 | values count as true in such a test except for @t{#f}. | |
1215 | @c and possibly the empty list. | |
1216 | @c The only value that is guaranteed to count as | |
1217 | @c false is \schfalse{}. It is explicitly unspecified whether the empty list | |
1218 | @c counts as true or as false. | |
1219 | This report uses the word ``true'' to refer to any | |
1220 | Scheme value except @t{#f}, and the word ``false'' to refer to | |
1221 | @t{#f}. | |
1222 | @cindex @w{false} | |
1223 | @cindex @w{true} | |
1224 | ||
1225 | @node External representations, Storage model, Disjointness of types, Basic concepts | |
1226 | @section External representations | |
1227 | ||
1228 | ||
1229 | ||
1230 | An important concept in Scheme (and Lisp) is that of the @emph{external | |
1231 | representation} of an object as a sequence of characters. For example, | |
1232 | an external representation of the integer 28 is the sequence of | |
1233 | characters ``@t{28}'', and an external representation of a list consisting | |
1234 | of the integers 8 and 13 is the sequence of characters ``@t{(8 13)}''. | |
1235 | ||
1236 | The external representation of an object is not necessarily unique. The | |
1237 | integer 28 also has representations ``@t{#e28.000}'' and ``@t{#x1c}'', and the | |
1238 | list in the previous paragraph also has the representations ``@t{( 08 13 | |
1239 | )}'' and ``@t{(8 .@: (13 .@: ()))}'' (see section @pxref{Pairs and lists}). | |
1240 | ||
1241 | Many objects have standard external representations, but some, such as | |
1242 | procedures, do not have standard representations (although particular | |
1243 | implementations may define representations for them). | |
1244 | ||
1245 | An external representation may be written in a program to obtain the | |
1246 | corresponding object (see @samp{quote}, section @pxref{Literal expressions}). | |
1247 | ||
1248 | External representations can also be used for input and output. The | |
1249 | procedure @samp{read} (section @pxref{Input}) parses external | |
1250 | representations, and the procedure @samp{write} (section @pxref{Output}) | |
1251 | generates them. Together, they provide an elegant and powerful | |
1252 | input/output facility. | |
1253 | ||
1254 | Note that the sequence of characters ``@t{(+ 2 6)}'' is @emph{not} an | |
1255 | external representation of the integer 8, even though it @emph{is} an | |
1256 | expression evaluating to the integer 8; rather, it is an external | |
1257 | representation of a three-element list, the elements of which are the symbol | |
1258 | @t{+} and the integers 2 and 6. Scheme's syntax has the property that | |
1259 | any sequence of characters that is an expression is also the external | |
1260 | representation of some object. This can lead to confusion, since it may | |
1261 | not be obvious out of context whether a given sequence of characters is | |
1262 | intended to denote data or program, but it is also a source of power, | |
1263 | since it facilitates writing programs such as interpreters and | |
1264 | compilers that treat programs as data (or vice versa). | |
1265 | ||
1266 | The syntax of external representations of various kinds of objects | |
1267 | accompanies the description of the primitives for manipulating the | |
1268 | objects in the appropriate sections of chapter @ref{Standard procedures}. | |
1269 | ||
1270 | @node Storage model, Proper tail recursion, External representations, Basic concepts | |
1271 | @section Storage model | |
1272 | ||
1273 | ||
1274 | ||
1275 | Variables and objects such as pairs, vectors, and strings implicitly | |
1276 | denote locations or sequences of locations. A string, for | |
1277 | @cindex @w{location} | |
1278 | example, denotes as many locations as there are characters in the string. | |
1279 | (These locations need not correspond to a full machine word.) A new value may be | |
1280 | stored into one of these locations using the @t{string-set!} procedure, but | |
1281 | the string continues to denote the same locations as before. | |
1282 | ||
1283 | An object fetched from a location, by a variable reference or by | |
1284 | a procedure such as @samp{car}, @samp{vector-ref}, or @samp{string-ref}, is | |
1285 | equivalent in the sense of @code{eqv?} | |
1286 | @c and \ide{eq?} ?? | |
1287 | (section @pxref{Equivalence predicates}) | |
1288 | @vindex @w{eqv?} | |
1289 | to the object last stored in the location before the fetch. | |
1290 | ||
1291 | Every location is marked to show whether it is in use. | |
1292 | No variable or object ever refers to a location that is not in use. | |
1293 | Whenever this report speaks of storage being allocated for a variable | |
1294 | or object, what is meant is that an appropriate number of locations are | |
1295 | chosen from the set of locations that are not in use, and the chosen | |
1296 | locations are marked to indicate that they are now in use before the variable | |
1297 | or object is made to denote them. | |
1298 | ||
1299 | In many systems it is desirable for constants (i.e. the values of | |
1300 | @cindex @w{constant} | |
1301 | literal expressions) to reside in read-only-memory. To express this, it is | |
1302 | convenient to imagine that every object that denotes locations is associated | |
1303 | with a flag telling whether that object is mutable or | |
1304 | @cindex @w{mutable} | |
1305 | immutable. In such systems literal constants and the strings | |
1306 | @cindex @w{immutable} | |
1307 | returned by @code{symbol->string} are immutable objects, while all objects | |
1308 | @vindex @w{symbol->string} | |
1309 | created by the other procedures listed in this report are mutable. It is an | |
1310 | error to attempt to store a new value into a location that is denoted by an | |
1311 | immutable object. | |
1312 | ||
1313 | @node Proper tail recursion, , Storage model, Basic concepts | |
1314 | @section Proper tail recursion | |
1315 | ||
1316 | ||
1317 | ||
1318 | Implementations of Scheme are required to be | |
1319 | @emph{properly tail-recursive}. | |
1320 | @cindex @w{proper tail recursion} | |
1321 | Procedure calls that occur in certain syntactic | |
1322 | contexts defined below are `tail calls'. A Scheme implementation is | |
1323 | properly tail-recursive if it supports an unbounded number of active | |
1324 | tail calls. A call is @emph{active} if the called procedure may still | |
1325 | return. Note that this includes calls that may be returned from either | |
1326 | by the current continuation or by continuations captured earlier by | |
1327 | @samp{call-with-current-continuation} that are later invoked. | |
1328 | In the absence of captured continuations, calls could | |
1329 | return at most once and the active calls would be those that had not | |
1330 | yet returned. | |
1331 | A formal definition of proper tail recursion can be found | |
1332 | in [propertailrecursion]. | |
1333 | ||
1334 | ||
1335 | @quotation | |
1336 | @emph{Rationale:} | |
1337 | ||
1338 | Intuitively, no space is needed for an active tail call because the | |
1339 | continuation that is used in the tail call has the same semantics as the | |
1340 | continuation passed to the procedure containing the call. Although an improper | |
1341 | implementation might use a new continuation in the call, a return | |
1342 | to this new continuation would be followed immediately by a return | |
1343 | to the continuation passed to the procedure. A properly tail-recursive | |
1344 | implementation returns to that continuation directly. | |
1345 | ||
1346 | Proper tail recursion was one of the central ideas in Steele and | |
1347 | Sussman's original version of Scheme. Their first Scheme interpreter | |
1348 | implemented both functions and actors. Control flow was expressed using | |
1349 | actors, which differed from functions in that they passed their results | |
1350 | on to another actor instead of returning to a caller. In the terminology | |
1351 | of this section, each actor finished with a tail call to another actor. | |
1352 | ||
1353 | Steele and Sussman later observed that in their interpreter the code | |
1354 | for dealing with actors was identical to that for functions and thus | |
1355 | there was no need to include both in the language. | |
1356 | ||
1357 | @end quotation | |
1358 | ||
1359 | ||
1360 | A @emph{tail call} is a procedure call that occurs | |
1361 | @cindex @w{tail call} | |
1362 | in a @emph{tail context}. Tail contexts are defined inductively. Note | |
1363 | that a tail context is always determined with respect to a particular lambda | |
1364 | expression. | |
1365 | ||
1366 | ||
1367 | ||
1368 | @itemize @bullet | |
1369 | ||
1370 | @item | |
1371 | The last expression within the body of a lambda expression, | |
1372 | shown as @r{<tail expression>} below, occurs in a tail context. | |
1373 | ||
1374 | @format | |
1375 | @t{(lambda <formals> | |
1376 | <definition>* <expression>* <tail expression>) | |
1377 | } | |
1378 | ||
1379 | @end format | |
1380 | ||
1381 | ||
1382 | ||
1383 | @item | |
1384 | If one of the following expressions is in a tail context, | |
1385 | then the subexpressions shown as <tail expression> are in a tail context. | |
1386 | These were derived from rules in the grammar given in | |
1387 | chapter @ref{Formal syntax and semantics} by replacing some occurrences of <expression> | |
1388 | with <tail expression>. Only those rules that contain tail contexts | |
1389 | are shown here. | |
1390 | ||
1391 | ||
1392 | @format | |
1393 | @t{(if <expression> <tail expression> <tail expression>) | |
1394 | (if <expression> <tail expression>) | |
1395 | ||
1396 | (cond <cond clause>+) | |
1397 | (cond <cond clause>* (else <tail sequence>)) | |
1398 | ||
1399 | (case <expression> | |
1400 | <case clause>+) | |
1401 | (case <expression> | |
1402 | <case clause>* | |
1403 | (else <tail sequence>)) | |
1404 | ||
1405 | (and <expression>* <tail expression>) | |
1406 | (or <expression>* <tail expression>) | |
1407 | ||
1408 | (let (<binding spec>*) <tail body>) | |
1409 | (let <variable> (<binding spec>*) <tail body>) | |
1410 | (let* (<binding spec>*) <tail body>) | |
1411 | (letrec (<binding spec>*) <tail body>) | |
1412 | ||
1413 | (let-syntax (<syntax spec>*) <tail body>) | |
1414 | (letrec-syntax (<syntax spec>*) <tail body>) | |
1415 | ||
1416 | (begin <tail sequence>) | |
1417 | ||
1418 | (do (<iteration spec>*) | |
1419 | (<test> <tail sequence>) | |
1420 | <expression>*) | |
1421 | ||
1422 | @r{where} | |
1423 | ||
1424 | <cond clause> --> (<test> <tail sequence>) | |
1425 | <case clause> --> ((<datum>*) <tail sequence>) | |
1426 | ||
1427 | <tail body> --> <definition>* <tail sequence> | |
1428 | <tail sequence> --> <expression>* <tail expression> | |
1429 | } | |
1430 | ||
1431 | @end format | |
1432 | ||
1433 | ||
1434 | ||
1435 | @item | |
1436 | If a @samp{cond} expression is in a tail context, and has a clause of | |
1437 | the form @samp{(@r{<expression1>} => @r{<expression2>})} | |
1438 | then the (implied) call to | |
1439 | the procedure that results from the evaluation of @r{<expression2>} is in a | |
1440 | tail context. @r{<expression2>} itself is not in a tail context. | |
1441 | ||
1442 | ||
1443 | @end itemize | |
1444 | ||
1445 | ||
1446 | Certain built-in procedures are also required to perform tail calls. | |
1447 | The first argument passed to @code{apply} and to | |
1448 | @vindex @w{apply} | |
1449 | @code{call-with-current-continuation}, and the second argument passed to | |
1450 | @vindex @w{call-with-current-continuation} | |
1451 | @code{call-with-values}, must be called via a tail call. | |
1452 | @vindex @w{call-with-values} | |
1453 | Similarly, @code{eval} must evaluate its argument as if it | |
1454 | @vindex @w{eval} | |
1455 | were in tail position within the @code{eval} procedure. | |
1456 | @vindex @w{eval} | |
1457 | ||
1458 | In the following example the only tail call is the call to @samp{f}. | |
1459 | None of the calls to @samp{g} or @samp{h} are tail calls. The reference to | |
1460 | @samp{x} is in a tail context, but it is not a call and thus is not a | |
1461 | tail call. | |
1462 | ||
1463 | @example | |
1464 | ||
1465 | (lambda () | |
1466 | (if (g) | |
1467 | (let ((x (h))) | |
1468 | x) | |
1469 | (and (g) (f)))) | |
1470 | ||
1471 | @end example | |
1472 | ||
1473 | ||
1474 | ||
1475 | @quotation | |
1476 | @emph{Note:} | |
1477 | Implementations are allowed, but not required, to | |
1478 | recognize that some non-tail calls, such as the call to @samp{h} | |
1479 | above, can be evaluated as though they were tail calls. | |
1480 | In the example above, the @samp{let} expression could be compiled | |
1481 | as a tail call to @samp{h}. (The possibility of @samp{h} returning | |
1482 | an unexpected number of values can be ignored, because in that | |
1483 | case the effect of the @samp{let} is explicitly unspecified and | |
1484 | implementation-dependent.) | |
1485 | @end quotation | |
1486 | ||
1487 | ||
1488 | ||
1489 | @c @include{expr} | |
1490 | ||
1491 | @c \vfill\eject | |
1492 | @node Expressions, Program structure, Basic concepts, top | |
1493 | @chapter Expressions | |
1494 | ||
1495 | @menu | |
1496 | * Primitive expression types:: | |
1497 | * Derived expression types:: | |
1498 | * Macros:: | |
1499 | @end menu | |
1500 | ||
1501 | ||
1502 | ||
1503 | @c \newcommand{\syntax}{{\em Syntax: }} | |
1504 | @c \newcommand{\semantics}{{\em Semantics: }} | |
1505 | ||
1506 | @c [Deleted for R5RS because of multiple-value returns. -RK] | |
1507 | @c A Scheme expression is a construct that returns a value, such as a | |
1508 | @c variable reference, literal, procedure call, or conditional. | |
1509 | ||
1510 | Expression types are categorized as @emph{primitive} or @emph{derived}. | |
1511 | Primitive expression types include variables and procedure calls. | |
1512 | Derived expression types are not semantically primitive, but can instead | |
1513 | be defined as macros. | |
1514 | With the exception of @samp{quasiquote}, whose macro definition is complex, | |
1515 | the derived expressions are classified as library features. | |
1516 | Suitable definitions are given in section @ref{Derived expression type}. | |
1517 | ||
1518 | @node Primitive expression types, Derived expression types, Expressions, Expressions | |
1519 | @section Primitive expression types | |
1520 | ||
1521 | @menu | |
1522 | * Variable references:: | |
1523 | * Literal expressions:: | |
1524 | * Procedure calls:: | |
1525 | * Procedures:: | |
1526 | * Conditionals:: | |
1527 | * Assignments:: | |
1528 | @end menu | |
1529 | ||
1530 | ||
1531 | ||
1532 | @node Variable references, Literal expressions, Primitive expression types, Primitive expression types | |
1533 | @subsection Variable references | |
1534 | ||
1535 | ||
1536 | ||
1537 | @deffn {syntax} @r{<variable>} | |
1538 | ||
1539 | ||
1540 | An expression consisting of a variable | |
1541 | @cindex @w{variable} | |
1542 | (section @pxref{Variables; syntactic keywords; and regions}) is a variable reference. The value of | |
1543 | the variable reference is the value stored in the location to which the | |
1544 | variable is bound. It is an error to reference an | |
1545 | unbound variable. | |
1546 | @cindex @w{unbound} | |
1547 | ||
1548 | ||
1549 | @format | |
1550 | @t{(define x 28) | |
1551 | x ==> 28 | |
1552 | } | |
1553 | @end format | |
1554 | ||
1555 | @end deffn | |
1556 | ||
1557 | @node Literal expressions, Procedure calls, Variable references, Primitive expression types | |
1558 | @subsection Literal expressions | |
1559 | ||
1560 | ||
1561 | ||
1562 | ||
1563 | @deffn {syntax} quote @r{<datum>} | |
1564 | ||
1565 | @deffnx {syntax} @t{'}@r{<datum>} | |
1566 | ||
1567 | ||
1568 | @deffnx {syntax} @r{<constant>} | |
1569 | ||
1570 | ||
1571 | @samp{(quote @r{<datum>})} evaluates to @r{<datum>}. | |
1572 | @cindex @w{'} | |
1573 | @r{<Datum>} | |
1574 | may be any external representation of a Scheme object (see | |
1575 | section @pxref{External representations}). This notation is used to include literal | |
1576 | constants in Scheme code. | |
1577 | ||
1578 | ||
1579 | @format | |
1580 | @t{ | |
1581 | (quote a) ==> a | |
1582 | (quote #(a b c)) ==> #(a b c) | |
1583 | (quote (+ 1 2)) ==> (+ 1 2) | |
1584 | } | |
1585 | @end format | |
1586 | ||
1587 | ||
1588 | @samp{(quote @r{<datum>})} may be abbreviated as | |
1589 | @t{'}@r{<datum>}. The two notations are equivalent in all | |
1590 | respects. | |
1591 | ||
1592 | ||
1593 | @format | |
1594 | @t{'a ==> a | |
1595 | '#(a b c) ==> #(a b c) | |
1596 | '() ==> () | |
1597 | '(+ 1 2) ==> (+ 1 2) | |
1598 | '(quote a) ==> (quote a) | |
1599 | ''a ==> (quote a) | |
1600 | } | |
1601 | @end format | |
1602 | ||
1603 | ||
1604 | Numerical constants, string constants, character constants, and boolean | |
1605 | constants evaluate ``to themselves''; they need not be quoted. | |
1606 | ||
1607 | ||
1608 | @format | |
1609 | @t{'"abc" ==> "abc" | |
1610 | "abc" ==> "abc" | |
1611 | '145932 ==> 145932 | |
1612 | 145932 ==> 145932 | |
1613 | '#t ==> #t | |
1614 | #t ==> #t | |
1615 | } | |
1616 | @end format | |
1617 | ||
1618 | ||
1619 | As noted in section @ref{Storage model}, it is an error to alter a constant | |
1620 | (i.e. the value of a literal expression) using a mutation procedure like | |
1621 | @samp{set-car!} or @samp{string-set!}. | |
1622 | ||
1623 | @end deffn | |
1624 | ||
1625 | ||
1626 | @node Procedure calls, Procedures, Literal expressions, Primitive expression types | |
1627 | @subsection Procedure calls | |
1628 | ||
1629 | ||
1630 | ||
1631 | @deffn {syntax} @r{<operator>} @r{<operand1>} @dots{}, | |
1632 | ||
1633 | ||
1634 | A procedure call is written by simply enclosing in parentheses | |
1635 | expressions for the procedure to be called and the arguments to be | |
1636 | passed to it. The operator and operand expressions are evaluated (in an | |
1637 | unspecified order) and the resulting procedure is passed the resulting | |
1638 | arguments. | |
1639 | @cindex @w{procedure call} | |
1640 | @cindex @w{call} | |
1641 | ||
1642 | @format | |
1643 | @t{ | |
1644 | (+ 3 4) ==> 7 | |
1645 | ((if #f + *) 3 4) ==> 12 | |
1646 | } | |
1647 | @end format | |
1648 | ||
1649 | ||
1650 | A number of procedures are available as the values of variables in the | |
1651 | initial environment; for example, the addition and multiplication | |
1652 | procedures in the above examples are the values of the variables @samp{+} | |
1653 | and @samp{*}. New procedures are created by evaluating lambda expressions | |
1654 | (see section @pxref{Procedures}). | |
1655 | @ignore todo | |
1656 | At Friedman's request, flushed mention of other ways. | |
1657 | @end ignore | |
1658 | ||
1659 | @c or definitions (see section~\ref{define}). | |
1660 | ||
1661 | Procedure calls may return any number of values (see @code{values} in | |
1662 | @vindex @w{values} | |
1663 | section @pxref{Control features}). With the exception of @samp{values} | |
1664 | the procedures available in the initial environment return one | |
1665 | value or, for procedures such as @samp{apply}, pass on the values returned | |
1666 | by a call to one of their arguments. | |
1667 | ||
1668 | Procedure calls are also called @emph{combinations}. | |
1669 | ||
1670 | @cindex @w{combination} | |
1671 | ||
1672 | ||
1673 | @quotation | |
1674 | @emph{Note:} In contrast to other dialects of Lisp, the order of | |
1675 | evaluation is unspecified, and the operator expression and the operand | |
1676 | expressions are always evaluated with the same evaluation rules. | |
1677 | @end quotation | |
1678 | ||
1679 | ||
1680 | ||
1681 | @quotation | |
1682 | @emph{Note:} | |
1683 | Although the order of evaluation is otherwise unspecified, the effect of | |
1684 | any concurrent evaluation of the operator and operand expressions is | |
1685 | constrained to be consistent with some sequential order of evaluation. | |
1686 | The order of evaluation may be chosen differently for each procedure call. | |
1687 | @end quotation | |
1688 | ||
1689 | ||
1690 | ||
1691 | @quotation | |
1692 | @emph{Note:} In many dialects of Lisp, the empty combination, @t{()}, is a legitimate expression. In Scheme, combinations must have at | |
1693 | least one subexpression, so @t{()} is not a syntactically valid | |
1694 | expression. | |
1695 | @ignore todo | |
1696 | Dybvig: ``it should be obvious from the syntax.'' | |
1697 | @end ignore | |
1698 | ||
1699 | @end quotation | |
1700 | ||
1701 | ||
1702 | @ignore todo | |
1703 | Freeman: | |
1704 | I think an explanation as to why evaluation order is not specified | |
1705 | should be included. It should not include any reference to parallel | |
1706 | evaluation. Does any existing compiler generate better code because | |
1707 | the evaluation order is unspecified? Clinger: yes: T3, MacScheme v2, | |
1708 | probably MIT Scheme and Chez Scheme. But that's not the main reason | |
1709 | for leaving the order unspecified. | |
1710 | @end ignore | |
1711 | ||
1712 | ||
1713 | @end deffn | |
1714 | ||
1715 | ||
1716 | @node Procedures, Conditionals, Procedure calls, Primitive expression types | |
1717 | @subsection Procedures | |
1718 | ||
1719 | ||
1720 | ||
1721 | ||
1722 | @deffn {syntax} lambda @r{<formals>} @r{<body>} | |
1723 | ||
1724 | @emph{Syntax:} | |
1725 | @r{<Formals>} should be a formal arguments list as described below, | |
1726 | and @r{<body>} should be a sequence of one or more expressions. | |
1727 | ||
1728 | @emph{Semantics:} | |
1729 | A lambda expression evaluates to a procedure. The environment in | |
1730 | effect when the lambda expression was evaluated is remembered as part of the | |
1731 | procedure. When the procedure is later called with some actual | |
1732 | arguments, the environment in which the lambda expression was evaluated will | |
1733 | be extended by binding the variables in the formal argument list to | |
1734 | fresh locations, the corresponding actual argument values will be stored | |
1735 | in those locations, and the expressions in the body of the lambda expression | |
1736 | will be evaluated sequentially in the extended environment. | |
1737 | The result(s) of the last expression in the body will be returned as | |
1738 | the result(s) of the procedure call. | |
1739 | ||
1740 | ||
1741 | @format | |
1742 | @t{(lambda (x) (+ x x)) ==> @emph{}a procedure | |
1743 | ((lambda (x) (+ x x)) 4) ==> 8 | |
1744 | ||
1745 | (define reverse-subtract | |
1746 | (lambda (x y) (- y x))) | |
1747 | (reverse-subtract 7 10) ==> 3 | |
1748 | ||
1749 | (define add4 | |
1750 | (let ((x 4)) | |
1751 | (lambda (y) (+ x y)))) | |
1752 | (add4 6) ==> 10 | |
1753 | } | |
1754 | @end format | |
1755 | ||
1756 | ||
1757 | @r{<Formals>} should have one of the following forms: | |
1758 | ||
1759 | ||
1760 | ||
1761 | @itemize @bullet | |
1762 | ||
1763 | @item | |
1764 | @t{(@r{<variable1>} @dots{},)}: | |
1765 | The procedure takes a fixed number of arguments; when the procedure is | |
1766 | called, the arguments will be stored in the bindings of the | |
1767 | corresponding variables. | |
1768 | ||
1769 | @item | |
1770 | @r{<variable>}: | |
1771 | The procedure takes any number of arguments; when the procedure is | |
1772 | called, the sequence of actual arguments is converted into a newly | |
1773 | allocated list, and the list is stored in the binding of the | |
1774 | @r{<variable>}. | |
1775 | ||
1776 | @item | |
1777 | @t{(@r{<variable1>} @dots{}, @r{<variable_n>} @b{.} | |
1778 | @r{<variable_n+1>})}: | |
1779 | If a space-delimited period precedes the last variable, then | |
1780 | the procedure takes n or more arguments, where n is the | |
1781 | number of formal arguments before the period (there must | |
1782 | be at least one). | |
1783 | The value stored in the binding of the last variable will be a | |
1784 | newly allocated | |
1785 | list of the actual arguments left over after all the other actual | |
1786 | arguments have been matched up against the other formal arguments. | |
1787 | ||
1788 | @end itemize | |
1789 | ||
1790 | ||
1791 | It is an error for a @r{<variable>} to appear more than once in | |
1792 | @r{<formals>}. | |
1793 | ||
1794 | ||
1795 | @format | |
1796 | @t{((lambda x x) 3 4 5 6) ==> (3 4 5 6) | |
1797 | ((lambda (x y . z) z) | |
1798 | 3 4 5 6) ==> (5 6) | |
1799 | } | |
1800 | @end format | |
1801 | ||
1802 | ||
1803 | Each procedure created as the result of evaluating a lambda expression is | |
1804 | (conceptually) tagged | |
1805 | with a storage location, in order to make @code{eqv?} and | |
1806 | @vindex @w{eqv?} | |
1807 | @code{eq?} work on procedures (see section @pxref{Equivalence predicates}). | |
1808 | @vindex @w{eq?} | |
1809 | ||
1810 | @end deffn | |
1811 | ||
1812 | ||
1813 | @node Conditionals, Assignments, Procedures, Primitive expression types | |
1814 | @subsection Conditionals | |
1815 | ||
1816 | ||
1817 | ||
1818 | @deffn {syntax} if @r{<test>} @r{<consequent>} @r{<alternate>} | |
1819 | @deffnx {syntax} if @r{<test>} @r{<consequent>} | |
1820 | @c \/ if hyper = italic | |
1821 | ||
1822 | @emph{Syntax:} | |
1823 | @r{<Test>}, @r{<consequent>}, and @r{<alternate>} may be arbitrary | |
1824 | expressions. | |
1825 | ||
1826 | @emph{Semantics:} | |
1827 | An @samp{if} expression is evaluated as follows: first, | |
1828 | @r{<test>} is evaluated. If it yields a true value (see | |
1829 | @cindex @w{true} | |
1830 | section @pxref{Booleans}), then @r{<consequent>} is evaluated and | |
1831 | its value(s) is(are) returned. Otherwise @r{<alternate>} is evaluated and its | |
1832 | value(s) is(are) returned. If @r{<test>} yields a false value and no | |
1833 | @r{<alternate>} is specified, then the result of the expression is | |
1834 | unspecified. | |
1835 | ||
1836 | ||
1837 | @format | |
1838 | @t{(if (> 3 2) 'yes 'no) ==> yes | |
1839 | (if (> 2 3) 'yes 'no) ==> no | |
1840 | (if (> 3 2) | |
1841 | (- 3 2) | |
1842 | (+ 3 2)) ==> 1 | |
1843 | } | |
1844 | @end format | |
1845 | ||
1846 | ||
1847 | @end deffn | |
1848 | ||
1849 | ||
1850 | @node Assignments, , Conditionals, Primitive expression types | |
1851 | @subsection Assignments | |
1852 | ||
1853 | ||
1854 | ||
1855 | ||
1856 | @deffn {syntax} set! @r{<variable>} @r{<expression>} | |
1857 | ||
1858 | @r{<Expression>} is evaluated, and the resulting value is stored in | |
1859 | the location to which @r{<variable>} is bound. @r{<Variable>} must | |
1860 | be bound either in some region enclosing the @samp{set!} expression | |
1861 | @cindex @w{region} | |
1862 | or at top level. The result of the @samp{set!} expression is | |
1863 | unspecified. | |
1864 | ||
1865 | ||
1866 | @format | |
1867 | @t{(define x 2) | |
1868 | (+ x 1) ==> 3 | |
1869 | (set! x 4) ==> @emph{unspecified} | |
1870 | (+ x 1) ==> 5 | |
1871 | } | |
1872 | @end format | |
1873 | ||
1874 | ||
1875 | @end deffn | |
1876 | ||
1877 | ||
1878 | @node Derived expression types, Macros, Primitive expression types, Expressions | |
1879 | @section Derived expression types | |
1880 | ||
1881 | @menu | |
1882 | * Conditional:: | |
1883 | * Binding constructs:: | |
1884 | * Sequencing:: | |
1885 | * Iteration:: | |
1886 | * Delayed evaluation:: | |
1887 | * Quasiquotation:: | |
1888 | @end menu | |
1889 | ||
1890 | ||
1891 | ||
1892 | The constructs in this section are hygienic, as discussed in | |
1893 | section @ref{Macros}. | |
1894 | For reference purposes, section @ref{Derived expression type} gives macro definitions | |
1895 | that will convert most of the constructs described in this section | |
1896 | into the primitive constructs described in the previous section. | |
1897 | ||
1898 | @ignore todo | |
1899 | Mention that no definition of backquote is provided? | |
1900 | @end ignore | |
1901 | ||
1902 | ||
1903 | @node Conditional, Binding constructs, Derived expression types, Derived expression types | |
1904 | @subsection Conditionals | |
1905 | ||
1906 | ||
1907 | ||
1908 | @deffn {library syntax} cond <clause1> <clause2> @dots{}, | |
1909 | ||
1910 | @emph{Syntax:} | |
1911 | Each @r{<clause>} should be of the form | |
1912 | ||
1913 | @format | |
1914 | @t{(@r{<test>} @r{<expression1>} @dots{},) | |
1915 | } | |
1916 | @end format | |
1917 | ||
1918 | where @r{<test>} is any expression. Alternatively, a @r{<clause>} may be | |
1919 | of the form | |
1920 | ||
1921 | @format | |
1922 | @t{(@r{<test>} => @r{<expression>}) | |
1923 | } | |
1924 | @end format | |
1925 | ||
1926 | The last @r{<clause>} may be | |
1927 | an ``else clause,'' which has the form | |
1928 | ||
1929 | @format | |
1930 | @t{(else @r{<expression1>} @r{<expression2>} @dots{},)@r{.} | |
1931 | } | |
1932 | @end format | |
1933 | ||
1934 | ||
1935 | @cindex @w{else} | |
1936 | ||
1937 | @cindex @w{=>} | |
1938 | ||
1939 | @emph{Semantics:} | |
1940 | A @samp{cond} expression is evaluated by evaluating the @r{<test>} | |
1941 | expressions of successive @r{<clause>}s in order until one of them | |
1942 | evaluates to a true value (see | |
1943 | @cindex @w{true} | |
1944 | section @pxref{Booleans}). When a @r{<test>} evaluates to a true | |
1945 | value, then the remaining @r{<expression>}s in its @r{<clause>} are | |
1946 | evaluated in order, and the result(s) of the last @r{<expression>} in the | |
1947 | @r{<clause>} is(are) returned as the result(s) of the entire @samp{cond} | |
1948 | expression. If the selected @r{<clause>} contains only the | |
1949 | @r{<test>} and no @r{<expression>}s, then the value of the | |
1950 | @r{<test>} is returned as the result. If the selected @r{<clause>} uses the | |
1951 | @code{=>} alternate form, then the @r{<expression>} is evaluated. | |
1952 | @vindex @w{=>} | |
1953 | Its value must be a procedure that accepts one argument; this procedure is then | |
1954 | called on the value of the @r{<test>} and the value(s) returned by this | |
1955 | procedure is(are) returned by the @samp{cond} expression. | |
1956 | If all @r{<test>}s evaluate | |
1957 | to false values, and there is no else clause, then the result of | |
1958 | the conditional expression is unspecified; if there is an else | |
1959 | clause, then its @r{<expression>}s are evaluated, and the value(s) of | |
1960 | the last one is(are) returned. | |
1961 | ||
1962 | ||
1963 | @format | |
1964 | @t{(cond ((> 3 2) 'greater) | |
1965 | ((< 3 2) 'less)) ==> greater | |
1966 | ||
1967 | (cond ((> 3 3) 'greater) | |
1968 | ((< 3 3) 'less) | |
1969 | (else 'equal)) ==> equal | |
1970 | ||
1971 | (cond ((assv 'b '((a 1) (b 2))) => cadr) | |
1972 | (else #f)) ==> 2 | |
1973 | } | |
1974 | @end format | |
1975 | ||
1976 | ||
1977 | ||
1978 | @end deffn | |
1979 | ||
1980 | ||
1981 | ||
1982 | @deffn {library syntax} case @r{<key>} <clause1> <clause2> @dots{}, | |
1983 | ||
1984 | @emph{Syntax:} | |
1985 | @r{<Key>} may be any expression. Each @r{<clause>} should have | |
1986 | the form | |
1987 | ||
1988 | @format | |
1989 | @t{((@r{<datum1>} @dots{},) @r{<expression1>} @r{<expression2>} @dots{},)@r{,} | |
1990 | } | |
1991 | @end format | |
1992 | ||
1993 | where each @r{<datum>} is an external representation of some object. | |
1994 | All the @r{<datum>}s must be distinct. | |
1995 | The last @r{<clause>} may be an ``else clause,'' which has the form | |
1996 | ||
1997 | @format | |
1998 | @t{(else @r{<expression1>} @r{<expression2>} @dots{},)@r{.} | |
1999 | } | |
2000 | @end format | |
2001 | ||
2002 | ||
2003 | @vindex else | |
2004 | ||
2005 | @emph{Semantics:} | |
2006 | A @samp{case} expression is evaluated as follows. @r{<Key>} is | |
2007 | evaluated and its result is compared against each @r{<datum>}. If the | |
2008 | result of evaluating @r{<key>} is equivalent (in the sense of | |
2009 | @samp{eqv?}; see section @pxref{Equivalence predicates}) to a @r{<datum>}, then the | |
2010 | expressions in the corresponding @r{<clause>} are evaluated from left | |
2011 | to right and the result(s) of the last expression in the @r{<clause>} is(are) | |
2012 | returned as the result(s) of the @samp{case} expression. If the result of | |
2013 | evaluating @r{<key>} is different from every @r{<datum>}, then if | |
2014 | there is an else clause its expressions are evaluated and the | |
2015 | result(s) of the last is(are) the result(s) of the @samp{case} expression; | |
2016 | otherwise the result of the @samp{case} expression is unspecified. | |
2017 | ||
2018 | ||
2019 | @format | |
2020 | @t{(case (* 2 3) | |
2021 | ((2 3 5 7) 'prime) | |
2022 | ((1 4 6 8 9) 'composite)) ==> composite | |
2023 | (case (car '(c d)) | |
2024 | ((a) 'a) | |
2025 | ((b) 'b)) ==> @emph{unspecified} | |
2026 | (case (car '(c d)) | |
2027 | ((a e i o u) 'vowel) | |
2028 | ((w y) 'semivowel) | |
2029 | (else 'consonant)) ==> consonant | |
2030 | } | |
2031 | @end format | |
2032 | ||
2033 | ||
2034 | @end deffn | |
2035 | ||
2036 | ||
2037 | ||
2038 | @deffn {library syntax} and <test1> @dots{}, | |
2039 | ||
2040 | The @r{<test>} expressions are evaluated from left to right, and the | |
2041 | value of the first expression that evaluates to a false value (see | |
2042 | section @pxref{Booleans}) is returned. Any remaining expressions | |
2043 | are not evaluated. If all the expressions evaluate to true values, the | |
2044 | value of the last expression is returned. If there are no expressions | |
2045 | then @t{#t} is returned. | |
2046 | ||
2047 | ||
2048 | @format | |
2049 | @t{(and (= 2 2) (> 2 1)) ==> #t | |
2050 | (and (= 2 2) (< 2 1)) ==> #f | |
2051 | (and 1 2 'c '(f g)) ==> (f g) | |
2052 | (and) ==> #t | |
2053 | } | |
2054 | @end format | |
2055 | ||
2056 | ||
2057 | @end deffn | |
2058 | ||
2059 | ||
2060 | ||
2061 | @deffn {library syntax} or <test1> @dots{}, | |
2062 | ||
2063 | The @r{<test>} expressions are evaluated from left to right, and the value of the | |
2064 | first expression that evaluates to a true value (see | |
2065 | section @pxref{Booleans}) is returned. Any remaining expressions | |
2066 | are not evaluated. If all expressions evaluate to false values, the | |
2067 | value of the last expression is returned. If there are no | |
2068 | expressions then @t{#f} is returned. | |
2069 | ||
2070 | ||
2071 | @format | |
2072 | @t{(or (= 2 2) (> 2 1)) ==> #t | |
2073 | (or (= 2 2) (< 2 1)) ==> #t | |
2074 | (or #f #f #f) ==> #f | |
2075 | (or (memq 'b '(a b c)) | |
2076 | (/ 3 0)) ==> (b c) | |
2077 | } | |
2078 | @end format | |
2079 | ||
2080 | ||
2081 | @end deffn | |
2082 | ||
2083 | ||
2084 | @node Binding constructs, Sequencing, Conditional, Derived expression types | |
2085 | @subsection Binding constructs | |
2086 | ||
2087 | ||
2088 | The three binding constructs @samp{let}, @samp{let*}, and @samp{letrec} | |
2089 | give Scheme a block structure, like Algol 60. The syntax of the three | |
2090 | constructs is identical, but they differ in the regions they establish | |
2091 | @cindex @w{region} | |
2092 | for their variable bindings. In a @samp{let} expression, the initial | |
2093 | values are computed before any of the variables become bound; in a | |
2094 | @samp{let*} expression, the bindings and evaluations are performed | |
2095 | sequentially; while in a @samp{letrec} expression, all the bindings are in | |
2096 | effect while their initial values are being computed, thus allowing | |
2097 | mutually recursive definitions. | |
2098 | ||
2099 | ||
2100 | @deffn {library syntax} let @r{<bindings>} @r{<body>} | |
2101 | ||
2102 | @emph{Syntax:} | |
2103 | @r{<Bindings>} should have the form | |
2104 | ||
2105 | @format | |
2106 | @t{((@r{<variable1>} @r{<init1>}) @dots{},)@r{,} | |
2107 | } | |
2108 | @end format | |
2109 | ||
2110 | where each @r{<init>} is an expression, and @r{<body>} should be a | |
2111 | sequence of one or more expressions. It is | |
2112 | an error for a @r{<variable>} to appear more than once in the list of variables | |
2113 | being bound. | |
2114 | ||
2115 | @emph{Semantics:} | |
2116 | The @r{<init>}s are evaluated in the current environment (in some | |
2117 | unspecified order), the @r{<variable>}s are bound to fresh locations | |
2118 | holding the results, the @r{<body>} is evaluated in the extended | |
2119 | environment, and the value(s) of the last expression of @r{<body>} | |
2120 | is(are) returned. Each binding of a @r{<variable>} has @r{<body>} as its | |
2121 | region. | |
2122 | @cindex @w{region} | |
2123 | ||
2124 | ||
2125 | @format | |
2126 | @t{(let ((x 2) (y 3)) | |
2127 | (* x y)) ==> 6 | |
2128 | ||
2129 | (let ((x 2) (y 3)) | |
2130 | (let ((x 7) | |
2131 | (z (+ x y))) | |
2132 | (* z x))) ==> 35 | |
2133 | } | |
2134 | @end format | |
2135 | ||
2136 | ||
2137 | See also named @samp{let}, section @ref{Iteration}. | |
2138 | ||
2139 | @end deffn | |
2140 | ||
2141 | ||
2142 | ||
2143 | @deffn {library syntax} let* @r{<bindings>} @r{<body>} | |
2144 | ||
2145 | ||
2146 | @emph{Syntax:} | |
2147 | @r{<Bindings>} should have the form | |
2148 | ||
2149 | @format | |
2150 | @t{((@r{<variable1>} @r{<init1>}) @dots{},)@r{,} | |
2151 | } | |
2152 | @end format | |
2153 | ||
2154 | and @r{<body>} should be a sequence of | |
2155 | one or more expressions. | |
2156 | ||
2157 | @emph{Semantics:} | |
7fb9c4af | 2158 | @samp{Let*} is similar to @samp{let}, but the bindings are performed |
a0e07ba4 NJ |
2159 | sequentially from left to right, and the region of a binding indicated |
2160 | @cindex @w{region} | |
2161 | by @samp{(@r{<variable>} @r{<init>})} is that part of the @samp{let*} | |
2162 | expression to the right of the binding. Thus the second binding is done | |
2163 | in an environment in which the first binding is visible, and so on. | |
2164 | ||
2165 | ||
2166 | @format | |
2167 | @t{(let ((x 2) (y 3)) | |
2168 | (let* ((x 7) | |
2169 | (z (+ x y))) | |
2170 | (* z x))) ==> 70 | |
2171 | } | |
2172 | @end format | |
2173 | ||
2174 | ||
2175 | @end deffn | |
2176 | ||
2177 | ||
2178 | ||
2179 | @deffn {library syntax} letrec @r{<bindings>} @r{<body>} | |
2180 | ||
2181 | @emph{Syntax:} | |
2182 | @r{<Bindings>} should have the form | |
2183 | ||
2184 | @format | |
2185 | @t{((@r{<variable1>} @r{<init1>}) @dots{},)@r{,} | |
2186 | } | |
2187 | @end format | |
2188 | ||
2189 | and @r{<body>} should be a sequence of | |
2190 | one or more expressions. It is an error for a @r{<variable>} to appear more | |
2191 | than once in the list of variables being bound. | |
2192 | ||
2193 | @emph{Semantics:} | |
2194 | The @r{<variable>}s are bound to fresh locations holding undefined | |
2195 | values, the @r{<init>}s are evaluated in the resulting environment (in | |
2196 | some unspecified order), each @r{<variable>} is assigned to the result | |
2197 | of the corresponding @r{<init>}, the @r{<body>} is evaluated in the | |
2198 | resulting environment, and the value(s) of the last expression in | |
2199 | @r{<body>} is(are) returned. Each binding of a @r{<variable>} has the | |
2200 | entire @samp{letrec} expression as its region, making it possible to | |
2201 | @cindex @w{region} | |
2202 | define mutually recursive procedures. | |
2203 | ||
2204 | ||
2205 | @format | |
2206 | @t{(letrec ((even? | |
2207 | (lambda (n) | |
2208 | (if (zero? n) | |
2209 | #t | |
2210 | (odd? (- n 1))))) | |
2211 | (odd? | |
2212 | (lambda (n) | |
2213 | (if (zero? n) | |
2214 | #f | |
2215 | (even? (- n 1)))))) | |
2216 | (even? 88)) | |
2217 | ==> #t | |
2218 | } | |
2219 | @end format | |
2220 | ||
2221 | ||
2222 | One restriction on @samp{letrec} is very important: it must be possible | |
2223 | to evaluate each @r{<init>} without assigning or referring to the value of any | |
2224 | @r{<variable>}. If this restriction is violated, then it is an error. The | |
2225 | restriction is necessary because Scheme passes arguments by value rather than by | |
2226 | name. In the most common uses of @samp{letrec}, all the @r{<init>}s are | |
2227 | lambda expressions and the restriction is satisfied automatically. | |
2228 | ||
2229 | @c \todo{use or uses? --- Jinx.} | |
2230 | ||
2231 | @end deffn | |
2232 | ||
2233 | ||
2234 | @node Sequencing, Iteration, Binding constructs, Derived expression types | |
2235 | @subsection Sequencing | |
2236 | ||
2237 | ||
2238 | ||
2239 | @deffn {library syntax} begin <expression1> <expression2> @dots{}, | |
2240 | ||
2241 | The @r{<expression>}s are evaluated sequentially from left to right, | |
2242 | and the value(s) of the last @r{<expression>} is(are) returned. This | |
2243 | expression type is used to sequence side effects such as input and | |
2244 | output. | |
2245 | ||
2246 | ||
2247 | @format | |
2248 | @t{(define x 0) | |
2249 | ||
2250 | (begin (set! x 5) | |
2251 | (+ x 1)) ==> 6 | |
2252 | ||
2253 | (begin (display "4 plus 1 equals ") | |
2254 | (display (+ 4 1))) ==> @emph{unspecified} | |
2255 | @emph{and prints} 4 plus 1 equals 5 | |
2256 | } | |
2257 | @end format | |
2258 | ||
2259 | ||
2260 | @end deffn | |
2261 | ||
2262 | ||
2263 | @node Iteration, Delayed evaluation, Sequencing, Derived expression types | |
2264 | @subsection Iteration | |
2265 | ||
2266 | @c \unsection | |
2267 | ||
2268 | ||
2269 | @noindent | |
2270 | ||
2271 | @deffn {library syntax} do ((@r{<variable1>} @r{<init1>} @r{<step1>}) @dots{}) (@r{<test>} @r{<expression>} @dots{}) @r{<command>} @dots{} | |
2272 | @cindex @w{do} | |
2273 | ||
7fb9c4af | 2274 | @samp{Do} is an iteration construct. It specifies a set of variables to |
a0e07ba4 NJ |
2275 | be bound, how they are to be initialized at the start, and how they are |
2276 | to be updated on each iteration. When a termination condition is met, | |
2277 | the loop exits after evaluating the @r{<expression>}s. | |
2278 | ||
7fb9c4af | 2279 | @samp{Do} expressions are evaluated as follows: |
a0e07ba4 NJ |
2280 | The @r{<init>} expressions are evaluated (in some unspecified order), |
2281 | the @r{<variable>}s are bound to fresh locations, the results of the | |
2282 | @r{<init>} expressions are stored in the bindings of the | |
2283 | @r{<variable>}s, and then the iteration phase begins. | |
2284 | ||
2285 | Each iteration begins by evaluating @r{<test>}; if the result is | |
2286 | false (see section @pxref{Booleans}), then the @r{<command>} | |
2287 | expressions are evaluated in order for effect, the @r{<step>} | |
2288 | expressions are evaluated in some unspecified order, the | |
2289 | @r{<variable>}s are bound to fresh locations, the results of the | |
2290 | @r{<step>}s are stored in the bindings of the | |
2291 | @r{<variable>}s, and the next iteration begins. | |
2292 | ||
2293 | If @r{<test>} evaluates to a true value, then the | |
2294 | @r{<expression>}s are evaluated from left to right and the value(s) of | |
2295 | the last @r{<expression>} is(are) returned. If no @r{<expression>}s | |
2296 | are present, then the value of the @samp{do} expression is unspecified. | |
2297 | ||
2298 | The region of the binding of a @r{<variable>} | |
2299 | @cindex @w{region} | |
2300 | consists of the entire @samp{do} expression except for the @r{<init>}s. | |
2301 | It is an error for a @r{<variable>} to appear more than once in the | |
2302 | list of @samp{do} variables. | |
2303 | ||
2304 | A @r{<step>} may be omitted, in which case the effect is the | |
2305 | same as if @samp{(@r{<variable>} @r{<init>} @r{<variable>})} had | |
2306 | been written instead of @samp{(@r{<variable>} @r{<init>})}. | |
2307 | ||
2308 | ||
2309 | @format | |
2310 | @t{(do ((vec (make-vector 5)) | |
2311 | (i 0 (+ i 1))) | |
2312 | ((= i 5) vec) | |
2313 | (vector-set! vec i i)) ==> #(0 1 2 3 4) | |
2314 | ||
2315 | (let ((x '(1 3 5 7 9))) | |
2316 | (do ((x x (cdr x)) | |
2317 | (sum 0 (+ sum (car x)))) | |
2318 | ((null? x) sum))) ==> 25 | |
2319 | } | |
2320 | @end format | |
2321 | ||
2322 | ||
2323 | @c \end{entry} | |
2324 | @end deffn | |
2325 | ||
2326 | ||
2327 | @deffn {library syntax} let @r{<variable>} @r{<bindings>} @r{<body>} | |
2328 | ||
2329 | ||
2330 | ``Named @samp{let}'' is a variant on the syntax of @code{let} which provides | |
2331 | @vindex @w{let} | |
2332 | a more general looping construct than @samp{do} and may also be used to express | |
2333 | recursions. | |
2334 | It has the same syntax and semantics as ordinary @samp{let} | |
2335 | except that @r{<variable>} is bound within @r{<body>} to a procedure | |
2336 | whose formal arguments are the bound variables and whose body is | |
2337 | @r{<body>}. Thus the execution of @r{<body>} may be repeated by | |
2338 | invoking the procedure named by @r{<variable>}. | |
2339 | ||
2340 | @c | <-- right margin | |
2341 | ||
2342 | @format | |
2343 | @t{(let loop ((numbers '(3 -2 1 6 -5)) | |
2344 | (nonneg '()) | |
2345 | (neg '())) | |
2346 | (cond ((null? numbers) (list nonneg neg)) | |
2347 | ((>= (car numbers) 0) | |
2348 | (loop (cdr numbers) | |
2349 | (cons (car numbers) nonneg) | |
2350 | neg)) | |
2351 | ((< (car numbers) 0) | |
2352 | (loop (cdr numbers) | |
2353 | nonneg | |
2354 | (cons (car numbers) neg))))) | |
2355 | ==> ((6 1 3) (-5 -2)) | |
2356 | } | |
2357 | @end format | |
2358 | ||
2359 | ||
2360 | @end deffn | |
2361 | ||
2362 | ||
2363 | @node Delayed evaluation, Quasiquotation, Iteration, Derived expression types | |
2364 | @subsection Delayed evaluation | |
2365 | ||
2366 | ||
2367 | ||
2368 | @deffn {library syntax} delay @r{<expression>} | |
2369 | ||
2370 | @ignore todo | |
2371 | Fix. | |
2372 | @end ignore | |
2373 | ||
2374 | ||
2375 | The @samp{delay} construct is used together with the procedure @code{force} to | |
2376 | @vindex @w{force} | |
2377 | implement @dfn{lazy evaluation} or @dfn{call by need}. | |
2378 | @cindex @w{call by need} | |
2379 | @cindex @w{lazy evaluation} | |
2380 | @t{(delay @r{<expression>})} returns an object called a | |
2381 | @dfn{promise} which at some point in the future may be asked (by | |
2382 | @cindex @w{promise} | |
2383 | the @samp{force} procedure) | |
2384 | @ignore todo | |
2385 | Bartley's white lie; OK? | |
2386 | @end ignore | |
2387 | to evaluate | |
2388 | @r{<expression>}, and deliver the resulting value. | |
2389 | The effect of @r{<expression>} returning multiple values | |
2390 | is unspecified. | |
2391 | ||
2392 | See the description of @samp{force} (section @pxref{Control features}) for a | |
2393 | more complete description of @samp{delay}. | |
2394 | ||
2395 | @end deffn | |
2396 | ||
2397 | ||
2398 | @node Quasiquotation, , Delayed evaluation, Derived expression types | |
2399 | @subsection Quasiquotation | |
2400 | ||
2401 | ||
2402 | ||
2403 | ||
2404 | @deffn {syntax} quasiquote @r{<qq template>} | |
2405 | ||
2406 | @deffnx {syntax} @t{`}@r{<qq template>} | |
2407 | ||
2408 | ||
2409 | ``Backquote'' or ``quasiquote'' expressions are useful | |
2410 | @cindex @w{backquote} | |
2411 | for constructing a list or vector structure when most but not all of the | |
2412 | desired structure is known in advance. If no | |
2413 | commas appear within the @r{<qq template>}, the result of | |
2414 | @cindex @w{comma} | |
2415 | evaluating | |
2416 | @t{`}@r{<qq template>} is equivalent to the result of evaluating | |
2417 | @t{'}@r{<qq template>}. If a comma appears within the | |
2418 | @cindex @w{,} | |
2419 | @r{<qq template>}, however, the expression following the comma is | |
2420 | evaluated (``unquoted'') and its result is inserted into the structure | |
2421 | instead of the comma and the expression. If a comma appears followed | |
2422 | immediately by an at-sign (@@), then the following | |
2423 | @cindex @w{,@@} | |
2424 | expression must evaluate to a list; the opening and closing parentheses | |
2425 | of the list are then ``stripped away'' and the elements of the list are | |
2426 | inserted in place of the comma at-sign expression sequence. A comma | |
2427 | at-sign should only appear within a list or vector @r{<qq template>}. | |
2428 | ||
2429 | @c struck: "(in the sense of {\cf equal?})" after "equivalent" | |
2430 | ||
2431 | ||
2432 | @format | |
2433 | @t{`(list ,(+ 1 2) 4) ==> (list 3 4) | |
2434 | (let ((name 'a)) `(list ,name ',name)) | |
2435 | ==> (list a (quote a)) | |
2436 | `(a ,(+ 1 2) ,@@(map abs '(4 -5 6)) b) | |
2437 | ==> (a 3 4 5 6 b) | |
2438 | `((@samp{foo} ,(- 10 3)) ,@@(cdr '(c)) . ,(car '(cons))) | |
2439 | ==> ((foo 7) . cons) | |
2440 | `#(10 5 ,(sqrt 4) ,@@(map sqrt '(16 9)) 8) | |
2441 | ==> #(10 5 2 4 3 8) | |
2442 | } | |
2443 | @end format | |
2444 | ||
2445 | ||
2446 | Quasiquote forms may be nested. Substitutions are made only for | |
2447 | unquoted components appearing at the same nesting level | |
2448 | as the outermost backquote. The nesting level increases by one inside | |
2449 | each successive quasiquotation, and decreases by one inside each | |
2450 | unquotation. | |
2451 | ||
2452 | ||
2453 | @format | |
2454 | @t{`(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f) | |
2455 | ==> (a `(b ,(+ 1 2) ,(foo 4 d) e) f) | |
2456 | (let ((name1 'x) | |
2457 | (name2 'y)) | |
2458 | `(a `(b ,,name1 ,',name2 d) e)) | |
2459 | ==> (a `(b ,x ,'y d) e) | |
2460 | } | |
2461 | @end format | |
2462 | ||
2463 | ||
2464 | The two notations | |
2465 | @t{`}@r{<qq template>} and @t{(quasiquote @r{<qq template>})} | |
2466 | are identical in all respects. | |
2467 | @samp{,@r{<expression>}} is identical to @samp{(unquote @r{<expression>})}, | |
2468 | and | |
2469 | @samp{,@@@r{<expression>}} is identical to @samp{(unquote-splicing @r{<expression>})}. | |
2470 | The external syntax generated by @code{write} for two-element lists whose | |
2471 | @vindex @w{write} | |
2472 | car is one of these symbols may vary between implementations. | |
2473 | ||
2474 | @cindex @w{`} | |
2475 | ||
2476 | ||
2477 | @format | |
2478 | @t{(quasiquote (list (unquote (+ 1 2)) 4)) | |
2479 | ==> (list 3 4) | |
2480 | '(quasiquote (list (unquote (+ 1 2)) 4)) | |
2481 | ==> `(list ,(+ 1 2) 4) | |
2482 | @emph{}i.e., (quasiquote (list (unquote (+ 1 2)) 4)) | |
2483 | } | |
2484 | @end format | |
2485 | ||
2486 | ||
2487 | Unpredictable behavior can result if any of the symbols | |
2488 | @code{quasiquote}, @code{unquote}, or @code{unquote-splicing} appear in | |
2489 | @vindex @w{unquote-splicing} | |
2490 | @vindex @w{unquote} | |
2491 | @vindex @w{quasiquote} | |
2492 | positions within a @r{<qq template>} otherwise than as described above. | |
2493 | ||
2494 | @end deffn | |
2495 | ||
2496 | @node Macros, , Derived expression types, Expressions | |
2497 | @section Macros | |
2498 | ||
2499 | @menu | |
2500 | * Binding constructs for syntactic keywords:: | |
2501 | * Pattern language:: | |
2502 | @end menu | |
2503 | ||
2504 | ||
2505 | ||
2506 | Scheme programs can define and use new derived expression types, | |
2507 | called @emph{macros}. | |
2508 | @cindex @w{macro} | |
2509 | Program-defined expression types have the syntax | |
2510 | ||
2511 | @example | |
2512 | ||
2513 | (@r{<keyword>} @r{<datum>} ...) | |
2514 | ||
2515 | @end example | |
2516 | ||
2517 | where @r{<keyword>} is an identifier that uniquely determines the | |
2518 | expression type. This identifier is called the @emph{syntactic | |
2519 | keyword}, or simply @emph{keyword}, of the macro. The | |
2520 | @cindex @w{macro keyword} | |
2521 | @cindex @w{keyword} | |
2522 | @cindex @w{syntactic keyword} | |
2523 | number of the @r{<datum>}s, and their syntax, depends on the | |
2524 | expression type. | |
2525 | ||
2526 | Each instance of a macro is called a @emph{use} | |
2527 | @cindex @w{macro use} | |
2528 | of the macro. | |
2529 | The set of rules that specifies | |
2530 | how a use of a macro is transcribed into a more primitive expression | |
2531 | is called the @emph{transformer} | |
2532 | @cindex @w{macro transformer} | |
2533 | of the macro. | |
2534 | ||
2535 | The macro definition facility consists of two parts: | |
2536 | ||
2537 | ||
2538 | ||
2539 | @itemize @bullet | |
2540 | ||
2541 | @item | |
2542 | A set of expressions used to establish that certain identifiers | |
2543 | are macro keywords, associate them with macro transformers, and control | |
2544 | the scope within which a macro is defined, and | |
2545 | ||
2546 | @item | |
2547 | a pattern language for specifying macro transformers. | |
2548 | ||
2549 | @end itemize | |
2550 | ||
2551 | ||
2552 | The syntactic keyword of a macro may shadow variable bindings, and local | |
2553 | variable bindings may shadow keyword bindings. All macros | |
2554 | @cindex @w{keyword} | |
2555 | defined using the pattern language are ``hygienic'' and ``referentially | |
2556 | transparent'' and thus preserve Scheme's lexical scoping [Kohlbecker86], [ | |
2557 | hygienic], [Bawden88], [macrosthatwork], [syntacticabstraction]: | |
2558 | ||
2559 | @cindex @w{hygienic} | |
2560 | ||
2561 | @cindex @w{referentially transparent} | |
2562 | ||
2563 | ||
2564 | ||
2565 | ||
2566 | @itemize @bullet | |
2567 | ||
2568 | ||
2569 | @item | |
2570 | If a macro transformer inserts a binding for an identifier | |
2571 | (variable or keyword), the identifier will in effect be renamed | |
2572 | throughout its scope to avoid conflicts with other identifiers. | |
2573 | Note that a @code{define} at top level may or may not introduce a binding; | |
2574 | see section @ref{Definitions}. | |
2575 | ||
2576 | @item | |
2577 | If a macro transformer inserts a free reference to an | |
2578 | identifier, the reference refers to the binding that was visible | |
2579 | where the transformer was specified, regardless of any local | |
2580 | bindings that may surround the use of the macro. | |
2581 | ||
2582 | ||
2583 | @end itemize | |
2584 | ||
2585 | @vindex @w{define} | |
2586 | ||
2587 | @c The low-level facility permits non-hygienic macros to be written, | |
2588 | @c and may be used to implement the high-level pattern language. | |
2589 | ||
2590 | @c The fourth section describes some features that would make the | |
2591 | @c low-level macro facility easier to use directly. | |
2592 | ||
2593 | @node Binding constructs for syntactic keywords, Pattern language, Macros, Macros | |
2594 | @subsection Binding constructs for syntactic keywords | |
2595 | ||
2596 | ||
2597 | ||
7fb9c4af | 2598 | @samp{Let-syntax} and @samp{letrec-syntax} are |
a0e07ba4 NJ |
2599 | analogous to @samp{let} and @samp{letrec}, but they bind |
2600 | syntactic keywords to macro transformers instead of binding variables | |
2601 | to locations that contain values. Syntactic keywords may also be | |
2602 | bound at top level; see section @ref{Syntax definitions}. | |
2603 | ||
2604 | ||
2605 | @deffn {syntax} let-syntax @r{<bindings>} @r{<body>} | |
2606 | ||
2607 | @emph{Syntax:} | |
2608 | @r{<Bindings>} should have the form | |
2609 | ||
2610 | @format | |
2611 | @t{((@r{<keyword>} @r{<transformer spec>}) @dots{},) | |
2612 | } | |
2613 | @end format | |
2614 | ||
2615 | Each @r{<keyword>} is an identifier, | |
2616 | each @r{<transformer spec>} is an instance of @samp{syntax-rules}, and | |
2617 | @r{<body>} should be a sequence of one or more expressions. It is an error | |
2618 | for a @r{<keyword>} to appear more than once in the list of keywords | |
2619 | being bound. | |
2620 | ||
2621 | @emph{Semantics:} | |
2622 | The @r{<body>} is expanded in the syntactic environment | |
2623 | obtained by extending the syntactic environment of the | |
2624 | @samp{let-syntax} expression with macros whose keywords are | |
2625 | the @r{<keyword>}s, bound to the specified transformers. | |
2626 | Each binding of a @r{<keyword>} has @r{<body>} as its region. | |
2627 | ||
2628 | ||
2629 | @format | |
2630 | @t{(let-syntax ((when (syntax-rules () | |
2631 | ((when test stmt1 stmt2 ...) | |
2632 | (if test | |
2633 | (begin stmt1 | |
2634 | stmt2 ...)))))) | |
2635 | (let ((if #t)) | |
2636 | (when if (set! if 'now)) | |
2637 | if)) ==> now | |
2638 | ||
2639 | (let ((x 'outer)) | |
2640 | (let-syntax ((m (syntax-rules () ((m) x)))) | |
2641 | (let ((x 'inner)) | |
2642 | (m)))) ==> outer | |
2643 | } | |
2644 | @end format | |
2645 | ||
2646 | ||
2647 | @end deffn | |
2648 | ||
2649 | ||
2650 | @deffn {syntax} letrec-syntax @r{<bindings>} @r{<body>} | |
2651 | ||
2652 | @emph{Syntax:} | |
2653 | Same as for @samp{let-syntax}. | |
2654 | ||
2655 | @emph{Semantics:} | |
2656 | The @r{<body>} is expanded in the syntactic environment obtained by | |
2657 | extending the syntactic environment of the @samp{letrec-syntax} | |
2658 | expression with macros whose keywords are the | |
2659 | @r{<keyword>}s, bound to the specified transformers. | |
2660 | Each binding of a @r{<keyword>} has the @r{<bindings>} | |
2661 | as well as the @r{<body>} within its region, | |
2662 | so the transformers can | |
2663 | transcribe expressions into uses of the macros | |
2664 | introduced by the @samp{letrec-syntax} expression. | |
2665 | ||
2666 | ||
2667 | @format | |
2668 | @t{(letrec-syntax | |
2669 | ((my-or (syntax-rules () | |
2670 | ((my-or) #f) | |
2671 | ((my-or e) e) | |
2672 | ((my-or e1 e2 ...) | |
2673 | (let ((temp e1)) | |
2674 | (if temp | |
2675 | temp | |
2676 | (my-or e2 ...))))))) | |
2677 | (let ((x #f) | |
2678 | (y 7) | |
2679 | (temp 8) | |
2680 | (let odd?) | |
2681 | (if even?)) | |
2682 | (my-or x | |
2683 | (let temp) | |
2684 | (if y) | |
2685 | y))) ==> 7 | |
2686 | } | |
2687 | @end format | |
2688 | ||
2689 | ||
2690 | @end deffn | |
2691 | ||
2692 | @node Pattern language, , Binding constructs for syntactic keywords, Macros | |
2693 | @subsection Pattern language | |
2694 | ||
2695 | ||
2696 | ||
2697 | A @r{<transformer spec>} has the following form: | |
2698 | ||
2699 | ||
2700 | @deffn {} syntax-rules @r{<literals>} @r{<syntax rule>} @dots{}, | |
2701 | ||
2702 | @emph{Syntax:} | |
2703 | @r{<Literals>} is a list of identifiers and each @r{<syntax rule>} | |
2704 | should be of the form | |
2705 | ||
2706 | @format | |
2707 | @t{(@r{<pattern>} @r{<template>}) | |
2708 | } | |
2709 | @end format | |
2710 | ||
2711 | The @r{<pattern>} in a @r{<syntax rule>} is a list @r{<pattern>} | |
2712 | that begins with the keyword for the macro. | |
2713 | ||
2714 | A @r{<pattern>} is either an identifier, a constant, or one of the | |
2715 | following | |
2716 | ||
2717 | @format | |
2718 | @t{(@r{<pattern>} @dots{}) | |
2719 | (@r{<pattern>} @r{<pattern>} @dots{} . @r{<pattern>}) | |
2720 | (@r{<pattern>} @dots{} @r{<pattern>} @r{<ellipsis>}) | |
2721 | #(@r{<pattern>} @dots{}) | |
2722 | #(@r{<pattern>} @dots{} @r{<pattern>} @r{<ellipsis>}) | |
2723 | } | |
2724 | @end format | |
2725 | ||
2726 | and a template is either an identifier, a constant, or one of the following | |
2727 | ||
2728 | @format | |
2729 | @t{(@r{<element>} @dots{}) | |
2730 | (@r{<element>} @r{<element>} @dots{} . @r{<template>}) | |
2731 | #(@r{<element>} @dots{}) | |
2732 | } | |
2733 | @end format | |
2734 | ||
2735 | where an @r{<element>} is a @r{<template>} optionally | |
2736 | followed by an @r{<ellipsis>} and | |
2737 | an @r{<ellipsis>} is the identifier ``@samp{...}'' (which cannot be used as | |
2738 | an identifier in either a template or a pattern). | |
2739 | @vindex ... | |
2740 | ||
2741 | @emph{Semantics:} An instance of @samp{syntax-rules} produces a new macro | |
2742 | transformer by specifying a sequence of hygienic rewrite rules. A use | |
2743 | of a macro whose keyword is associated with a transformer specified by | |
2744 | @samp{syntax-rules} is matched against the patterns contained in the | |
2745 | @r{<syntax rule>}s, beginning with the leftmost @r{<syntax rule>}. | |
2746 | When a match is found, the macro use is transcribed hygienically | |
2747 | according to the template. | |
2748 | ||
2749 | An identifier that appears in the pattern of a @r{<syntax rule>} is | |
2750 | a @emph{pattern variable}, unless it is the keyword that begins the pattern, | |
2751 | is listed in @r{<literals>}, or is the identifier ``@samp{...}''. | |
2752 | Pattern variables match arbitrary input elements and | |
2753 | are used to refer to elements of the input in the template. It is an | |
2754 | error for the same pattern variable to appear more than once in a | |
2755 | @r{<pattern>}. | |
2756 | ||
2757 | The keyword at the beginning of the pattern in a | |
2758 | @r{<syntax rule>} is not involved in the matching and | |
2759 | is not considered a pattern variable or literal identifier. | |
2760 | ||
2761 | ||
2762 | @quotation | |
2763 | @emph{Rationale:} | |
2764 | The scope of the keyword is determined by the expression or syntax | |
2765 | definition that binds it to the associated macro transformer. | |
2766 | If the keyword were a pattern variable or literal | |
2767 | identifier, then | |
2768 | the template that follows the pattern would be within its scope | |
2769 | regardless of whether the keyword were bound by @samp{let-syntax} | |
2770 | or by @samp{letrec-syntax}. | |
2771 | @end quotation | |
2772 | ||
2773 | ||
2774 | Identifiers that appear in @r{<literals>} are interpreted as literal | |
2775 | identifiers to be matched against corresponding subforms of the input. | |
2776 | A subform | |
2777 | in the input matches a literal identifier if and only if it is an | |
2778 | identifier | |
2779 | and either both its occurrence in the macro expression and its | |
2780 | occurrence in the macro definition have the same lexical binding, or | |
2781 | the two identifiers are equal and both have no lexical binding. | |
2782 | ||
2783 | @c [Bill Rozas suggested the term "noise word" for these literal | |
2784 | @c identifiers, but in their most interesting uses, such as a setf | |
2785 | @c macro, they aren't noise words at all. -- Will] | |
2786 | ||
2787 | A subpattern followed by @samp{...} can match zero or more elements of the | |
2788 | input. It is an error for @samp{...} to appear in @r{<literals>}. | |
2789 | Within a pattern the identifier @samp{...} must follow the last element of | |
2790 | a nonempty sequence of subpatterns. | |
2791 | ||
2792 | More formally, an input form F matches a pattern P if and only if: | |
2793 | ||
2794 | ||
2795 | ||
2796 | @itemize @bullet | |
2797 | ||
2798 | @item | |
2799 | P is a non-literal identifier; or | |
2800 | ||
2801 | @item | |
2802 | P is a literal identifier and F is an identifier with the same | |
2803 | binding; or | |
2804 | ||
2805 | @item | |
2806 | P is a list @samp{(P_1 @dots{} P_n)} and F is a | |
2807 | list of n | |
2808 | forms that match P_1 through P_n, respectively; or | |
2809 | ||
2810 | @item | |
2811 | P is an improper list | |
2812 | @samp{(P_1 P_2 @dots{} P_n . P_n+1)} | |
2813 | and F is a list or | |
2814 | improper list of n or more forms that match P_1 through P_n, | |
2815 | respectively, and whose nth ``cdr'' matches P_n+1; or | |
2816 | ||
2817 | @item | |
2818 | P is of the form | |
2819 | @samp{(P_1 @dots{} P_n P_n+1 <ellipsis>)} | |
2820 | where <ellipsis> is the identifier @samp{...} | |
2821 | and F is | |
2822 | a proper list of at least n forms, the first n of which match | |
2823 | P_1 through P_n, respectively, and each remaining element of F | |
2824 | matches P_n+1; or | |
2825 | ||
2826 | @item | |
2827 | P is a vector of the form @samp{#(P_1 @dots{} P_n)} | |
2828 | and F is a vector | |
2829 | of n forms that match P_1 through P_n; or | |
2830 | ||
2831 | @item | |
2832 | P is of the form | |
2833 | @samp{#(P_1 @dots{} P_n P_n+1 <ellipsis>)} | |
2834 | where <ellipsis> is the identifier @samp{...} | |
2835 | and F is a vector of n | |
2836 | or more forms the first n of which match | |
2837 | P_1 through P_n, respectively, and each remaining element of F | |
2838 | matches P_n+1; or | |
2839 | ||
2840 | @item | |
2841 | P is a datum and F is equal to P in the sense of | |
2842 | the @samp{equal?} procedure. | |
2843 | ||
2844 | @end itemize | |
2845 | ||
2846 | ||
2847 | It is an error to use a macro keyword, within the scope of its | |
2848 | binding, in an expression that does not match any of the patterns. | |
2849 | ||
2850 | When a macro use is transcribed according to the template of the | |
2851 | matching @r{<syntax rule>}, pattern variables that occur in the | |
2852 | template are replaced by the subforms they match in the input. | |
2853 | Pattern variables that occur in subpatterns followed by one or more | |
2854 | instances of the identifier | |
2855 | @samp{...} are allowed only in subtemplates that are | |
2856 | followed by as many instances of @samp{...}. | |
2857 | They are replaced in the | |
2858 | output by all of the subforms they match in the input, distributed as | |
2859 | indicated. It is an error if the output cannot be built up as | |
2860 | specified. | |
2861 | ||
2862 | @c %% This description of output construction is very vague. It should | |
2863 | @c %% probably be formalized, but that is not easy... | |
2864 | ||
2865 | Identifiers that appear in the template but are not pattern variables | |
2866 | or the identifier | |
2867 | @samp{...} are inserted into the output as literal identifiers. If a | |
2868 | literal identifier is inserted as a free identifier then it refers to the | |
2869 | binding of that identifier within whose scope the instance of | |
2870 | @samp{syntax-rules} appears. | |
2871 | If a literal identifier is inserted as a bound identifier then it is | |
2872 | in effect renamed to prevent inadvertent captures of free identifiers. | |
2873 | ||
2874 | As an example, if @code{let} and @code{cond} are defined as in | |
2875 | @vindex @w{cond} | |
2876 | @vindex @w{let} | |
2877 | section @ref{Derived expression type} then they are hygienic (as required) and | |
2878 | the following is not an error. | |
2879 | ||
2880 | ||
2881 | @format | |
2882 | @t{(let ((=> #f)) | |
2883 | (cond (#t => 'ok))) ==> ok | |
2884 | } | |
2885 | @end format | |
2886 | ||
2887 | ||
2888 | The macro transformer for @samp{cond} recognizes @samp{=>} | |
2889 | as a local variable, and hence an expression, and not as the | |
2890 | top-level identifier @samp{=>}, which the macro transformer treats | |
2891 | as a syntactic keyword. Thus the example expands into | |
2892 | ||
2893 | ||
2894 | @format | |
2895 | @t{(let ((=> #f)) | |
2896 | (if #t (begin => 'ok))) | |
2897 | } | |
2898 | @end format | |
2899 | ||
2900 | ||
2901 | instead of | |
2902 | ||
2903 | ||
2904 | @format | |
2905 | @t{(let ((=> #f)) | |
2906 | (let ((temp #t)) | |
2907 | (if temp ('ok temp)))) | |
2908 | } | |
2909 | @end format | |
2910 | ||
2911 | ||
2912 | which would result in an invalid procedure call. | |
2913 | ||
2914 | @end deffn | |
2915 | ||
2916 | ||
2917 | @page | |
2918 | ||
2919 | @c @include{prog} | |
2920 | @node Program structure, Standard procedures, Expressions, top | |
2921 | @chapter Program structure | |
2922 | ||
2923 | @menu | |
2924 | * Programs:: | |
2925 | * Definitions:: | |
2926 | * Syntax definitions:: | |
2927 | @end menu | |
2928 | ||
2929 | ||
2930 | ||
2931 | @node Programs, Definitions, Program structure, Program structure | |
2932 | @section Programs | |
2933 | ||
2934 | ||
2935 | A Scheme program consists of a sequence of expressions, definitions, | |
2936 | and syntax definitions. | |
2937 | Expressions are described in chapter @ref{Expressions}; | |
2938 | definitions and syntax definitions are the subject of the rest of the | |
2939 | present chapter. | |
2940 | ||
2941 | Programs are typically stored in files or entered interactively to a | |
2942 | running Scheme system, although other paradigms are possible; | |
2943 | questions of user interface lie outside the scope of this report. | |
2944 | (Indeed, Scheme would still be useful as a notation for expressing | |
2945 | computational methods even in the absence of a mechanical | |
2946 | implementation.) | |
2947 | ||
2948 | Definitions and syntax definitions occurring at the top level of a program | |
2949 | can be interpreted | |
2950 | declaratively. | |
2951 | They cause bindings to be created in the top level | |
2952 | environment or modify the value of existing top-level bindings. | |
2953 | Expressions occurring at the top level of a program are | |
2954 | interpreted imperatively; they are executed in order when the program is | |
2955 | invoked or loaded, and typically perform some kind of initialization. | |
2956 | ||
2957 | At the top level of a program @t{(begin @r{<form1>} @dots{},)} is | |
2958 | equivalent to the sequence of expressions, definitions, and syntax definitions | |
2959 | that form the body of the @code{begin}. | |
2960 | @vindex @w{begin} | |
2961 | ||
2962 | @ignore todo | |
2963 | Cromarty, etc.: disclaimer about top level? | |
2964 | @end ignore | |
2965 | ||
2966 | ||
2967 | @node Definitions, Syntax definitions, Programs, Program structure | |
2968 | @section Definitions | |
2969 | ||
2970 | @menu | |
2971 | * Top level definitions:: | |
2972 | * Internal definitions:: | |
2973 | @end menu | |
2974 | ||
2975 | ||
2976 | ||
2977 | Definitions are valid in some, but not all, contexts where expressions | |
2978 | are allowed. They are valid only at the top level of a @r{<program>} | |
2979 | and at the beginning of a @r{<body>}. | |
2980 | ||
2981 | @cindex @w{definition} | |
2982 | ||
2983 | A definition should have one of the following forms: | |
2984 | @cindex @w{define} | |
2985 | ||
2986 | ||
2987 | ||
2988 | @itemize @bullet | |
2989 | ||
2990 | ||
2991 | @item @t{(define @r{<variable>} @r{<expression>})} | |
2992 | ||
2993 | @item @t{(define (@r{<variable>} @r{<formals>}) @r{<body>})} | |
2994 | ||
2995 | @r{<Formals>} should be either a | |
2996 | sequence of zero or more variables, or a sequence of one or more | |
2997 | variables followed by a space-delimited period and another variable (as | |
2998 | in a lambda expression). This form is equivalent to | |
2999 | ||
3000 | @example | |
3001 | ||
3002 | (define @r{<variable>} | |
3003 | (lambda (@r{<formals>}) @r{<body>}))@r{.} | |
3004 | ||
3005 | @end example | |
3006 | ||
3007 | ||
3008 | @item @t{(define (@r{<variable>} .@: @r{<formal>}) @r{<body>})} | |
3009 | ||
3010 | @r{<Formal>} should be a single | |
3011 | variable. This form is equivalent to | |
3012 | ||
3013 | @example | |
3014 | ||
3015 | (define @r{<variable>} | |
3016 | (lambda @r{<formal>} @r{<body>}))@r{.} | |
3017 | ||
3018 | @end example | |
3019 | ||
3020 | ||
3021 | ||
3022 | @end itemize | |
3023 | ||
3024 | ||
3025 | @node Top level definitions, Internal definitions, Definitions, Definitions | |
3026 | @subsection Top level definitions | |
3027 | ||
3028 | ||
3029 | At the top level of a program, a definition | |
3030 | ||
3031 | @example | |
3032 | ||
3033 | (define @r{<variable>} @r{<expression>}) | |
3034 | ||
3035 | @end example | |
3036 | ||
3037 | has essentially the same effect as the assignment expression | |
3038 | ||
3039 | @example | |
3040 | ||
3041 | (set! @r{<variable>} @r{<expression>}) | |
3042 | ||
3043 | @end example | |
3044 | ||
3045 | if @r{<variable>} is bound. If @r{<variable>} is not bound, | |
3046 | however, then the definition will bind @r{<variable>} to a new | |
3047 | location before performing the assignment, whereas it would be an error | |
3048 | to perform a @samp{set!} on an unbound variable. | |
3049 | @cindex @w{unbound} | |
3050 | ||
3051 | ||
3052 | @example | |
3053 | ||
3054 | (define add3 | |
3055 | (lambda (x) (+ x 3))) | |
3056 | (add3 3) ==> 6 | |
3057 | (define first car) | |
3058 | (first '(1 2)) ==> 1 | |
3059 | ||
3060 | @end example | |
3061 | ||
3062 | ||
3063 | Some implementations of Scheme use an initial environment in | |
3064 | which all possible variables are bound to locations, most of | |
3065 | which contain undefined values. Top level definitions in | |
3066 | such an implementation are truly equivalent to assignments. | |
3067 | ||
3068 | @ignore todo | |
3069 | Rozas: equal time for opposition semantics? | |
3070 | @end ignore | |
3071 | ||
3072 | ||
3073 | ||
3074 | @node Internal definitions, , Top level definitions, Definitions | |
3075 | @subsection Internal definitions | |
3076 | ||
3077 | ||
3078 | ||
3079 | Definitions may occur at the | |
3080 | beginning of a @r{<body>} (that is, the body of a @code{lambda}, | |
3081 | @vindex @w{lambda} | |
3082 | @code{let}, @code{let*}, @code{letrec}, @code{let-syntax}, or @code{letrec-syntax} | |
3083 | @vindex @w{letrec-syntax} | |
3084 | @vindex @w{let-syntax} | |
3085 | @vindex @w{letrec} | |
3086 | @vindex @w{let*} | |
3087 | @vindex @w{let} | |
3088 | expression or that of a definition of an appropriate form). | |
3089 | Such definitions are known as @emph{internal definitions} as opposed to the top level definitions described above. | |
3090 | @cindex @w{internal definition} | |
3091 | The variable defined by an internal definition is local to the | |
3092 | @r{<body>}. That is, @r{<variable>} is bound rather than assigned, | |
3093 | and the region of the binding is the entire @r{<body>}. For example, | |
3094 | ||
3095 | ||
3096 | @example | |
3097 | ||
3098 | (let ((x 5)) | |
3099 | (define foo (lambda (y) (bar x y))) | |
3100 | (define bar (lambda (a b) (+ (* a b) a))) | |
3101 | (foo (+ x 3))) ==> 45 | |
3102 | ||
3103 | @end example | |
3104 | ||
3105 | ||
3106 | A @r{<body>} containing internal definitions can always be converted | |
3107 | into a completely equivalent @samp{letrec} expression. For example, the | |
3108 | @samp{let} expression in the above example is equivalent to | |
3109 | ||
3110 | ||
3111 | @example | |
3112 | ||
3113 | (let ((x 5)) | |
3114 | (letrec ((foo (lambda (y) (bar x y))) | |
3115 | (bar (lambda (a b) (+ (* a b) a)))) | |
3116 | (foo (+ x 3)))) | |
3117 | ||
3118 | @end example | |
3119 | ||
3120 | ||
3121 | Just as for the equivalent @samp{letrec} expression, it must be | |
3122 | possible to evaluate each @r{<expression>} of every internal | |
3123 | definition in a @r{<body>} without assigning or referring to | |
3124 | the value of any @r{<variable>} being defined. | |
3125 | ||
3126 | Wherever an internal definition may occur | |
3127 | @t{(begin @r{<definition1>} @dots{},)} | |
3128 | is equivalent to the sequence of definitions | |
3129 | that form the body of the @code{begin}. | |
3130 | @vindex @w{begin} | |
3131 | ||
3132 | @node Syntax definitions, , Definitions, Program structure | |
3133 | @section Syntax definitions | |
3134 | ||
3135 | ||
3136 | Syntax definitions are valid only at the top level of a @r{<program>}. | |
3137 | ||
3138 | @cindex @w{syntax definition} | |
3139 | They have the following form: | |
3140 | @cindex @w{define-syntax} | |
3141 | ||
3142 | @t{(define-syntax @r{<keyword>} @r{<transformer spec>})} | |
3143 | ||
3144 | @r{<Keyword>} is an identifier, and | |
3145 | the @r{<transformer spec>} should be an instance of @code{syntax-rules}. | |
3146 | @vindex @w{syntax-rules} | |
3147 | The top-level syntactic environment is extended by binding the | |
3148 | @r{<keyword>} to the specified transformer. | |
3149 | ||
3150 | There is no @samp{define-syntax} analogue of internal definitions. | |
3151 | ||
3152 | @c [Rationale flushed because it may or may not be true and isn't the | |
3153 | @c real rationale anyway. -RK] | |
3154 | @c \begin{rationale} | |
3155 | @c As discussed below, the syntax and scope rules for syntax definitions | |
3156 | @c can give rise to syntactic ambiguities when syntactic keywords are | |
3157 | @c shadowed. | |
3158 | @c Further ambiguities would arise if {\cf define-syntax} | |
3159 | @c were permitted at the beginning of a \meta{body}, with scope | |
3160 | @c rules analogous to those for internal definitions. | |
3161 | @c \end{rationale} | |
3162 | ||
3163 | @c It is an error for a program to contain more than one top-level | |
3164 | @c \meta{definition} or \meta{syntax definition} of any identifier. | |
3165 | ||
3166 | @c [I flushed this because it isn't an error for a program to | |
3167 | @c contain more than one top-level definition of an identifier, | |
3168 | @c and I didn't want to introduce any gratuitous incompatibilities | |
3169 | @c with the existing Scheme language. -- Will] | |
3170 | ||
3171 | Although macros may expand into definitions and syntax definitions in | |
3172 | any context that permits them, it is an error for a definition or syntax | |
3173 | definition to shadow a syntactic keyword whose meaning is needed to | |
3174 | determine whether some form in the group of forms that contains the | |
3175 | shadowing definition is in fact a definition, or, for internal definitions, | |
3176 | is needed to determine the boundary between the group and the expressions | |
3177 | that follow the group. For example, the following are errors: | |
3178 | ||
3179 | ||
3180 | @example | |
3181 | ||
3182 | (define define 3) | |
3183 | ||
3184 | (begin (define begin list)) | |
3185 | ||
3186 | (let-syntax | |
3187 | ((foo (syntax-rules () | |
3188 | ((foo (proc args ...) body ...) | |
3189 | (define proc | |
3190 | (lambda (args ...) | |
3191 | body ...)))))) | |
3192 | (let ((x 3)) | |
3193 | (foo (plus x y) (+ x y)) | |
3194 | (define foo x) | |
3195 | (plus foo x))) | |
3196 | ||
3197 | @end example | |
3198 | ||
3199 | ||
3200 | ||
3201 | ||
3202 | @c @include{procs} | |
3203 | ||
3204 | @c Initial environment | |
3205 | ||
3206 | @c \vfill\eject | |
3207 | @node Standard procedures, Formal syntax and semantics, Program structure, top | |
3208 | @chapter Standard procedures | |
3209 | ||
3210 | @menu | |
3211 | * Equivalence predicates:: | |
3212 | * Numbers:: | |
3213 | * Other data types:: | |
3214 | * Control features:: | |
3215 | * Eval:: | |
3216 | * Input and output:: | |
3217 | @end menu | |
3218 | ||
3219 | ||
3220 | ||
3221 | ||
3222 | ||
3223 | @cindex @w{initial environment} | |
3224 | ||
3225 | @cindex @w{top level environment} | |
3226 | ||
3227 | @cindex @w{library procedure} | |
3228 | ||
3229 | This chapter describes Scheme's built-in procedures. The initial (or | |
3230 | ``top level'') Scheme environment starts out with a number of variables | |
3231 | bound to locations containing useful values, most of which are primitive | |
3232 | procedures that manipulate data. For example, the variable @samp{abs} is | |
3233 | bound to (a location initially containing) a procedure of one argument | |
3234 | that computes the absolute value of a number, and the variable @samp{+} | |
3235 | is bound to a procedure that computes sums. Built-in procedures that | |
3236 | can easily be written in terms of other built-in procedures are identified as | |
3237 | ``library procedures''. | |
3238 | ||
3239 | A program may use a top-level definition to bind any variable. It may | |
3240 | subsequently alter any such binding by an assignment (see @pxref{Assignments}). | |
3241 | These operations do not modify the behavior of Scheme's built-in | |
3242 | procedures. Altering any top-level binding that has not been introduced by a | |
3243 | definition has an unspecified effect on the behavior of the built-in procedures. | |
3244 | ||
3245 | @node Equivalence predicates, Numbers, Standard procedures, Standard procedures | |
3246 | @section Equivalence predicates | |
3247 | ||
3248 | ||
3249 | ||
3250 | A @dfn{predicate} is a procedure that always returns a boolean | |
3251 | @cindex @w{predicate} | |
3252 | value (@t{#t} or @t{#f}). An @dfn{equivalence predicate} is | |
3253 | @cindex @w{equivalence predicate} | |
3254 | the computational analogue of a mathematical equivalence relation (it is | |
3255 | symmetric, reflexive, and transitive). Of the equivalence predicates | |
3256 | described in this section, @samp{eq?} is the finest or most | |
7fb9c4af | 3257 | discriminating, and @samp{equal?} is the coarsest. @samp{Eqv?} is |
a0e07ba4 NJ |
3258 | slightly less discriminating than @samp{eq?}. |
3259 | @ignore todo | |
3260 | Pitman doesn't like | |
3261 | this paragraph. Lift the discussion from the Maclisp manual. Explain | |
3262 | why there's more than one predicate. | |
3263 | @end ignore | |
3264 | ||
3265 | ||
3266 | ||
3267 | ||
3268 | @deffn {procedure} eqv? obj1 obj2 | |
3269 | ||
3270 | The @samp{eqv?} procedure defines a useful equivalence relation on objects. | |
3271 | Briefly, it returns @t{#t} if @var{obj1} and @var{obj2} should | |
3272 | normally be regarded as the same object. This relation is left slightly | |
3273 | open to interpretation, but the following partial specification of | |
3274 | @samp{eqv?} holds for all implementations of Scheme. | |
3275 | ||
3276 | The @samp{eqv?} procedure returns @t{#t} if: | |
3277 | ||
3278 | ||
3279 | ||
3280 | @itemize @bullet | |
3281 | ||
3282 | @item | |
3283 | @var{obj1} and @var{obj2} are both @t{#t} or both @t{#f}. | |
3284 | ||
3285 | @item | |
3286 | @var{obj1} and @var{obj2} are both symbols and | |
3287 | ||
3288 | ||
3289 | @format | |
3290 | @t{(string=? (symbol->string obj1) | |
3291 | (symbol->string obj2)) | |
3292 | ==> #t | |
3293 | } | |
3294 | @end format | |
3295 | ||
3296 | ||
3297 | ||
3298 | @quotation | |
3299 | @emph{Note:} | |
3300 | This assumes that neither @var{obj1} nor @var{obj2} is an ``uninterned | |
3301 | symbol'' as alluded to in section @ref{Symbols}. This report does | |
3302 | not presume to specify the behavior of @samp{eqv?} on implementation-dependent | |
3303 | extensions. | |
3304 | @end quotation | |
3305 | ||
3306 | ||
3307 | @item | |
3308 | @var{obj1} and @var{obj2} are both numbers, are numerically | |
3309 | equal (see @samp{=}, section @pxref{Numbers}), and are either both | |
3310 | exact or both inexact. | |
3311 | ||
3312 | @item | |
3313 | @var{obj1} and @var{obj2} are both characters and are the same | |
3314 | character according to the @samp{char=?} procedure | |
3315 | (section @pxref{Characters}). | |
3316 | ||
3317 | @item | |
3318 | both @var{obj1} and @var{obj2} are the empty list. | |
3319 | ||
3320 | @item | |
3321 | @var{obj1} and @var{obj2} are pairs, vectors, or strings that denote the | |
3322 | same locations in the store (section @pxref{Storage model}). | |
3323 | ||
3324 | @item | |
3325 | @var{obj1} and @var{obj2} are procedures whose location tags are | |
3326 | equal (section @pxref{Procedures}). | |
3327 | ||
3328 | @end itemize | |
3329 | ||
3330 | @cindex @w{inexact} | |
3331 | @cindex @w{exact} | |
3332 | ||
3333 | The @samp{eqv?} procedure returns @t{#f} if: | |
3334 | ||
3335 | ||
3336 | ||
3337 | @itemize @bullet | |
3338 | ||
3339 | @item | |
3340 | @var{obj1} and @var{obj2} are of different types | |
3341 | (section @pxref{Disjointness of types}). | |
3342 | ||
3343 | @item | |
3344 | one of @var{obj1} and @var{obj2} is @t{#t} but the other is | |
3345 | @t{#f}. | |
3346 | ||
3347 | @item | |
3348 | @var{obj1} and @var{obj2} are symbols but | |
3349 | ||
3350 | ||
3351 | @format | |
3352 | @t{(string=? (symbol->string @var{obj1}) | |
3353 | (symbol->string @var{obj2})) | |
3354 | ==> #f | |
3355 | } | |
3356 | @end format | |
3357 | ||
3358 | ||
3359 | @item | |
3360 | one of @var{obj1} and @var{obj2} is an exact number but the other | |
3361 | is an inexact number. | |
3362 | ||
3363 | @item | |
3364 | @var{obj1} and @var{obj2} are numbers for which the @samp{=} | |
3365 | procedure returns @t{#f}. | |
3366 | ||
3367 | @item | |
3368 | @var{obj1} and @var{obj2} are characters for which the @samp{char=?} | |
3369 | procedure returns @t{#f}. | |
3370 | ||
3371 | @item | |
3372 | one of @var{obj1} and @var{obj2} is the empty list but the other | |
3373 | is not. | |
3374 | ||
3375 | @item | |
3376 | @var{obj1} and @var{obj2} are pairs, vectors, or strings that denote | |
3377 | distinct locations. | |
3378 | ||
3379 | @item | |
3380 | @var{obj1} and @var{obj2} are procedures that would behave differently | |
3381 | (return different value(s) or have different side effects) for some arguments. | |
3382 | ||
3383 | ||
3384 | @end itemize | |
3385 | ||
3386 | ||
3387 | ||
3388 | @format | |
3389 | @t{(eqv? 'a 'a) ==> #t | |
3390 | (eqv? 'a 'b) ==> #f | |
3391 | (eqv? 2 2) ==> #t | |
3392 | (eqv? '() '()) ==> #t | |
3393 | (eqv? 100000000 100000000) ==> #t | |
3394 | (eqv? (cons 1 2) (cons 1 2)) ==> #f | |
3395 | (eqv? (lambda () 1) | |
3396 | (lambda () 2)) ==> #f | |
3397 | (eqv? #f 'nil) ==> #f | |
3398 | (let ((p (lambda (x) x))) | |
3399 | (eqv? p p)) ==> #t | |
3400 | } | |
3401 | @end format | |
3402 | ||
3403 | ||
3404 | The following examples illustrate cases in which the above rules do | |
3405 | not fully specify the behavior of @samp{eqv?}. All that can be said | |
3406 | about such cases is that the value returned by @samp{eqv?} must be a | |
3407 | boolean. | |
3408 | ||
3409 | ||
3410 | @format | |
3411 | @t{(eqv? "" "") ==> @emph{unspecified} | |
3412 | (eqv? '#() '#()) ==> @emph{unspecified} | |
3413 | (eqv? (lambda (x) x) | |
3414 | (lambda (x) x)) ==> @emph{unspecified} | |
3415 | (eqv? (lambda (x) x) | |
3416 | (lambda (y) y)) ==> @emph{unspecified} | |
3417 | } | |
3418 | @end format | |
3419 | ||
3420 | ||
3421 | The next set of examples shows the use of @samp{eqv?} with procedures | |
7fb9c4af | 3422 | that have local state. @samp{Gen-counter} must return a distinct |
a0e07ba4 | 3423 | procedure every time, since each procedure has its own internal counter. |
7fb9c4af | 3424 | @samp{Gen-loser}, however, returns equivalent procedures each time, since |
a0e07ba4 NJ |
3425 | the local state does not affect the value or side effects of the |
3426 | procedures. | |
3427 | ||
3428 | ||
3429 | @format | |
3430 | @t{(define gen-counter | |
3431 | (lambda () | |
3432 | (let ((n 0)) | |
3433 | (lambda () (set! n (+ n 1)) n)))) | |
3434 | (let ((g (gen-counter))) | |
3435 | (eqv? g g)) ==> #t | |
3436 | (eqv? (gen-counter) (gen-counter)) | |
3437 | ==> #f | |
3438 | (define gen-loser | |
3439 | (lambda () | |
3440 | (let ((n 0)) | |
3441 | (lambda () (set! n (+ n 1)) 27)))) | |
3442 | (let ((g (gen-loser))) | |
3443 | (eqv? g g)) ==> #t | |
3444 | (eqv? (gen-loser) (gen-loser)) | |
3445 | ==> @emph{unspecified} | |
3446 | ||
3447 | (letrec ((f (lambda () (if (eqv? f g) 'both 'f))) | |
3448 | (g (lambda () (if (eqv? f g) 'both 'g)))) | |
3449 | (eqv? f g)) | |
3450 | ==> @emph{unspecified} | |
3451 | ||
3452 | (letrec ((f (lambda () (if (eqv? f g) 'f 'both))) | |
3453 | (g (lambda () (if (eqv? f g) 'g 'both)))) | |
3454 | (eqv? f g)) | |
3455 | ==> #f | |
3456 | } | |
3457 | @end format | |
3458 | ||
3459 | ||
3460 | @c Objects of distinct types must never be regarded as the same object, | |
3461 | @c except that \schfalse{} and the empty list\index{empty list} are permitted to | |
3462 | @c be identical. | |
3463 | ||
3464 | @c \begin{scheme} | |
3465 | @c (eqv? '() \schfalse) \ev \unspecified% | |
3466 | @c \end{scheme} | |
3467 | ||
3468 | Since it is an error to modify constant objects (those returned by | |
3469 | literal expressions), implementations are permitted, though not | |
3470 | required, to share structure between constants where appropriate. Thus | |
3471 | the value of @samp{eqv?} on constants is sometimes | |
3472 | implementation-dependent. | |
3473 | ||
3474 | ||
3475 | @format | |
3476 | @t{(eqv? '(a) '(a)) ==> @emph{unspecified} | |
3477 | (eqv? "a" "a") ==> @emph{unspecified} | |
3478 | (eqv? '(b) (cdr '(a b))) ==> @emph{unspecified} | |
3479 | (let ((x '(a))) | |
3480 | (eqv? x x)) ==> #t | |
3481 | } | |
3482 | @end format | |
3483 | ||
3484 | ||
3485 | ||
3486 | @quotation | |
3487 | @emph{Rationale:} | |
3488 | The above definition of @samp{eqv?} allows implementations latitude in | |
3489 | their treatment of procedures and literals: implementations are free | |
3490 | either to detect or to fail to detect that two procedures or two literals | |
3491 | are equivalent to each other, and can decide whether or not to | |
3492 | merge representations of equivalent objects by using the same pointer or | |
3493 | bit pattern to represent both. | |
3494 | @end quotation | |
3495 | ||
3496 | ||
3497 | @end deffn | |
3498 | ||
3499 | ||
3500 | ||
3501 | @deffn {procedure} eq? obj1 obj2 | |
3502 | ||
7fb9c4af | 3503 | @samp{Eq?} is similar to @samp{eqv?} except that in some cases it is |
a0e07ba4 NJ |
3504 | capable of discerning distinctions finer than those detectable by |
3505 | @samp{eqv?}. | |
3506 | ||
7fb9c4af | 3507 | @samp{Eq?} and @samp{eqv?} are guaranteed to have the same |
a0e07ba4 NJ |
3508 | behavior on symbols, booleans, the empty list, pairs, procedures, |
3509 | and non-empty | |
7fb9c4af | 3510 | strings and vectors. @samp{Eq?}'s behavior on numbers and characters is |
a0e07ba4 NJ |
3511 | implementation-dependent, but it will always return either true or |
3512 | false, and will return true only when @samp{eqv?} would also return | |
7fb9c4af | 3513 | true. @samp{Eq?} may also behave differently from @samp{eqv?} on empty |
a0e07ba4 NJ |
3514 | vectors and empty strings. |
3515 | ||
3516 | ||
3517 | @format | |
3518 | @t{(eq? 'a 'a) ==> #t | |
3519 | (eq? '(a) '(a)) ==> @emph{unspecified} | |
3520 | (eq? (list 'a) (list 'a)) ==> #f | |
3521 | (eq? "a" "a") ==> @emph{unspecified} | |
3522 | (eq? "" "") ==> @emph{unspecified} | |
3523 | (eq? '() '()) ==> #t | |
3524 | (eq? 2 2) ==> @emph{unspecified} | |
3525 | (eq? #\A #\A) ==> @emph{unspecified} | |
3526 | (eq? car car) ==> #t | |
3527 | (let ((n (+ 2 3))) | |
3528 | (eq? n n)) ==> @emph{unspecified} | |
3529 | (let ((x '(a))) | |
3530 | (eq? x x)) ==> #t | |
3531 | (let ((x '#())) | |
3532 | (eq? x x)) ==> #t | |
3533 | (let ((p (lambda (x) x))) | |
3534 | (eq? p p)) ==> #t | |
3535 | } | |
3536 | @end format | |
3537 | ||
3538 | ||
3539 | @ignore todo | |
3540 | Needs to be explained better above. How can this be made to be | |
3541 | not confusing? A table maybe? | |
3542 | @end ignore | |
3543 | ||
3544 | ||
3545 | ||
3546 | @quotation | |
3547 | @emph{Rationale:} It will usually be possible to implement @samp{eq?} much | |
3548 | more efficiently than @samp{eqv?}, for example, as a simple pointer | |
3549 | comparison instead of as some more complicated operation. One reason is | |
3550 | that it may not be possible to compute @samp{eqv?} of two numbers in | |
3551 | constant time, whereas @samp{eq?} implemented as pointer comparison will | |
7fb9c4af | 3552 | always finish in constant time. @samp{Eq?} may be used like @samp{eqv?} |
a0e07ba4 NJ |
3553 | in applications using procedures to implement objects with state since |
3554 | it obeys the same constraints as @samp{eqv?}. | |
3555 | @end quotation | |
3556 | ||
3557 | ||
3558 | @end deffn | |
3559 | ||
3560 | ||
3561 | ||
3562 | @deffn {library procedure} equal? obj1 obj2 | |
3563 | ||
7fb9c4af | 3564 | @samp{Equal?} recursively compares the contents of pairs, vectors, and |
a0e07ba4 NJ |
3565 | strings, applying @samp{eqv?} on other objects such as numbers and symbols. |
3566 | A rule of thumb is that objects are generally @samp{equal?} if they print | |
7fb9c4af | 3567 | the same. @samp{Equal?} may fail to terminate if its arguments are |
a0e07ba4 NJ |
3568 | circular data structures. |
3569 | ||
3570 | ||
3571 | @format | |
3572 | @t{(equal? 'a 'a) ==> #t | |
3573 | (equal? '(a) '(a)) ==> #t | |
3574 | (equal? '(a (b) c) | |
3575 | '(a (b) c)) ==> #t | |
3576 | (equal? "abc" "abc") ==> #t | |
3577 | (equal? 2 2) ==> #t | |
3578 | (equal? (make-vector 5 'a) | |
3579 | (make-vector 5 'a)) ==> #t | |
3580 | (equal? (lambda (x) x) | |
3581 | (lambda (y) y)) ==> @emph{unspecified} | |
3582 | } | |
3583 | @end format | |
3584 | ||
3585 | ||
3586 | @end deffn | |
3587 | ||
3588 | ||
3589 | @node Numbers, Other data types, Equivalence predicates, Standard procedures | |
3590 | @section Numbers | |
3591 | ||
3592 | @menu | |
3593 | * Numerical types:: | |
3594 | * Exactness:: | |
3595 | * Implementation restrictions:: | |
3596 | * Syntax of numerical constants:: | |
3597 | * Numerical operations:: | |
3598 | * Numerical input and output:: | |
3599 | @end menu | |
3600 | ||
3601 | ||
3602 | ||
3603 | @cindex @w{number} | |
3604 | ||
3605 | @c %R4%% The excessive use of the code font in this section was | |
3606 | @c confusing, somewhat obnoxious, and inconsistent with the rest | |
3607 | @c of the report and with parts of the section itself. I added | |
3608 | @c a \tupe no-op, and changed most old uses of \type to \tupe, | |
3609 | @c to make it easier to change the fonts back if people object | |
3610 | @c to the change. | |
3611 | ||
3612 | @c \newcommand{\type}[1]{{\it#1}} | |
3613 | @c \newcommand{\tupe}[1]{{#1}} | |
3614 | ||
3615 | Numerical computation has traditionally been neglected by the Lisp | |
3616 | community. Until Common Lisp there was no carefully thought out | |
3617 | strategy for organizing numerical computation, and with the exception of | |
3618 | the MacLisp system [Pitman83] little effort was made to | |
3619 | execute numerical code efficiently. This report recognizes the excellent work | |
3620 | of the Common Lisp committee and accepts many of their recommendations. | |
3621 | In some ways this report simplifies and generalizes their proposals in a manner | |
3622 | consistent with the purposes of Scheme. | |
3623 | ||
3624 | It is important to distinguish between the mathematical numbers, the | |
3625 | Scheme numbers that attempt to model them, the machine representations | |
3626 | used to implement the Scheme numbers, and notations used to write numbers. | |
3627 | This report uses the types @i{number}, @i{complex}, @i{real}, | |
3628 | @i{rational}, and @i{integer} to refer to both mathematical numbers | |
3629 | and Scheme numbers. Machine representations such as fixed point and | |
3630 | floating point are referred to by names such as @i{fixnum} and | |
3631 | @i{flonum}. | |
3632 | ||
3633 | @c %R4%% I did some reorganizing here to move the discussion of mathematical | |
3634 | @c numbers before the discussion of the Scheme numbers, hoping that this | |
3635 | @c would help to motivate the discussion of representation independence. | |
3636 | ||
3637 | @node Numerical types, Exactness, Numbers, Numbers | |
3638 | @subsection Numerical types | |
3639 | ||
3640 | ||
3641 | ||
3642 | @cindex @w{numerical types} | |
3643 | ||
3644 | @c %R4%% A Scheme system provides data of type \type{number}, which is the most | |
3645 | @c general numerical type supported by that system. | |
3646 | @c \type{Number} is | |
3647 | @c likely to be a complicated union type implemented in terms of | |
3648 | @c \type{fixnum}s, \type{bignum}s, \type{flonum}s, and so forth, but this | |
3649 | @c should not be apparent to a naive user. What the user should see is | |
3650 | @c that the usual operations on numbers produce the mathematically | |
3651 | @c expected results, within the limits of the implementation. | |
3652 | ||
3653 | @c %R4%% I rewrote the following paragraph to make the various levels of | |
3654 | @c the tower into subsets of each other, instead of relating them by | |
3655 | @c injections. I think the injections tended to put people in the frame | |
3656 | @c of mind of thinking about coercions between non-overlapping numeric | |
3657 | @c types in mainstream programming languages. | |
3658 | ||
3659 | Mathematically, numbers may be arranged into a tower of subtypes | |
3660 | @c %R4%% with injections relating adjacent levels of the tower: | |
3661 | in which each level is a subset of the level above it: | |
3662 | ||
3663 | @format | |
3664 | @r{number} | |
3665 | @r{complex} | |
3666 | @r{real} | |
3667 | @r{rational} | |
3668 | @r{integer} | |
3669 | @end format | |
3670 | ||
3671 | ||
3672 | For example, 3 is an integer. Therefore 3 is also a rational, | |
3673 | a real, and a complex. The same is true of the Scheme numbers | |
3674 | that model 3. For Scheme numbers, these types are defined by the | |
3675 | predicates @code{number?}, @code{complex?}, @code{real?}, @code{rational?}, | |
3676 | @vindex @w{rational?} | |
3677 | @vindex @w{real?} | |
3678 | @vindex @w{complex?} | |
3679 | @vindex @w{number?} | |
3680 | and @code{integer?}. | |
3681 | @vindex @w{integer?} | |
3682 | ||
3683 | There is no simple relationship between a number's type and its | |
3684 | representation inside a computer. Although most implementations of | |
3685 | Scheme will offer at least two different representations of 3, these | |
3686 | different representations denote the same integer. | |
3687 | ||
3688 | @c %R4%% I moved "Implementations of Scheme are not required to implement | |
3689 | @c the whole tower..." to the subsection on implementation restrictions. | |
3690 | ||
3691 | Scheme's numerical operations treat numbers as abstract data, as | |
3692 | independent of their representation as possible. Although an implementation | |
3693 | of Scheme may use fixnum, flonum, and perhaps other representations for | |
3694 | numbers, this should not be apparent to a casual programmer writing | |
3695 | simple programs. | |
3696 | ||
3697 | It is necessary, however, to distinguish between numbers that are | |
3698 | represented exactly and those that may not be. For example, indexes | |
3699 | into data structures must be known exactly, as must some polynomial | |
3700 | coefficients in a symbolic algebra system. On the other hand, the | |
3701 | results of measurements are inherently inexact, and irrational numbers | |
3702 | may be approximated by rational and therefore inexact approximations. | |
3703 | In order to catch uses of inexact numbers where exact numbers are | |
3704 | required, Scheme explicitly distinguishes exact from inexact numbers. | |
3705 | This distinction is orthogonal to the dimension of type. | |
3706 | ||
3707 | @node Exactness, Implementation restrictions, Numerical types, Numbers | |
3708 | @subsection Exactness | |
3709 | ||
3710 | ||
3711 | @c %R4%% I tried to direct the following paragraph away from philosophizing | |
3712 | @c about the exactness of mathematical numbers, and toward philosophizing | |
3713 | @c about the exactness of Scheme numbers. | |
3714 | ||
3715 | ||
3716 | @cindex @w{exactness} | |
3717 | Scheme numbers are either @i{exact} or @i{inexact}. A number is | |
3718 | @r{exact} if it was written as an exact constant or was derived from | |
3719 | @r{exact} numbers using only @r{exact} operations. A number is | |
3720 | @r{inexact} if it was written as an inexact constant, | |
3721 | @c %R4%% models a quantity (e.g., a measurement) known only approximately, | |
3722 | if it was | |
3723 | derived using @r{inexact} ingredients, or if it was derived using | |
3724 | @r{inexact} operations. Thus @r{inexact}ness is a contagious | |
3725 | property of a number. | |
3726 | @c %R4%% The rest of this paragraph (from R3RS) has been dropped. | |
3727 | ||
3728 | If two implementations produce @r{exact} results for a | |
3729 | computation that did not involve @r{inexact} intermediate results, | |
3730 | the two ultimate results will be mathematically equivalent. This is | |
3731 | generally not true of computations involving @r{inexact} numbers | |
3732 | since approximate methods such as floating point arithmetic may be used, | |
3733 | but it is the duty of each implementation to make the result as close as | |
3734 | practical to the mathematically ideal result. | |
3735 | ||
3736 | Rational operations such as @samp{+} should always produce | |
3737 | @r{exact} results when given @r{exact} arguments. | |
3738 | @c %R4%%If an implementation is | |
3739 | @c unable to represent an \tupe{exact} result (for example, if it does not | |
3740 | @c support infinite precision integers and rationals) | |
3741 | If the operation is unable to produce an @r{exact} result, | |
3742 | then it may either report the violation of an implementation restriction | |
3743 | or it may silently coerce its | |
3744 | result to an @r{inexact} value. | |
3745 | @c %R4%%Such a coercion may cause an error later. | |
3746 | See section @ref{Implementation restrictions}. | |
3747 | ||
3748 | With the exception of @code{inexact->exact}, the operations described in | |
3749 | @vindex @w{inexact->exact} | |
3750 | this section must generally return inexact results when given any inexact | |
3751 | arguments. An operation may, however, return an @r{exact} result if it can | |
3752 | prove that the value of the result is unaffected by the inexactness of its | |
3753 | arguments. For example, multiplication of any number by an @r{exact} zero | |
3754 | may produce an @r{exact} zero result, even if the other argument is | |
3755 | @r{inexact}. | |
3756 | ||
3757 | @node Implementation restrictions, Syntax of numerical constants, Exactness, Numbers | |
3758 | @subsection Implementation restrictions | |
3759 | ||
3760 | ||
3761 | ||
3762 | @cindex @w{implementation restriction} | |
3763 | ||
3764 | Implementations of Scheme are not required to implement the whole | |
3765 | tower of subtypes given in section @ref{Numerical types}, | |
3766 | but they must implement a coherent subset consistent with both the | |
3767 | purposes of the implementation and the spirit of the Scheme language. | |
3768 | For example, an implementation in which all numbers are @r{real} | |
3769 | may still be quite useful. | |
3770 | ||
3771 | Implementations may also support only a limited range of numbers of | |
3772 | any type, subject to the requirements of this section. The supported | |
3773 | range for @r{exact} numbers of any type may be different from the | |
3774 | supported range for @r{inexact} numbers of that type. For example, | |
3775 | an implementation that uses flonums to represent all its | |
3776 | @r{inexact} @r{real} numbers may | |
3777 | support a practically unbounded range of @r{exact} @r{integer}s | |
3778 | and @r{rational}s | |
3779 | while limiting the range of @r{inexact} @r{real}s (and therefore | |
3780 | the range of @r{inexact} @r{integer}s and @r{rational}s) | |
3781 | to the dynamic range of the flonum format. | |
3782 | Furthermore | |
3783 | the gaps between the representable @r{inexact} @r{integer}s and | |
3784 | @r{rational}s are | |
3785 | likely to be very large in such an implementation as the limits of this | |
3786 | range are approached. | |
3787 | ||
3788 | An implementation of Scheme must support exact integers | |
3789 | throughout the range of numbers that may be used for indexes of | |
3790 | lists, vectors, and strings or that may result from computing the length of a | |
3791 | list, vector, or string. The @code{length}, @code{vector-length}, | |
3792 | @vindex @w{vector-length} | |
3793 | @vindex @w{length} | |
3794 | and @code{string-length} procedures must return an exact | |
3795 | @vindex @w{string-length} | |
3796 | integer, and it is an error to use anything but an exact integer as an | |
3797 | index. Furthermore any integer constant within the index range, if | |
3798 | expressed by an exact integer syntax, will indeed be read as an exact | |
3799 | integer, regardless of any implementation restrictions that may apply | |
3800 | outside this range. Finally, the procedures listed below will always | |
3801 | return an exact integer result provided all their arguments are exact integers | |
3802 | and the mathematically expected result is representable as an exact integer | |
3803 | within the implementation: | |
3804 | ||
3805 | ||
3806 | @example | |
3807 | ||
3808 | + - * | |
3809 | quotient remainder modulo | |
3810 | max min abs | |
3811 | numerator denominator gcd | |
3812 | lcm floor ceiling | |
3813 | truncate round rationalize | |
3814 | expt | |
3815 | ||
3816 | @end example | |
3817 | ||
3818 | ||
3819 | Implementations are encouraged, but not required, to support | |
3820 | @r{exact} @r{integer}s and @r{exact} @r{rational}s of | |
3821 | practically unlimited size and precision, and to implement the | |
3822 | above procedures and the @samp{/} procedure in | |
3823 | such a way that they always return @r{exact} results when given @r{exact} | |
3824 | arguments. If one of these procedures is unable to deliver an @r{exact} | |
3825 | result when given @r{exact} arguments, then it may either report a | |
3826 | violation of an | |
3827 | implementation restriction or it may silently coerce its result to an | |
3828 | @r{inexact} number. Such a coercion may cause an error later. | |
3829 | ||
3830 | @c %R4%% I moved this stuff here. | |
3831 | @c It seems to me that the only thing that this requires is that | |
3832 | @c implementations that support inexact numbers have to have both | |
3833 | @c exact and inexact representations for the integers 0 through 15. | |
3834 | @c If that's what it's saying, I'd rather say it that way. | |
3835 | @c On the other hand, letting the limit be as small as 15 sounds a | |
3836 | @c tad silly, though I think I understand how that number was arrived at. | |
3837 | @c (Or is 35 the number?) | |
3838 | ||
3839 | @c Implementations are encouraged, but not required, to support \tupe{inexact} | |
3840 | @c numbers. For any implementation that supports \tupe{inexact} numbers, | |
3841 | @c there is a subset of the integers for which there are both \tupe{exact} and | |
3842 | @c \tupe{inexact} representations. This subset must include all non-negative | |
3843 | @c integers up to some limit specified by the implementation. This limit | |
3844 | @c must be 16 or greater. The | |
3845 | @c \ide{exact\coerce{}inexact} and \ide{inexact\coerce{}exact} | |
3846 | @c procedures implement the natural one-to-one correspondence between | |
3847 | @c the \tupe{inexact} and \tupe{exact} integers within this range. | |
3848 | ||
3849 | An implementation may use floating point and other approximate | |
3850 | representation strategies for @r{inexact} numbers. | |
3851 | @c %R4%% The following sentence seemed a bit condescending as well as | |
3852 | @c awkward. It didn't seem to be very enforceable, so I flushed it. | |
3853 | ||
3854 | @c This is not to | |
3855 | @c say that implementors need not use the best known algorithms for | |
3856 | @c \tupe{inexact} computations---only that approximate methods of high | |
3857 | @c quality are allowed. | |
3858 | ||
3859 | This report recommends, but does not require, that the IEEE 32-bit | |
3860 | and 64-bit floating point standards be followed by implementations that use | |
3861 | flonum representations, and that implementations using | |
3862 | other representations should match or exceed the precision achievable | |
3863 | using these floating point standards [IEEE]. | |
3864 | ||
3865 | In particular, implementations that use flonum representations | |
3866 | must follow these rules: A @r{flonum} result | |
3867 | must be represented with at least as much precision as is used to express any of | |
3868 | the inexact arguments to that operation. It is desirable (but not required) for | |
3869 | potentially inexact operations such as @samp{sqrt}, when applied to @r{exact} | |
3870 | arguments, to produce @r{exact} answers whenever possible (for example the | |
3871 | square root of an @r{exact} 4 ought to be an @r{exact} 2). | |
3872 | If, however, an | |
3873 | @r{exact} number is operated upon so as to produce an @r{inexact} result | |
3874 | (as by @samp{sqrt}), and if the result is represented as a @r{flonum}, then | |
3875 | the most precise @r{flonum} format available must be used; but if the result | |
3876 | is represented in some other way then the representation must have at least as | |
3877 | much precision as the most precise @r{flonum} format available. | |
3878 | ||
3879 | Although Scheme allows a variety of written | |
3880 | @c %R4%% representations of | |
3881 | notations for | |
3882 | numbers, any particular implementation may support only some of them. | |
3883 | @c %R4%% | |
3884 | For example, an implementation in which all numbers are @r{real} | |
3885 | need not support the rectangular and polar notations for complex | |
3886 | numbers. If an implementation encounters an @r{exact} numerical constant that | |
3887 | it cannot represent as an @r{exact} number, then it may either report a | |
3888 | violation of an implementation restriction or it may silently represent the | |
3889 | constant by an @r{inexact} number. | |
3890 | ||
3891 | ||
3892 | @node Syntax of numerical constants, Numerical operations, Implementation restrictions, Numbers | |
3893 | @subsection Syntax of numerical constants | |
3894 | ||
3895 | ||
3896 | ||
3897 | @c @@@@LOSE@@@@ | |
3898 | ||
3899 | @c %R4%% I removed the following paragraph in an attempt to tighten up | |
3900 | @c this subsection. Except for its first sentence, which I moved to | |
3901 | @c the subsection on implementation restrictions, I think its content | |
3902 | @c is implied by the rest of the section. | |
3903 | ||
3904 | @c Although Scheme allows a variety of written representations of numbers, | |
3905 | @c any particular implementation may support only some of them. | |
3906 | @c These syntaxes are intended to be purely notational; any kind of number | |
3907 | @c may be written in any form that the user deems convenient. Of course, | |
3908 | @c writing 1/7 as a limited-precision decimal fraction will not express the | |
3909 | @c number exactly, but this approximate form of expression may be just what | |
3910 | @c the user wants to see. | |
3911 | ||
3912 | The syntax of the written representations for numbers is described formally in | |
3913 | section @ref{Lexical structure}. Note that case is not significant in numerical | |
3914 | constants. | |
3915 | ||
3916 | @c %R4%% See section~\ref{numberformats} for many examples. | |
3917 | ||
3918 | A number may be written in binary, octal, decimal, or | |
3919 | hexadecimal by the use of a radix prefix. The radix prefixes are @samp{#b} (binary), @samp{#o} (octal), @samp{#d} (decimal), and @samp{#x} (hexadecimal). With | |
3920 | @vindex #x | |
3921 | @vindex #d | |
3922 | @vindex #o | |
3923 | @vindex #b | |
3924 | no radix prefix, a number is assumed to be expressed in decimal. | |
3925 | ||
3926 | A | |
3927 | @c %R4%% | |
3928 | @c simple | |
3929 | numerical constant may be specified to be either @r{exact} or | |
3930 | @r{inexact} by a prefix. The prefixes are @samp{#e} | |
3931 | @vindex #e | |
3932 | for @r{exact}, and @samp{#i} for @r{inexact}. An exactness | |
3933 | @vindex #i | |
3934 | prefix may appear before or after any radix prefix that is used. If | |
3935 | the written representation of a number has no exactness prefix, the | |
3936 | constant may be either @r{inexact} or @r{exact}. It is | |
3937 | @r{inexact} if it contains a decimal point, an | |
3938 | exponent, or a ``#'' character in the place of a digit, | |
3939 | otherwise it is @r{exact}. | |
3940 | @c %R4%% With our new syntax, the following sentence is redundant: | |
3941 | ||
3942 | @c The written representation of a | |
3943 | @c compound number, such as a ratio or a complex, is exact if and only if | |
3944 | @c all of its constituents are exact. | |
3945 | ||
3946 | In systems with @r{inexact} numbers | |
3947 | of varying precisions it may be useful to specify | |
3948 | the precision of a constant. For this purpose, numerical constants | |
3949 | may be written with an exponent marker that indicates the | |
3950 | desired precision of the @r{inexact} | |
3951 | representation. The letters @samp{s}, @samp{f}, | |
3952 | @samp{d}, and @samp{l} specify the use of @var{short}, @var{single}, | |
3953 | @var{double}, and @var{long} precision, respectively. (When fewer | |
3954 | than four internal | |
3955 | @c %R4%%\tupe{flonum} | |
3956 | @r{inexact} | |
3957 | representations exist, the four size | |
3958 | specifications are mapped onto those available. For example, an | |
3959 | implementation with two internal representations may map short and | |
3960 | single together and long and double together.) In addition, the | |
3961 | exponent marker @samp{e} specifies the default precision for the | |
3962 | implementation. The default precision has at least as much precision | |
3963 | as @var{double}, but | |
3964 | implementations may wish to allow this default to be set by the user. | |
3965 | ||
3966 | ||
3967 | @example | |
3968 | ||
3969 | 3.14159265358979F0 | |
3970 | @r{Round to single ---} 3.141593 | |
3971 | 0.6L0 | |
3972 | @r{Extend to long ---} .600000000000000 | |
3973 | ||
3974 | @end example | |
3975 | ||
3976 | ||
3977 | ||
3978 | @node Numerical operations, Numerical input and output, Syntax of numerical constants, Numbers | |
3979 | @subsection Numerical operations | |
3980 | ||
3981 | ||
3982 | The reader is referred to section @ref{Entry format} for a summary | |
3983 | of the naming conventions used to specify restrictions on the types of | |
3984 | arguments to numerical routines. | |
3985 | @c %R4%% The following sentence has already been said twice, and the | |
3986 | @c term "exactness-preserving" is no longer defined by the Report. | |
3987 | ||
3988 | @c Remember that | |
3989 | @c an exactness-preserving operation may coerce its result to inexact if the | |
3990 | @c implementation is unable to represent it exactly. | |
3991 | The examples used in this section assume that any numerical constant written | |
3992 | using an @r{exact} notation is indeed represented as an @r{exact} | |
3993 | number. Some examples also assume that certain numerical constants written | |
3994 | using an @r{inexact} notation can be represented without loss of | |
3995 | accuracy; the @r{inexact} constants were chosen so that this is | |
3996 | likely to be true in implementations that use flonums to represent | |
3997 | inexact numbers. | |
3998 | ||
3999 | @ignore todo | |
4000 | Scheme provides the usual set of operations for manipulating | |
4001 | numbers, etc. | |
4002 | @end ignore | |
4003 | ||
4004 | ||
4005 | ||
4006 | @deffn {procedure} number? obj | |
4007 | @deffnx {procedure} complex? obj | |
4008 | @deffnx {procedure} real? obj | |
4009 | @deffnx {procedure} rational? obj | |
4010 | @deffnx {procedure} integer? obj | |
4011 | ||
4012 | These numerical type predicates can be applied to any kind of | |
4013 | argument, including non-numbers. They return @t{#t} if the object is | |
4014 | of the named type, and otherwise they return @t{#f}. | |
4015 | In general, if a type predicate is true of a number then all higher | |
4016 | type predicates are also true of that number. Consequently, if a type | |
4017 | predicate is false of a number, then all lower type predicates are | |
4018 | also false of that number. | |
4019 | @c %R4%% The new section on implementation restrictions subsumes: | |
4020 | @c Not every system | |
4021 | @c supports all of these types; for example, it is entirely possible to have a | |
4022 | @c Scheme system that has only \tupe{integer}s. Nonetheless every implementation | |
4023 | @c of Scheme must have all of these predicates. | |
4024 | ||
4025 | If @var{z} is an inexact complex number, then @samp{(real? @var{z})} is true if | |
4026 | and only if @samp{(zero? (imag-part @var{z}))} is true. If @var{x} is an inexact | |
4027 | real number, then @samp{(integer? @var{x})} is true if and only if | |
4028 | @samp{(= @var{x} (round @var{x}))}. | |
4029 | ||
4030 | ||
4031 | @format | |
4032 | @t{(complex? 3+4i) ==> #t | |
4033 | (complex? 3) ==> #t | |
4034 | (real? 3) ==> #t | |
4035 | (real? -2.5+0.0i) ==> #t | |
4036 | (real? #e1e10) ==> #t | |
4037 | (rational? 6/10) ==> #t | |
4038 | (rational? 6/3) ==> #t | |
4039 | (integer? 3+0i) ==> #t | |
4040 | (integer? 3.0) ==> #t | |
4041 | (integer? 8/4) ==> #t | |
4042 | } | |
4043 | @end format | |
4044 | ||
4045 | ||
4046 | ||
4047 | @quotation | |
4048 | @emph{Note:} | |
4049 | The behavior of these type predicates on @r{inexact} numbers | |
4050 | is unreliable, since any inaccuracy may affect the result. | |
4051 | @end quotation | |
4052 | ||
4053 | ||
4054 | ||
4055 | @quotation | |
4056 | @emph{Note:} | |
4057 | In many implementations the @code{rational?} procedure will be the same | |
4058 | @vindex @w{rational?} | |
4059 | as @code{real?}, and the @code{complex?} procedure will be the same as | |
4060 | @vindex @w{complex?} | |
4061 | @vindex @w{real?} | |
4062 | @code{number?}, but unusual implementations may be able to represent | |
4063 | @vindex @w{number?} | |
4064 | some irrational numbers exactly or may extend the number system to | |
4065 | support some kind of non-complex numbers. | |
4066 | @end quotation | |
4067 | ||
4068 | ||
4069 | @end deffn | |
4070 | ||
4071 | ||
4072 | @deffn {procedure} exact? @var{z} | |
4073 | @deffnx {procedure} inexact? @var{z} | |
4074 | ||
4075 | These numerical predicates provide tests for the exactness of a | |
4076 | quantity. For any Scheme number, precisely one of these predicates | |
4077 | is true. | |
4078 | ||
4079 | @end deffn | |
4080 | ||
4081 | ||
4082 | ||
4083 | @deffn {procedure} = z1 z2 z3 @dots{}, | |
4084 | @deffnx {procedure} < x1 x2 x3 @dots{}, | |
4085 | @deffnx {procedure} > x1 x2 x3 @dots{}, | |
4086 | @deffnx {procedure} <= x1 x2 x3 @dots{}, | |
4087 | @deffnx {procedure} >= x1 x2 x3 @dots{}, | |
4088 | ||
4089 | @c - Some implementations allow these procedures to take many arguments, to | |
4090 | @c - facilitate range checks. | |
4091 | These procedures return @t{#t} if their arguments are (respectively): | |
4092 | equal, monotonically increasing, monotonically decreasing, | |
4093 | monotonically nondecreasing, or monotonically nonincreasing. | |
4094 | ||
4095 | These predicates are required to be transitive. | |
4096 | ||
4097 | ||
4098 | @quotation | |
4099 | @emph{Note:} | |
4100 | The traditional implementations of these predicates in Lisp-like | |
4101 | languages are not transitive. | |
4102 | @end quotation | |
4103 | ||
4104 | ||
4105 | ||
4106 | @quotation | |
4107 | @emph{Note:} | |
4108 | While it is not an error to compare @r{inexact} numbers using these | |
4109 | predicates, the results may be unreliable because a small inaccuracy | |
4110 | may affect the result; this is especially true of @code{=} and @code{zero?}. | |
4111 | @vindex @w{zero?} | |
4112 | @vindex @w{=} | |
4113 | When in doubt, consult a numerical analyst. | |
4114 | @end quotation | |
4115 | ||
4116 | ||
4117 | @end deffn | |
4118 | ||
4119 | ||
4120 | @deffn {library procedure} zero? @var{z} | |
4121 | @deffnx {library procedure} positive? @var{x} | |
4122 | @deffnx {library procedure} negative? @var{x} | |
4123 | @deffnx {library procedure} odd? @var{n} | |
4124 | @deffnx {library procedure} even? @var{n} | |
4125 | ||
4126 | These numerical predicates test a number for a particular property, | |
4127 | returning @t{#t} or @t{#f}. See note above. | |
4128 | ||
4129 | @end deffn | |
4130 | ||
4131 | ||
4132 | @deffn {library procedure} max x1 x2 @dots{}, | |
4133 | @deffnx {library procedure} min x1 x2 @dots{}, | |
4134 | ||
4135 | These procedures return the maximum or minimum of their arguments. | |
4136 | ||
4137 | ||
4138 | @format | |
4139 | @t{(max 3 4) ==> 4 ; exact | |
4140 | (max 3.9 4) ==> 4.0 ; inexact | |
4141 | } | |
4142 | @end format | |
4143 | ||
4144 | ||
4145 | ||
4146 | @quotation | |
4147 | @emph{Note:} | |
4148 | If any argument is inexact, then the result will also be inexact (unless | |
4149 | the procedure can prove that the inaccuracy is not large enough to affect the | |
4150 | result, which is possible only in unusual implementations). If @samp{min} or | |
4151 | @samp{max} is used to compare numbers of mixed exactness, and the numerical | |
4152 | value of the result cannot be represented as an inexact number without loss of | |
4153 | accuracy, then the procedure may report a violation of an implementation | |
4154 | restriction. | |
4155 | @end quotation | |
4156 | ||
4157 | ||
4158 | @end deffn | |
4159 | ||
4160 | ||
4161 | ||
4162 | @deffn {procedure} + z1 @dots{}, | |
4163 | @deffnx {procedure} * z1 @dots{}, | |
4164 | ||
4165 | These procedures return the sum or product of their arguments. | |
4166 | @c - These procedures are exactness preserving. | |
4167 | ||
4168 | ||
4169 | @format | |
4170 | @t{(+ 3 4) ==> 7 | |
4171 | (+ 3) ==> 3 | |
4172 | (+) ==> 0 | |
4173 | (* 4) ==> 4 | |
4174 | (*) ==> 1 | |
4175 | } | |
4176 | @end format | |
4177 | ||
4178 | ||
4179 | @end deffn | |
4180 | ||
4181 | ||
4182 | ||
4183 | @deffn {procedure} - z1 z2 | |
4184 | @deffnx {procedure} - @var{z} | |
4185 | @deffnx {optional procedure} - z1 z2 @dots{}, | |
4186 | @deffnx {procedure} / z1 z2 | |
4187 | @deffnx {procedure} / @var{z} | |
4188 | @deffnx {optional procedure} / z1 z2 @dots{}, | |
4189 | ||
4190 | With two or more arguments, these procedures return the difference or | |
4191 | quotient of their arguments, associating to the left. With one argument, | |
4192 | however, they return the additive or multiplicative inverse of their argument. | |
4193 | @c - These procedures are exactness preserving, except that division may | |
4194 | @c - coerce its result to inexact in implementations that do not support | |
4195 | @c - \tupe{ratnum}s. | |
4196 | ||
4197 | ||
4198 | @format | |
4199 | @t{(- 3 4) ==> -1 | |
4200 | (- 3 4 5) ==> -6 | |
4201 | (- 3) ==> -3 | |
4202 | (/ 3 4 5) ==> 3/20 | |
4203 | (/ 3) ==> 1/3 | |
4204 | } | |
4205 | @end format | |
4206 | ||
4207 | ||
4208 | @end deffn | |
4209 | ||
4210 | ||
4211 | ||
4212 | @deffn {library procedure} abs x | |
4213 | ||
7fb9c4af | 4214 | @samp{Abs} returns the absolute value of its argument. |
a0e07ba4 NJ |
4215 | @c - {\cf Abs} is exactness preserving when its argument is real. |
4216 | ||
4217 | @format | |
4218 | @t{(abs -7) ==> 7 | |
4219 | } | |
4220 | @end format | |
4221 | ||
4222 | @end deffn | |
4223 | ||
4224 | ||
4225 | ||
4226 | @deffn {procedure} quotient n1 n2 | |
4227 | @deffnx {procedure} remainder n1 n2 | |
4228 | @deffnx {procedure} modulo n1 n2 | |
4229 | ||
4230 | These procedures implement number-theoretic (integer) | |
4231 | division. @var{n2} should be non-zero. All three procedures | |
4232 | return integers. If @var{n1}/@var{n2} is an integer: | |
4233 | ||
4234 | @format | |
4235 | @t{ (quotient @var{n1} @var{n2}) ==> @var{n1}/@var{n2} | |
4236 | (remainder @var{n1} @var{n2}) ==> 0 | |
4237 | (modulo @var{n1} @var{n2}) ==> 0 | |
4238 | } | |
4239 | @end format | |
4240 | ||
4241 | If @var{n1}/@var{n2} is not an integer: | |
4242 | ||
4243 | @format | |
4244 | @t{ (quotient @var{n1} @var{n2}) ==> @var{n_q} | |
4245 | (remainder @var{n1} @var{n2}) ==> @var{n_r} | |
4246 | (modulo @var{n1} @var{n2}) ==> @var{n_m} | |
4247 | } | |
4248 | @end format | |
4249 | ||
4250 | where @var{n_q} is @var{n1}/@var{n2} rounded towards zero, | |
4251 | 0 < |@var{n_r}| < |@var{n2}|, 0 < |@var{n_m}| < |@var{n2}|, | |
4252 | @var{n_r} and @var{n_m} differ from @var{n1} by a multiple of @var{n2}, | |
4253 | @var{n_r} has the same sign as @var{n1}, and | |
4254 | @var{n_m} has the same sign as @var{n2}. | |
4255 | ||
4256 | From this we can conclude that for integers @var{n1} and @var{n2} with | |
4257 | @var{n2} not equal to 0, | |
4258 | ||
4259 | @format | |
4260 | @t{ (= @var{n1} (+ (* @var{n2} (quotient @var{n1} @var{n2})) | |
4261 | (remainder @var{n1} @var{n2}))) | |
4262 | ==> #t | |
4263 | } | |
4264 | @end format | |
4265 | ||
4266 | provided all numbers involved in that computation are exact. | |
4267 | ||
4268 | ||
4269 | @format | |
4270 | @t{(modulo 13 4) ==> 1 | |
4271 | (remainder 13 4) ==> 1 | |
4272 | ||
4273 | (modulo -13 4) ==> 3 | |
4274 | (remainder -13 4) ==> -1 | |
4275 | ||
4276 | (modulo 13 -4) ==> -3 | |
4277 | (remainder 13 -4) ==> 1 | |
4278 | ||
4279 | (modulo -13 -4) ==> -1 | |
4280 | (remainder -13 -4) ==> -1 | |
4281 | ||
4282 | (remainder -13 -4.0) ==> -1.0 ; inexact | |
4283 | } | |
4284 | @end format | |
4285 | ||
4286 | @end deffn | |
4287 | ||
4288 | ||
4289 | @deffn {library procedure} gcd n1 @dots{}, | |
4290 | @deffnx {library procedure} lcm n1 @dots{}, | |
4291 | ||
4292 | These procedures return the greatest common divisor or least common | |
4293 | multiple of their arguments. The result is always non-negative. | |
4294 | @c - These procedures are exactness preserving. | |
4295 | ||
4296 | @c %R4%% I added the inexact example. | |
4297 | ||
4298 | @format | |
4299 | @t{(gcd 32 -36) ==> 4 | |
4300 | (gcd) ==> 0 | |
4301 | (lcm 32 -36) ==> 288 | |
4302 | (lcm 32.0 -36) ==> 288.0 ; inexact | |
4303 | (lcm) ==> 1 | |
4304 | } | |
4305 | @end format | |
4306 | ||
4307 | ||
4308 | @end deffn | |
4309 | ||
4310 | ||
4311 | ||
4312 | @deffn {procedure} numerator @var{q} | |
4313 | @deffnx {procedure} denominator @var{q} | |
4314 | ||
4315 | These procedures return the numerator or denominator of their | |
4316 | argument; the result is computed as if the argument was represented as | |
4317 | a fraction in lowest terms. The denominator is always positive. The | |
4318 | denominator of 0 is defined to be 1. | |
4319 | @c - The remarks about denominators are new. | |
4320 | @c - Clearly, they are exactness-preserving procedures. | |
4321 | ||
4322 | @ignore todo | |
4323 | More description and examples needed. | |
4324 | @end ignore | |
4325 | ||
4326 | ||
4327 | @format | |
4328 | @t{(numerator (/ 6 4)) ==> 3 | |
4329 | (denominator (/ 6 4)) ==> 2 | |
4330 | (denominator | |
4331 | (exact->inexact (/ 6 4))) ==> 2.0 | |
4332 | } | |
4333 | @end format | |
4334 | ||
4335 | ||
4336 | @end deffn | |
4337 | ||
4338 | ||
4339 | ||
4340 | @deffn {procedure} floor x | |
4341 | @deffnx {procedure} ceiling x | |
4342 | @deffnx {procedure} truncate x | |
4343 | @deffnx {procedure} round x | |
4344 | ||
4345 | ||
4346 | These procedures return integers. | |
7fb9c4af AW |
4347 | @samp{Floor} returns the largest integer not larger than @var{x}. |
4348 | @samp{Ceiling} returns the smallest integer not smaller than @var{x}. | |
4349 | @samp{Truncate} returns the integer closest to @var{x} whose absolute | |
4350 | value is not larger than the absolute value of @var{x}. @samp{Round} returns the | |
a0e07ba4 NJ |
4351 | closest integer to @var{x}, rounding to even when @var{x} is halfway between two |
4352 | integers. | |
4353 | ||
4354 | ||
4355 | @quotation | |
4356 | @emph{Rationale:} | |
7fb9c4af | 4357 | @samp{Round} rounds to even for consistency with the default rounding |
a0e07ba4 NJ |
4358 | mode specified by the IEEE floating point standard. |
4359 | @end quotation | |
4360 | ||
4361 | ||
4362 | ||
4363 | @quotation | |
4364 | @emph{Note:} | |
4365 | If the argument to one of these procedures is inexact, then the result | |
4366 | will also be inexact. If an exact value is needed, the | |
4367 | result should be passed to the @samp{inexact->exact} procedure. | |
4368 | @end quotation | |
4369 | ||
4370 | ||
4371 | ||
4372 | @format | |
4373 | @t{(floor -4.3) ==> -5.0 | |
4374 | (ceiling -4.3) ==> -4.0 | |
4375 | (truncate -4.3) ==> -4.0 | |
4376 | (round -4.3) ==> -4.0 | |
4377 | ||
4378 | (floor 3.5) ==> 3.0 | |
4379 | (ceiling 3.5) ==> 4.0 | |
4380 | (truncate 3.5) ==> 3.0 | |
4381 | (round 3.5) ==> 4.0 ; inexact | |
4382 | ||
4383 | (round 7/2) ==> 4 ; exact | |
4384 | (round 7) ==> 7 | |
4385 | } | |
4386 | @end format | |
4387 | ||
4388 | ||
4389 | @end deffn | |
4390 | ||
4391 | ||
4392 | @deffn {library procedure} rationalize x y | |
4393 | @c - \proto{rationalize}{ x}{procedure} | |
4394 | ||
4395 | ||
7fb9c4af | 4396 | @samp{Rationalize} returns the @emph{simplest} rational number |
a0e07ba4 NJ |
4397 | differing from @var{x} by no more than @var{y}. A rational number r_1 is |
4398 | @emph{simpler} than another rational number | |
4399 | @cindex @w{simplest rational} | |
4400 | r_2 if r_1 = p_1/q_1 and r_2 = p_2/q_2 (in lowest terms) and |p_1|<= |p_2| and |q_1| <= |q_2|. Thus 3/5 is simpler than 4/7. | |
4401 | Although not all rationals are comparable in this ordering (consider 2/7 | |
4402 | and 3/5) any interval contains a rational number that is simpler than | |
4403 | every other rational number in that interval (the simpler 2/5 lies | |
4404 | between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of | |
4405 | all. | |
4406 | ||
4407 | ||
4408 | @format | |
4409 | @t{(rationalize | |
4410 | (inexact->exact .3) 1/10) ==> 1/3 ; exact | |
4411 | (rationalize .3 1/10) ==> #i1/3 ; inexact | |
4412 | } | |
4413 | @end format | |
4414 | ||
4415 | ||
4416 | @end deffn | |
4417 | ||
4418 | ||
4419 | @deffn {procedure} exp @var{z} | |
4420 | @deffnx {procedure} log @var{z} | |
4421 | @deffnx {procedure} sin @var{z} | |
4422 | @deffnx {procedure} cos @var{z} | |
4423 | @deffnx {procedure} tan @var{z} | |
4424 | @deffnx {procedure} asin @var{z} | |
4425 | @deffnx {procedure} acos @var{z} | |
4426 | @deffnx {procedure} atan @var{z} | |
4427 | @deffnx {procedure} atan @var{y} @var{x} | |
4428 | ||
4429 | These procedures are part of every implementation that supports | |
4430 | @c %R4%% | |
4431 | general | |
ecb87335 | 4432 | real numbers; they compute the usual transcendental functions. @samp{log} |
a0e07ba4 | 4433 | computes the natural logarithm of @var{z} (not the base ten logarithm). |
ecb87335 | 4434 | @samp{asin}, @samp{acos}, and @samp{atan} compute arcsine (sin^-1), |
a0e07ba4 NJ |
4435 | arccosine (cos^-1), and arctangent (tan^-1), respectively. |
4436 | The two-argument variant of @samp{atan} computes @t{(angle | |
4437 | (make-rectangular @var{x} @var{y}))} (see below), even in implementations | |
4438 | that don't support general complex numbers. | |
4439 | ||
4440 | In general, the mathematical functions log, arcsine, arccosine, and | |
4441 | arctangent are multiply defined. | |
4442 | The value of log z is defined to be the one whose imaginary | |
4443 | part lies in the range from -pi (exclusive) to pi (inclusive). | |
4444 | log 0 is undefined. | |
4445 | With log defined this way, the values of sin^-1 z, cos^-1 z, | |
4446 | and tan^-1 z are according to the following formulae: | |
4447 | ||
4448 | ||
eaf2d3f2 | 4449 | @center sin^-1 z = -i log (i z + sqrt(1 - z^2)) |
a0e07ba4 NJ |
4450 | |
4451 | ||
4452 | ||
4453 | @center cos^-1 z = pi / 2 - sin^-1 z | |
4454 | ||
4455 | ||
4456 | ||
4457 | @center tan^-1 z = (log (1 + i z) - log (1 - i z)) / (2 i) | |
4458 | ||
4459 | ||
4460 | The above specification follows [CLtL], which in turn | |
4461 | cites [Penfield81]; refer to these sources for more detailed | |
4462 | discussion of branch cuts, boundary conditions, and implementation of | |
4463 | these functions. When it is possible these procedures produce a real | |
4464 | result from a real argument. | |
4465 | ||
4466 | @c %R4%% | |
4467 | ||
4468 | @ignore todo | |
4469 | The cited references are likely to change their branch cuts | |
4470 | soon to allow for the possibility of distinct positive and negative | |
4471 | zeroes, as in IEEE floating point. We may not want to follow those | |
4472 | changes, since we may want a complex number with zero imaginary part | |
4473 | (whether positive or negative zero) to be treated as a real. I don't | |
4474 | think there are any better standards for complex arithmetic than the | |
4475 | ones cited, so we're really on our own here. | |
4476 | @end ignore | |
4477 | ||
4478 | ||
4479 | @end deffn | |
4480 | ||
4481 | ||
4482 | ||
4483 | @deffn {procedure} sqrt @var{z} | |
4484 | ||
4485 | Returns the principal square root of @var{z}. The result will have | |
4486 | either positive real part, or zero real part and non-negative imaginary | |
4487 | part. | |
4488 | @end deffn | |
4489 | ||
4490 | ||
4491 | ||
4492 | @deffn {procedure} expt z1 z2 | |
4493 | ||
4494 | Returns @var{z1} raised to the power @var{z2}. For z_1 ~= 0 | |
4495 | ||
4496 | ||
4497 | @center z_1^z_2 = e^z_2 log z_1 | |
4498 | ||
4499 | 0^z is 1 if z = 0 and 0 otherwise. | |
4500 | @end deffn | |
4501 | ||
4502 | @c - \begin{entry}{%- | |
4503 | @c - \proto{approximate}{ z x}{procedure}} | |
4504 | @c - | |
4505 | @c - Returns an approximation to \vr{z} in a representation whose precision is | |
4506 | @c - the same as that | |
4507 | @c - of the representation of \vr{x}, which must be an inexact number. The | |
4508 | @c - result is always inexact. | |
4509 | @c - | |
4510 | @c - \begin{scheme} | |
4511 | @c - (approximate 3.1415926535 1F10) | |
4512 | @c - \ev 3.14159F0 | |
4513 | @c - (approximate 3.1415926535 \#I65535) | |
4514 | @c - \ev \#I3 | |
4515 | @c - (approximate 3.14F0 1L8) | |
4516 | @c - \ev 3.14L0 | |
4517 | @c - (approximate 3.1415926535F0 1L8) | |
4518 | @c - \ev 3.14159L0 | |
4519 | @c - \end{scheme} | |
4520 | @c - \end{entry} | |
4521 | ||
4522 | ||
4523 | ||
4524 | ||
4525 | @deffn {procedure} make-rectangular x1 x2 | |
4526 | @deffnx {procedure} make-polar x3 x4 | |
4527 | @deffnx {procedure} real-part @var{z} | |
4528 | @deffnx {procedure} imag-part @var{z} | |
4529 | @deffnx {procedure} magnitude @var{z} | |
4530 | @deffnx {procedure} angle @var{z} | |
4531 | ||
4532 | These procedures are part of every implementation that supports | |
4533 | @c %R4%% | |
4534 | general | |
4535 | complex numbers. Suppose @var{x1}, @var{x2}, @var{x3}, and @var{x4} are | |
4536 | real numbers and @var{z} is a complex number such that | |
4537 | ||
4538 | ||
4539 | @center @var{z} = @var{x1} + @var{x2}@w{i} = @var{x3} . e^@w{i} @var{x4} | |
4540 | ||
4541 | Then | |
4542 | ||
4543 | @format | |
4544 | @t{(make-rectangular @var{x1} @var{x2}) ==> @var{z} | |
4545 | (make-polar @var{x3} @var{x4}) ==> @var{z} | |
4546 | (real-part @var{z}) ==> @var{x1} | |
4547 | (imag-part @var{z}) ==> @var{x2} | |
4548 | (magnitude @var{z}) ==> |@var{x3}| | |
4549 | (angle @var{z}) ==> x_angle | |
4550 | } | |
4551 | @end format | |
4552 | ||
4553 | where -pi < x_angle <= pi with x_angle = @var{x4} + 2pi n | |
4554 | for some integer n. | |
4555 | ||
4556 | ||
4557 | @quotation | |
4558 | @emph{Rationale:} | |
7fb9c4af | 4559 | @samp{Magnitude} is the same as @code{abs} for a real argument, |
a0e07ba4 NJ |
4560 | @vindex @w{abs} |
4561 | but @samp{abs} must be present in all implementations, whereas | |
4562 | @samp{magnitude} need only be present in implementations that support | |
4563 | general complex numbers. | |
4564 | @end quotation | |
4565 | ||
4566 | ||
4567 | @end deffn | |
4568 | ||
4569 | ||
4570 | ||
4571 | @deffn {procedure} exact->inexact @var{z} | |
4572 | @deffnx {procedure} inexact->exact @var{z} | |
4573 | ||
7fb9c4af | 4574 | @samp{Exact->inexact} returns an @r{inexact} representation of @var{z}. |
a0e07ba4 NJ |
4575 | The value returned is the |
4576 | @r{inexact} number that is numerically closest to the argument. | |
4577 | @c %R4%%For | |
4578 | @c \tupe{exact} arguments which have no reasonably close \tupe{inexact} equivalent, | |
4579 | @c it is permissible to signal an error. | |
4580 | If an @r{exact} argument has no reasonably close @r{inexact} equivalent, | |
4581 | then a violation of an implementation restriction may be reported. | |
4582 | ||
7fb9c4af | 4583 | @samp{Inexact->exact} returns an @r{exact} representation of |
a0e07ba4 NJ |
4584 | @var{z}. The value returned is the @r{exact} number that is numerically |
4585 | closest to the argument. | |
4586 | @c %R4%% For \tupe{inexact} arguments which have no | |
4587 | @c reasonably close \tupe{exact} equivalent, it is permissible to signal | |
4588 | @c an error. | |
4589 | If an @r{inexact} argument has no reasonably close @r{exact} equivalent, | |
4590 | then a violation of an implementation restriction may be reported. | |
4591 | ||
4592 | @c %R%% I moved this to the section on implementation restrictions. | |
4593 | @c For any implementation that supports \tupe{inexact} quantities, | |
4594 | @c there is a subset of the integers for which there are both \tupe{exact} and | |
4595 | @c \tupe{inexact} representations. This subset must include the non-negative | |
4596 | @c integers up to a limit specified by the implementation. The limit | |
4597 | @c must be big enough to represent all digits in reasonable radices, and | |
4598 | @c may correspond to some natural word size for the implementation. For | |
4599 | @c such integers, these procedures implement the natural one-to-one | |
4600 | @c correspondence between the representations. | |
4601 | ||
4602 | These procedures implement the natural one-to-one correspondence between | |
4603 | @r{exact} and @r{inexact} integers throughout an | |
4604 | implementation-dependent range. See section @ref{Implementation restrictions}. | |
4605 | ||
4606 | @end deffn | |
4607 | ||
4608 | @sp 3 | |
4609 | ||
4610 | @node Numerical input and output, , Numerical operations, Numbers | |
4611 | @subsection Numerical input and output | |
4612 | ||
4613 | ||
4614 | ||
4615 | @deffn {procedure} number->string z | |
4616 | @deffnx {procedure} number->string z radix | |
4617 | ||
7fb9c4af | 4618 | @var{Radix} must be an exact integer, either 2, 8, 10, or 16. If omitted, |
a0e07ba4 NJ |
4619 | @var{radix} defaults to 10. |
4620 | The procedure @samp{number->string} takes a | |
4621 | number and a radix and returns as a string an external representation of | |
4622 | the given number in the given radix such that | |
4623 | ||
4624 | @format | |
4625 | @t{(let ((number @var{number}) | |
4626 | (radix @var{radix})) | |
4627 | (eqv? number | |
4628 | (string->number (number->string number | |
4629 | radix) | |
4630 | radix))) | |
4631 | } | |
4632 | @end format | |
4633 | ||
4634 | is true. It is an error if no possible result makes this expression true. | |
4635 | ||
4636 | If @var{z} is inexact, the radix is 10, and the above expression | |
4637 | can be satisfied by a result that contains a decimal point, | |
4638 | then the result contains a decimal point and is expressed using the | |
4639 | minimum number of digits (exclusive of exponent and trailing | |
4640 | zeroes) needed to make the above expression | |
4641 | true [howtoprint], [howtoread]; | |
4642 | otherwise the format of the result is unspecified. | |
4643 | ||
4644 | The result returned by @samp{number->string} | |
4645 | never contains an explicit radix prefix. | |
4646 | ||
4647 | ||
4648 | @quotation | |
4649 | @emph{Note:} | |
4650 | The error case can occur only when @var{z} is not a complex number | |
4651 | or is a complex number with a non-rational real or imaginary part. | |
4652 | @end quotation | |
4653 | ||
4654 | ||
4655 | ||
4656 | @quotation | |
4657 | @emph{Rationale:} | |
4658 | If @var{z} is an inexact number represented using flonums, and | |
4659 | the radix is 10, then the above expression is normally satisfied by | |
4660 | a result containing a decimal point. The unspecified case | |
4661 | allows for infinities, NaNs, and non-flonum representations. | |
4662 | @end quotation | |
4663 | ||
4664 | ||
4665 | @end deffn | |
4666 | ||
4667 | ||
4668 | ||
4669 | @deffn {procedure} string->number string | |
4670 | @deffnx {procedure} string->number string radix | |
4671 | ||
4672 | @c %R4%% I didn't include the (string->number string radix exactness) | |
4673 | @c case, since I haven't heard any resolution of the coding to be used | |
4674 | @c for the third argument. | |
4675 | ||
4676 | Returns a number of the maximally precise representation expressed by the | |
7fb9c4af | 4677 | given @var{string}. @var{Radix} must be an exact integer, either 2, 8, 10, |
a0e07ba4 NJ |
4678 | or 16. If supplied, @var{radix} is a default radix that may be overridden |
4679 | by an explicit radix prefix in @var{string} (e.g. @t{"#o177"}). If @var{radix} | |
4680 | is not supplied, then the default radix is 10. If @var{string} is not | |
4681 | a syntactically valid notation for a number, then @samp{string->number} | |
4682 | returns @t{#f}. | |
4683 | ||
4684 | ||
4685 | @format | |
4686 | @t{(string->number "100") ==> 100 | |
4687 | (string->number "100" 16) ==> 256 | |
4688 | (string->number "1e2") ==> 100.0 | |
4689 | (string->number "15##") ==> 1500.0 | |
4690 | } | |
4691 | @end format | |
4692 | ||
4693 | ||
4694 | ||
4695 | @quotation | |
4696 | @emph{Note:} | |
4697 | The domain of @samp{string->number} may be restricted by implementations | |
7fb9c4af | 4698 | in the following ways. @samp{String->number} is permitted to return |
a0e07ba4 NJ |
4699 | @t{#f} whenever @var{string} contains an explicit radix prefix. |
4700 | If all numbers supported by an implementation are real, then | |
4701 | @samp{string->number} is permitted to return @t{#f} whenever | |
4702 | @var{string} uses the polar or rectangular notations for complex | |
4703 | numbers. If all numbers are integers, then | |
4704 | @samp{string->number} may return @t{#f} whenever | |
4705 | the fractional notation is used. If all numbers are exact, then | |
4706 | @samp{string->number} may return @t{#f} whenever | |
4707 | an exponent marker or explicit exactness prefix is used, or if | |
4708 | a @t{#} appears in place of a digit. If all inexact | |
4709 | numbers are integers, then | |
4710 | @samp{string->number} may return @t{#f} whenever | |
4711 | a decimal point is used. | |
4712 | @end quotation | |
4713 | ||
4714 | ||
4715 | @end deffn | |
4716 | ||
4717 | @node Other data types, Control features, Numbers, Standard procedures | |
4718 | @section Other data types | |
4719 | ||
4720 | @menu | |
4721 | * Booleans:: | |
4722 | * Pairs and lists:: | |
4723 | * Symbols:: | |
4724 | * Characters:: | |
4725 | * Strings:: | |
4726 | * Vectors:: | |
4727 | @end menu | |
4728 | ||
4729 | ||
4730 | This section describes operations on some of Scheme's non-numeric data types: | |
4731 | booleans, pairs, lists, symbols, characters, strings and vectors. | |
4732 | ||
4733 | @node Booleans, Pairs and lists, Other data types, Other data types | |
4734 | @subsection Booleans | |
4735 | ||
4736 | ||
4737 | ||
4738 | The standard boolean objects for true and false are written as | |
4739 | @t{#t} and @t{#f}. What really | |
4740 | @vindex #f | |
4741 | @vindex #t | |
4742 | matters, though, are the objects that the Scheme conditional expressions | |
4743 | (@samp{if}, @samp{cond}, @samp{and}, @samp{or}, @samp{do}) treat as | |
4744 | true or false. The phrase ``a true value'' | |
4745 | @cindex @w{false} | |
4746 | @cindex @w{true} | |
4747 | (or sometimes just ``true'') means any object treated as true by the | |
4748 | conditional expressions, and the phrase ``a false value'' (or | |
4749 | @cindex @w{false} | |
4750 | ``false'') means any object treated as false by the conditional expressions. | |
4751 | ||
4752 | Of all the standard Scheme values, only @t{#f} | |
4753 | @c is guaranteed to count | |
4754 | counts as false in conditional expressions. | |
4755 | @c It is not | |
4756 | @c specified whether the empty list\index{empty list} counts as false | |
4757 | @c or as true in conditional expressions. | |
4758 | Except for @t{#f}, | |
4759 | @c and possibly the empty list, | |
4760 | all standard Scheme values, including @t{#t}, | |
4761 | pairs, the empty list, symbols, numbers, strings, vectors, and procedures, | |
4762 | count as true. | |
4763 | ||
4764 | @c \begin{note} | |
4765 | @c In some implementations the empty list counts as false, contrary | |
4766 | @c to the above. | |
4767 | @c Nonetheless a few examples in this report assume that the | |
4768 | @c empty list counts as true, as in \cite{IEEEScheme}. | |
4769 | @c \end{note} | |
4770 | ||
4771 | @c \begin{rationale} | |
4772 | @c For historical reasons some implementations regard \schfalse{} and the | |
4773 | @c empty list as the same object. These implementations therefore cannot | |
4774 | @c make the empty list count as true in conditional expressions. | |
4775 | @c \end{rationale} | |
4776 | ||
4777 | ||
4778 | @quotation | |
4779 | @emph{Note:} | |
4780 | Programmers accustomed to other dialects of Lisp should be aware that | |
4781 | Scheme distinguishes both @t{#f} and the empty list | |
4782 | @cindex @w{empty list} | |
4783 | from the symbol @code{nil}. | |
4784 | @vindex @w{nil} | |
4785 | @end quotation | |
4786 | ||
4787 | ||
4788 | Boolean constants evaluate to themselves, so they do not need to be quoted | |
4789 | in programs. | |
4790 | ||
4791 | ||
4792 | @example | |
4793 | ||
4794 | #t ==> #t | |
4795 | #f ==> #f | |
4796 | '#f ==> #f | |
4797 | ||
4798 | @end example | |
4799 | ||
4800 | ||
4801 | ||
4802 | ||
4803 | @deffn {library procedure} not obj | |
4804 | ||
7fb9c4af | 4805 | @samp{Not} returns @t{#t} if @var{obj} is false, and returns |
a0e07ba4 NJ |
4806 | @t{#f} otherwise. |
4807 | ||
4808 | ||
4809 | @format | |
4810 | @t{(not #t) ==> #f | |
4811 | (not 3) ==> #f | |
4812 | (not (list 3)) ==> #f | |
4813 | (not #f) ==> #t | |
4814 | (not '()) ==> #f | |
4815 | (not (list)) ==> #f | |
4816 | (not 'nil) ==> #f | |
4817 | } | |
4818 | @end format | |
4819 | ||
4820 | ||
4821 | @end deffn | |
4822 | ||
4823 | ||
4824 | ||
4825 | @deffn {library procedure} boolean? obj | |
4826 | ||
7fb9c4af | 4827 | @samp{Boolean?} returns @t{#t} if @var{obj} is either @t{#t} or |
a0e07ba4 NJ |
4828 | @t{#f} and returns @t{#f} otherwise. |
4829 | ||
4830 | ||
4831 | @format | |
4832 | @t{(boolean? #f) ==> #t | |
4833 | (boolean? 0) ==> #f | |
4834 | (boolean? '()) ==> #f | |
4835 | } | |
4836 | @end format | |
4837 | ||
4838 | ||
4839 | @end deffn | |
4840 | ||
4841 | ||
4842 | @node Pairs and lists, Symbols, Booleans, Other data types | |
4843 | @subsection Pairs and lists | |
4844 | ||
4845 | ||
4846 | ||
4847 | A @dfn{pair} (sometimes called a @dfn{dotted pair}) is a | |
4848 | @cindex @w{dotted pair} | |
4849 | @cindex @w{pair} | |
4850 | record structure with two fields called the car and cdr fields (for | |
4851 | historical reasons). Pairs are created by the procedure @samp{cons}. | |
4852 | The car and cdr fields are accessed by the procedures @samp{car} and | |
4853 | @samp{cdr}. The car and cdr fields are assigned by the procedures | |
4854 | @samp{set-car!} and @samp{set-cdr!}. | |
4855 | ||
4856 | Pairs are used primarily to represent lists. A list can | |
4857 | be defined recursively as either the empty list or a pair whose | |
4858 | @cindex @w{empty list} | |
4859 | cdr is a list. More precisely, the set of lists is defined as the smallest | |
4860 | set @var{X} such that | |
4861 | ||
4862 | ||
4863 | ||
4864 | @itemize @bullet | |
4865 | ||
4866 | @item | |
4867 | The empty list is in @var{X}. | |
4868 | @item | |
4869 | If @var{list} is in @var{X}, then any pair whose cdr field contains | |
4870 | @var{list} is also in @var{X}. | |
4871 | ||
4872 | @end itemize | |
4873 | ||
4874 | ||
4875 | The objects in the car fields of successive pairs of a list are the | |
4876 | elements of the list. For example, a two-element list is a pair whose car | |
4877 | is the first element and whose cdr is a pair whose car is the second element | |
4878 | and whose cdr is the empty list. The length of a list is the number of | |
4879 | elements, which is the same as the number of pairs. | |
4880 | ||
4881 | The empty list is a special object of its own type | |
4882 | @cindex @w{empty list} | |
4883 | (it is not a pair); it has no elements and its length is zero. | |
4884 | ||
4885 | ||
4886 | @quotation | |
4887 | @emph{Note:} | |
4888 | The above definitions imply that all lists have finite length and are | |
4889 | terminated by the empty list. | |
4890 | @end quotation | |
4891 | ||
4892 | ||
4893 | The most general notation (external representation) for Scheme pairs is | |
4894 | the ``dotted'' notation @w{@samp{(@var{c1} .@: @var{c2})}} where | |
4895 | @var{c1} is the value of the car field and @var{c2} is the value of the | |
4896 | cdr field. For example @samp{(4 .@: 5)} is a pair whose car is 4 and whose | |
4897 | cdr is 5. Note that @samp{(4 .@: 5)} is the external representation of a | |
4898 | pair, not an expression that evaluates to a pair. | |
4899 | ||
4900 | A more streamlined notation can be used for lists: the elements of the | |
4901 | list are simply enclosed in parentheses and separated by spaces. The | |
4902 | empty list is written @t{()} . For example, | |
4903 | @cindex @w{empty list} | |
4904 | ||
4905 | ||
4906 | @example | |
4907 | ||
4908 | (a b c d e) | |
4909 | ||
4910 | @end example | |
4911 | ||
4912 | ||
4913 | and | |
4914 | ||
4915 | ||
4916 | @example | |
4917 | ||
4918 | (a . (b . (c . (d . (e . ()))))) | |
4919 | ||
4920 | @end example | |
4921 | ||
4922 | ||
4923 | are equivalent notations for a list of symbols. | |
4924 | ||
4925 | A chain of pairs not ending in the empty list is called an | |
4926 | @dfn{improper list}. Note that an improper list is not a list. | |
4927 | @cindex @w{improper list} | |
4928 | The list and dotted notations can be combined to represent | |
4929 | improper lists: | |
4930 | ||
4931 | ||
4932 | @example | |
4933 | ||
4934 | (a b c . d) | |
4935 | ||
4936 | @end example | |
4937 | ||
4938 | ||
4939 | is equivalent to | |
4940 | ||
4941 | ||
4942 | @example | |
4943 | ||
4944 | (a . (b . (c . d))) | |
4945 | ||
4946 | @end example | |
4947 | ||
4948 | ||
4949 | Whether a given pair is a list depends upon what is stored in the cdr | |
4950 | field. When the @code{set-cdr!} procedure is used, an object can be a | |
4951 | @vindex @w{set-cdr!} | |
4952 | list one moment and not the next: | |
4953 | ||
4954 | ||
4955 | @example | |
4956 | ||
4957 | (define x (list 'a 'b 'c)) | |
4958 | (define y x) | |
4959 | y ==> (a b c) | |
4960 | (list? y) ==> #t | |
4961 | (set-cdr! x 4) ==> @emph{unspecified} | |
4962 | x ==> (a . 4) | |
4963 | (eqv? x y) ==> #t | |
4964 | y ==> (a . 4) | |
4965 | (list? y) ==> #f | |
4966 | (set-cdr! x x) ==> @emph{unspecified} | |
4967 | (list? x) ==> #f | |
4968 | ||
4969 | @end example | |
4970 | ||
4971 | ||
4972 | @c It is often convenient to speak of a homogeneous list of objects | |
4973 | @c of some particular data type, as for example \hbox{\cf (1 2 3)} is a list of | |
4974 | @c integers. To be more precise, suppose \var{D} is some data type. (Any | |
4975 | @c predicate defines a data type consisting of those objects of which the | |
4976 | @c predicate is true.) Then | |
4977 | ||
4978 | @c \begin{itemize} | |
4979 | @c \item The empty list is a list of \var{D}. | |
4980 | @c \item If \var{list} is a list of \var{D}, then any pair whose cdr is | |
4981 | @c \var{list} and whose car is an element of the data type \var{D} is also a | |
4982 | @c list of \var{D}. | |
4983 | @c \item There are no other lists of \var{D}. | |
4984 | @c \end{itemize} | |
4985 | ||
4986 | Within literal expressions and representations of objects read by the | |
4987 | @code{read} procedure, the forms @t{'}@r{<datum>}, | |
4988 | @vindex ' | |
4989 | @vindex @w{read} | |
4990 | @t{`}@r{<datum>}, @t{,}@r{<datum>}, and | |
4991 | @vindex , | |
4992 | @t{,@@}@r{<datum>} denote two-ele@-ment lists whose first elements are | |
4993 | the symbols @code{quote}, @code{quasiquote}, @w{@code{unquote}}, and | |
4994 | @vindex @w{unquote} | |
4995 | @vindex @w{quasiquote} | |
4996 | @vindex @w{quote} | |
4997 | @code{unquote-splicing}, respectively. The second element in each case | |
4998 | @vindex @w{unquote-splicing} | |
4999 | is @r{<datum>}. This convention is supported so that arbitrary Scheme | |
5000 | programs may be represented as lists. | |
5001 | @ignore todo | |
5002 | Can or need this be stated | |
5003 | more carefully? | |
5004 | @end ignore | |
5005 | That is, according to Scheme's grammar, every | |
5006 | <expression> is also a <datum> (see section @pxref{External representation}). | |
5007 | Among other things, this permits the use of the @samp{read} procedure to | |
5008 | parse Scheme programs. See section @ref{External representations}. | |
5009 | ||
5010 | ||
5011 | ||
5012 | @deffn {procedure} pair? obj | |
5013 | ||
7fb9c4af | 5014 | @samp{Pair?} returns @t{#t} if @var{obj} is a pair, and otherwise |
a0e07ba4 NJ |
5015 | returns @t{#f}. |
5016 | ||
5017 | ||
5018 | @format | |
5019 | @t{(pair? '(a . b)) ==> #t | |
5020 | (pair? '(a b c)) ==> #t | |
5021 | (pair? '()) ==> #f | |
5022 | (pair? '#(a b)) ==> #f | |
5023 | } | |
5024 | @end format | |
5025 | ||
5026 | @end deffn | |
5027 | ||
5028 | ||
5029 | ||
5030 | @deffn {procedure} cons obj1 obj2 | |
5031 | ||
5032 | Returns a newly allocated pair whose car is @var{obj1} and whose cdr is | |
5033 | @var{obj2}. The pair is guaranteed to be different (in the sense of | |
5034 | @samp{eqv?}) from every existing object. | |
5035 | ||
5036 | ||
5037 | @format | |
5038 | @t{(cons 'a '()) ==> (a) | |
5039 | (cons '(a) '(b c d)) ==> ((a) b c d) | |
5040 | (cons "a" '(b c)) ==> ("a" b c) | |
5041 | (cons 'a 3) ==> (a . 3) | |
5042 | (cons '(a b) 'c) ==> ((a b) . c) | |
5043 | } | |
5044 | @end format | |
5045 | ||
5046 | @end deffn | |
5047 | ||
5048 | ||
5049 | ||
5050 | @deffn {procedure} car pair | |
5051 | ||
5052 | @ignore nodomain | |
5053 | @var{Pair} must be a pair. | |
5054 | @end ignore | |
5055 | ||
5056 | Returns the contents of the car field of @var{pair}. Note that it is an | |
5057 | error to take the car of the empty list. | |
5058 | @cindex @w{empty list} | |
5059 | ||
5060 | ||
5061 | @format | |
5062 | @t{(car '(a b c)) ==> a | |
5063 | (car '((a) b c d)) ==> (a) | |
5064 | (car '(1 . 2)) ==> 1 | |
5065 | (car '()) ==> @emph{error} | |
5066 | } | |
5067 | @end format | |
5068 | ||
5069 | ||
5070 | @end deffn | |
5071 | ||
5072 | ||
5073 | ||
5074 | @deffn {procedure} cdr pair | |
5075 | ||
5076 | @ignore nodomain | |
5077 | @var{Pair} must be a pair. | |
5078 | @end ignore | |
5079 | ||
5080 | Returns the contents of the cdr field of @var{pair}. | |
5081 | Note that it is an error to take the cdr of the empty list. | |
5082 | ||
5083 | ||
5084 | @format | |
5085 | @t{(cdr '((a) b c d)) ==> (b c d) | |
5086 | (cdr '(1 . 2)) ==> 2 | |
5087 | (cdr '()) ==> @emph{error} | |
5088 | } | |
5089 | @end format | |
5090 | ||
5091 | ||
5092 | @end deffn | |
5093 | ||
5094 | ||
5095 | ||
5096 | @deffn {procedure} set-car! pair obj | |
5097 | ||
5098 | @ignore nodomain | |
5099 | @var{Pair} must be a pair. | |
5100 | @end ignore | |
5101 | ||
5102 | Stores @var{obj} in the car field of @var{pair}. | |
5103 | The value returned by @samp{set-car!} is unspecified. | |
5104 | @c <!> | |
5105 | @c This procedure can be very confusing if used indiscriminately. | |
5106 | ||
5107 | ||
5108 | @format | |
5109 | @t{(define (f) (list 'not-a-constant-list)) | |
5110 | (define (g) '(constant-list)) | |
5111 | (set-car! (f) 3) ==> @emph{unspecified} | |
5112 | (set-car! (g) 3) ==> @emph{error} | |
5113 | } | |
5114 | @end format | |
5115 | ||
5116 | ||
5117 | @end deffn | |
5118 | ||
5119 | ||
5120 | ||
5121 | @deffn {procedure} set-cdr! pair obj | |
5122 | ||
5123 | @ignore nodomain | |
5124 | @var{Pair} must be a pair. | |
5125 | @end ignore | |
5126 | ||
5127 | Stores @var{obj} in the cdr field of @var{pair}. | |
5128 | The value returned by @samp{set-cdr!} is unspecified. | |
5129 | @c <!> | |
5130 | @c This procedure can be very confusing if used indiscriminately. | |
5131 | ||
5132 | @end deffn | |
5133 | ||
5134 | ||
5135 | ||
5136 | ||
5137 | ||
5138 | ||
5139 | @deffn {library procedure} caar pair | |
5140 | @deffnx {library procedure} cadr pair | |
5141 | ||
5142 | @deffnx { @w{ @dots{}}} @w{ @dots{}} | |
5143 | ||
5144 | @deffnx {library procedure} cdddar pair | |
5145 | @deffnx {library procedure} cddddr pair | |
5146 | ||
5147 | These procedures are compositions of @samp{car} and @samp{cdr}, where | |
5148 | for example @samp{caddr} could be defined by | |
5149 | ||
5150 | ||
5151 | @format | |
5152 | @t{(define caddr (lambda (x) (car (cdr (cdr x)))))@r{.} | |
5153 | } | |
5154 | @end format | |
5155 | ||
5156 | ||
5157 | Arbitrary compositions, up to four deep, are provided. There are | |
5158 | twenty-eight of these procedures in all. | |
5159 | ||
5160 | @end deffn | |
5161 | ||
5162 | ||
5163 | ||
5164 | @deffn {library procedure} null? obj | |
5165 | ||
5166 | Returns @t{#t} if @var{obj} is the empty list, | |
5167 | @cindex @w{empty list} | |
5168 | otherwise returns @t{#f}. | |
5169 | ||
5170 | @c \begin{note} | |
5171 | @c In implementations in which the empty | |
5172 | @c list is the same as \schfalse{}, {\cf null?} will return \schtrue{} | |
5173 | @c if \var{obj} is \schfalse{}. | |
5174 | @c \end{note} | |
5175 | ||
5176 | @end deffn | |
5177 | ||
5178 | ||
5179 | @deffn {library procedure} list? obj | |
5180 | ||
5181 | Returns @t{#t} if @var{obj} is a list, otherwise returns @t{#f}. | |
5182 | By definition, all lists have finite length and are terminated by | |
5183 | the empty list. | |
5184 | ||
5185 | ||
5186 | @format | |
5187 | @t{ (list? '(a b c)) ==> #t | |
5188 | (list? '()) ==> #t | |
5189 | (list? '(a . b)) ==> #f | |
5190 | (let ((x (list 'a))) | |
5191 | (set-cdr! x x) | |
5192 | (list? x)) ==> #f | |
5193 | } | |
5194 | @end format | |
5195 | ||
5196 | @end deffn | |
5197 | ||
5198 | ||
5199 | ||
5200 | @deffn {library procedure} list @var{obj} @dots{}, | |
5201 | ||
5202 | Returns a newly allocated list of its arguments. | |
5203 | ||
5204 | ||
5205 | @format | |
5206 | @t{(list 'a (+ 3 4) 'c) ==> (a 7 c) | |
5207 | (list) ==> () | |
5208 | } | |
5209 | @end format | |
5210 | ||
5211 | @end deffn | |
5212 | ||
5213 | ||
5214 | ||
5215 | @deffn {library procedure} length list | |
5216 | ||
5217 | @ignore nodomain | |
5218 | @var{List} must be a list. | |
5219 | @end ignore | |
5220 | ||
5221 | Returns the length of @var{list}. | |
5222 | ||
5223 | ||
5224 | @format | |
5225 | @t{(length '(a b c)) ==> 3 | |
5226 | (length '(a (b) (c d e))) ==> 3 | |
5227 | (length '()) ==> 0 | |
5228 | } | |
5229 | @end format | |
5230 | ||
5231 | @end deffn | |
5232 | ||
5233 | ||
5234 | ||
5235 | @deffn {library procedure} append list @dots{}, | |
5236 | ||
5237 | @ignore nodomain | |
5238 | All @var{list}s should be lists. | |
5239 | @end ignore | |
5240 | ||
5241 | Returns a list consisting of the elements of the first @var{list} | |
5242 | followed by the elements of the other @var{list}s. | |
5243 | ||
5244 | ||
5245 | @format | |
5246 | @t{(append '(x) '(y)) ==> (x y) | |
5247 | (append '(a) '(b c d)) ==> (a b c d) | |
5248 | (append '(a (b)) '((c))) ==> (a (b) (c)) | |
5249 | } | |
5250 | @end format | |
5251 | ||
5252 | ||
5253 | The resulting list is always newly allocated, except that it shares | |
5254 | structure with the last @var{list} argument. The last argument may | |
5255 | actually be any object; an improper list results if the last argument is not a | |
5256 | proper list. | |
5257 | @ignore todo | |
5258 | This is pretty awkward. I should get Bartley to fix this. | |
5259 | @end ignore | |
5260 | ||
5261 | ||
5262 | ||
5263 | @format | |
5264 | @t{(append '(a b) '(c . d)) ==> (a b c . d) | |
5265 | (append '() 'a) ==> a | |
5266 | } | |
5267 | @end format | |
5268 | ||
5269 | @end deffn | |
5270 | ||
5271 | ||
5272 | ||
5273 | @deffn {library procedure} reverse list | |
5274 | ||
5275 | @ignore nodomain | |
5276 | @var{List} must be a list. | |
5277 | @end ignore | |
5278 | ||
5279 | Returns a newly allocated list consisting of the elements of @var{list} | |
5280 | in reverse order. | |
5281 | ||
5282 | ||
5283 | @format | |
5284 | @t{(reverse '(a b c)) ==> (c b a) | |
5285 | (reverse '(a (b c) d (e (f)))) | |
5286 | ==> ((e (f)) d (b c) a) | |
5287 | } | |
5288 | @end format | |
5289 | ||
5290 | @end deffn | |
5291 | ||
5292 | ||
5293 | ||
5294 | @deffn {library procedure} list-tail list @var{k} | |
5295 | ||
5296 | Returns the sublist of @var{list} obtained by omitting the first @var{k} | |
5297 | elements. It is an error if @var{list} has fewer than @var{k} elements. | |
7fb9c4af | 5298 | @samp{List-tail} could be defined by |
a0e07ba4 NJ |
5299 | |
5300 | ||
5301 | @format | |
5302 | @t{(define list-tail | |
5303 | (lambda (x k) | |
5304 | (if (zero? k) | |
5305 | x | |
5306 | (list-tail (cdr x) (- k 1))))) | |
5307 | } | |
5308 | @end format | |
5309 | ||
5310 | @end deffn | |
5311 | ||
5312 | ||
5313 | ||
5314 | @deffn {library procedure} list-ref list @var{k} | |
5315 | ||
5316 | Returns the @var{k}th element of @var{list}. (This is the same | |
5317 | as the car of @t{(list-tail @var{list} @var{k})}.) | |
5318 | It is an error if @var{list} has fewer than @var{k} elements. | |
5319 | ||
5320 | ||
5321 | @format | |
5322 | @t{(list-ref '(a b c d) 2) ==> c | |
5323 | (list-ref '(a b c d) | |
5324 | (inexact->exact (round 1.8))) | |
5325 | ==> c | |
5326 | } | |
5327 | @end format | |
5328 | ||
5329 | @end deffn | |
5330 | ||
5331 | ||
5332 | @c \begin{entry}{% | |
5333 | @c \proto{last-pair}{ list}{library procedure}} | |
5334 | ||
5335 | @c Returns the last pair in the nonempty, possibly improper, list \var{list}. | |
5336 | @c {\cf Last-pair} could be defined by | |
5337 | ||
5338 | @c \begin{scheme} | |
5339 | @c (define last-pair | |
5340 | @c (lambda (x) | |
5341 | @c (if (pair? (cdr x)) | |
5342 | @c (last-pair (cdr x)) | |
5343 | @c x)))% | |
5344 | @c \end{scheme} | |
5345 | ||
5346 | @c \end{entry} | |
5347 | ||
5348 | ||
5349 | ||
5350 | @deffn {library procedure} memq obj list | |
5351 | @deffnx {library procedure} memv obj list | |
5352 | @deffnx {library procedure} member obj list | |
5353 | ||
5354 | These procedures return the first sublist of @var{list} whose car is | |
5355 | @var{obj}, where the sublists of @var{list} are the non-empty lists | |
5356 | returned by @t{(list-tail @var{list} @var{k})} for @var{k} less | |
5357 | than the length of @var{list}. If | |
5358 | @var{obj} does not occur in @var{list}, then @t{#f} (not the empty list) is | |
7fb9c4af | 5359 | returned. @samp{Memq} uses @samp{eq?} to compare @var{obj} with the elements of |
a0e07ba4 NJ |
5360 | @var{list}, while @samp{memv} uses @samp{eqv?} and @samp{member} uses @samp{equal?}. |
5361 | ||
5362 | ||
5363 | @format | |
5364 | @t{(memq 'a '(a b c)) ==> (a b c) | |
5365 | (memq 'b '(a b c)) ==> (b c) | |
5366 | (memq 'a '(b c d)) ==> #f | |
5367 | (memq (list 'a) '(b (a) c)) ==> #f | |
5368 | (member (list 'a) | |
5369 | '(b (a) c)) ==> ((a) c) | |
5370 | (memq 101 '(100 101 102)) ==> @emph{unspecified} | |
5371 | (memv 101 '(100 101 102)) ==> (101 102) | |
5372 | } | |
5373 | @end format | |
5374 | ||
5375 | ||
5376 | @end deffn | |
5377 | ||
5378 | ||
5379 | ||
5380 | @deffn {library procedure} assq obj alist | |
5381 | @deffnx {library procedure} assv obj alist | |
5382 | @deffnx {library procedure} assoc obj alist | |
5383 | ||
7fb9c4af | 5384 | @var{Alist} (for ``association list'') must be a list of |
a0e07ba4 NJ |
5385 | pairs. These procedures find the first pair in @var{alist} whose car field is @var{obj}, |
5386 | and returns that pair. If no pair in @var{alist} has @var{obj} as its | |
7fb9c4af | 5387 | car, then @t{#f} (not the empty list) is returned. @samp{Assq} uses |
a0e07ba4 NJ |
5388 | @samp{eq?} to compare @var{obj} with the car fields of the pairs in @var{alist}, |
5389 | while @samp{assv} uses @samp{eqv?} and @samp{assoc} uses @samp{equal?}. | |
5390 | ||
5391 | ||
5392 | @format | |
5393 | @t{(define e '((a 1) (b 2) (c 3))) | |
5394 | (assq 'a e) ==> (a 1) | |
5395 | (assq 'b e) ==> (b 2) | |
5396 | (assq 'd e) ==> #f | |
5397 | (assq (list 'a) '(((a)) ((b)) ((c)))) | |
5398 | ==> #f | |
5399 | (assoc (list 'a) '(((a)) ((b)) ((c)))) | |
5400 | ==> ((a)) | |
5401 | (assq 5 '((2 3) (5 7) (11 13))) | |
5402 | ==> @emph{unspecified} | |
5403 | (assv 5 '((2 3) (5 7) (11 13))) | |
5404 | ==> (5 7) | |
5405 | } | |
5406 | @end format | |
5407 | ||
5408 | ||
5409 | ||
5410 | ||
5411 | @quotation | |
5412 | @emph{Rationale:} | |
5413 | Although they are ordinarily used as predicates, | |
5414 | @samp{memq}, @samp{memv}, @samp{member}, @samp{assq}, @samp{assv}, and @samp{assoc} do not | |
5415 | have question marks in their names because they return useful values rather | |
5416 | than just @t{#t} or @t{#f}. | |
5417 | @end quotation | |
5418 | ||
5419 | @end deffn | |
5420 | ||
5421 | ||
5422 | @node Symbols, Characters, Pairs and lists, Other data types | |
5423 | @subsection Symbols | |
5424 | ||
5425 | ||
5426 | ||
5427 | Symbols are objects whose usefulness rests on the fact that two | |
5428 | symbols are identical (in the sense of @samp{eqv?}) if and only if their | |
5429 | names are spelled the same way. This is exactly the property needed to | |
5430 | represent identifiers in programs, and so most | |
5431 | @cindex @w{identifier} | |
5432 | implementations of Scheme use them internally for that purpose. Symbols | |
5433 | are useful for many other applications; for instance, they may be used | |
5434 | the way enumerated values are used in Pascal. | |
5435 | ||
5436 | The rules for writing a symbol are exactly the same as the rules for | |
5437 | writing an identifier; see sections @ref{Identifiers} | |
5438 | and @ref{Lexical structure}. | |
5439 | ||
5440 | It is guaranteed that any symbol that has been returned as part of | |
5441 | a literal expression, or read using the @samp{read} procedure, and | |
5442 | subsequently written out using the @samp{write} procedure, will read back | |
5443 | in as the identical symbol (in the sense of @samp{eqv?}). The | |
5444 | @samp{string->symbol} procedure, however, can create symbols for | |
5445 | which this write/read invariance may not hold because their names | |
5446 | contain special characters or letters in the non-standard case. | |
5447 | ||
5448 | ||
5449 | @quotation | |
5450 | @emph{Note:} | |
5451 | Some implementations of Scheme have a feature known as ``slashification'' | |
5452 | in order to guarantee write/read invariance for all symbols, but | |
5453 | historically the most important use of this feature has been to | |
5454 | compensate for the lack of a string data type. | |
5455 | ||
5456 | Some implementations also have ``uninterned symbols'', which | |
5457 | defeat write/read invariance even in implementations with slashification, | |
5458 | and also generate exceptions to the rule that two symbols are the same | |
5459 | if and only if their names are spelled the same. | |
5460 | @end quotation | |
5461 | ||
5462 | ||
5463 | ||
5464 | ||
5465 | @deffn {procedure} symbol? obj | |
5466 | ||
5467 | Returns @t{#t} if @var{obj} is a symbol, otherwise returns @t{#f}. | |
5468 | ||
5469 | ||
5470 | @format | |
5471 | @t{(symbol? 'foo) ==> #t | |
5472 | (symbol? (car '(a b))) ==> #t | |
5473 | (symbol? "bar") ==> #f | |
5474 | (symbol? 'nil) ==> #t | |
5475 | (symbol? '()) ==> #f | |
5476 | (symbol? #f) ==> #f | |
5477 | } | |
5478 | @end format | |
5479 | ||
5480 | @end deffn | |
5481 | ||
5482 | ||
5483 | ||
5484 | @deffn {procedure} symbol->string symbol | |
5485 | ||
5486 | Returns the name of @var{symbol} as a string. If the symbol was part of | |
5487 | an object returned as the value of a literal expression | |
5488 | (section @pxref{Literal expressions}) or by a call to the @samp{read} procedure, | |
5489 | and its name contains alphabetic characters, then the string returned | |
5490 | will contain characters in the implementation's preferred standard | |
5491 | case---some implementations will prefer upper case, others lower case. | |
5492 | If the symbol was returned by @samp{string->symbol}, the case of | |
5493 | characters in the string returned will be the same as the case in the | |
5494 | string that was passed to @samp{string->symbol}. It is an error | |
5495 | to apply mutation procedures like @code{string-set!} to strings returned | |
5496 | @vindex @w{string-set!} | |
5497 | by this procedure. | |
5498 | ||
5499 | The following examples assume that the implementation's standard case is | |
5500 | lower case: | |
5501 | ||
5502 | ||
5503 | @format | |
5504 | @t{(symbol->string 'flying-fish) | |
5505 | ==> "flying-fish" | |
5506 | (symbol->string 'Martin) ==> "martin" | |
5507 | (symbol->string | |
5508 | (string->symbol "Malvina")) | |
5509 | ==> "Malvina" | |
5510 | } | |
5511 | @end format | |
5512 | ||
5513 | @end deffn | |
5514 | ||
5515 | ||
5516 | ||
5517 | @deffn {procedure} string->symbol string | |
5518 | ||
5519 | Returns the symbol whose name is @var{string}. This procedure can | |
5520 | create symbols with names containing special characters or letters in | |
5521 | the non-standard case, but it is usually a bad idea to create such | |
5522 | symbols because in some implementations of Scheme they cannot be read as | |
5523 | themselves. See @samp{symbol->string}. | |
5524 | ||
5525 | The following examples assume that the implementation's standard case is | |
5526 | lower case: | |
5527 | ||
5528 | ||
5529 | @format | |
5530 | @t{(eq? 'mISSISSIppi 'mississippi) | |
5531 | ==> #t | |
5532 | (string->symbol "mISSISSIppi") | |
5533 | ==> | |
5534 | @r{}the symbol with name "mISSISSIppi" | |
5535 | (eq? 'bitBlt (string->symbol "bitBlt")) | |
5536 | ==> #f | |
5537 | (eq? 'JollyWog | |
5538 | (string->symbol | |
5539 | (symbol->string 'JollyWog))) | |
5540 | ==> #t | |
5541 | (string=? "K. Harper, M.D." | |
5542 | (symbol->string | |
5543 | (string->symbol "K. Harper, M.D."))) | |
5544 | ==> #t | |
5545 | } | |
5546 | @end format | |
5547 | ||
5548 | ||
5549 | @end deffn | |
5550 | ||
5551 | ||
5552 | @node Characters, Strings, Symbols, Other data types | |
5553 | @subsection Characters | |
5554 | ||
5555 | ||
5556 | ||
5557 | Characters are objects that represent printed characters such as | |
5558 | letters and digits. | |
5559 | @c There is no requirement that the data type of | |
5560 | @c characters be disjoint from other data types; implementations are | |
5561 | @c encouraged to have a separate character data type, but may choose to | |
5562 | @c represent characters as integers, strings, or some other type. | |
5563 | Characters are written using the notation #\@r{<character>} | |
5564 | or #\@r{<character name>}. | |
5565 | For example: | |
5566 | ||
5567 | ||
5568 | ||
5569 | @center @c begin-tabular | |
5570 | @quotation | |
5571 | @table @asis | |
5572 | @item @t{#\a} | |
5573 | ; lower case letter | |
5574 | @item @t{#\A} | |
5575 | ; upper case letter | |
5576 | @item @t{#\(} | |
5577 | ; left parenthesis | |
5578 | @item @t{#\ } | |
5579 | ; the space character | |
5580 | @item @t{#\space} | |
5581 | ; the preferred way to write a space | |
5582 | @item @t{#\newline} | |
5583 | ; the newline character | |
5584 | @item | |
5585 | @end table | |
5586 | @end quotation | |
5587 | ||
5588 | ||
5589 | ||
5590 | ||
5591 | Case is significant in #\@r{<character>}, but not in | |
5592 | #\@r{<character name>}. | |
5593 | @c \hyper doesn't | |
5594 | ||
5595 | @c allow a linebreak | |
5596 | If @r{<character>} in | |
5597 | #\@r{<character>} is alphabetic, then the character | |
5598 | following @r{<character>} must be a delimiter character such as a | |
5599 | space or parenthesis. This rule resolves the ambiguous case where, for | |
5600 | example, the sequence of characters ``@t{#\ space}'' | |
5601 | could be taken to be either a representation of the space character or a | |
5602 | representation of the character ``@t{#\ s}'' followed | |
5603 | by a representation of the symbol ``@t{pace}.'' | |
5604 | ||
5605 | @ignore todo | |
5606 | Fix | |
5607 | @end ignore | |
5608 | ||
5609 | Characters written in the #\ notation are self-evaluating. | |
5610 | That is, they do not have to be quoted in programs. | |
5611 | @c The \sharpsign\backwhack{} | |
5612 | @c notation is not an essential part of Scheme, however. Even implementations | |
5613 | @c that support the \sharpsign\backwhack{} notation for input do not have to | |
5614 | @c support it for output. | |
5615 | ||
5616 | Some of the procedures that operate on characters ignore the | |
5617 | difference between upper case and lower case. The procedures that | |
5618 | ignore case have @w{``@t{-ci}''} (for ``case | |
5619 | insensitive'') embedded in their names. | |
5620 | ||
5621 | ||
5622 | ||
5623 | @deffn {procedure} char? obj | |
5624 | ||
5625 | Returns @t{#t} if @var{obj} is a character, otherwise returns @t{#f}. | |
5626 | ||
5627 | @end deffn | |
5628 | ||
5629 | ||
5630 | ||
5631 | @deffn {procedure} char=? char1 char2 | |
5632 | @deffnx {procedure} char<? char1 char2 | |
5633 | @deffnx {procedure} char>? char1 char2 | |
5634 | @deffnx {procedure} char<=? char1 char2 | |
5635 | @deffnx {procedure} char>=? char1 char2 | |
5636 | ||
5637 | ||
5638 | @ignore nodomain | |
5639 | Both @var{char1} and @var{char2} must be characters. | |
5640 | @end ignore | |
5641 | ||
5642 | These procedures impose a total ordering on the set of characters. It | |
5643 | is guaranteed that under this ordering: | |
5644 | ||
5645 | ||
5646 | ||
5647 | @itemize @bullet | |
5648 | ||
5649 | @item | |
5650 | The upper case characters are in order. For example, @samp{(char<? #\A #\B)} returns @t{#t}. | |
5651 | @item | |
5652 | The lower case characters are in order. For example, @samp{(char<? #\a #\b)} returns @t{#t}. | |
5653 | @item | |
5654 | The digits are in order. For example, @samp{(char<? #\0 #\9)} returns @t{#t}. | |
5655 | @item | |
5656 | Either all the digits precede all the upper case letters, or vice versa. | |
5657 | @item | |
5658 | Either all the digits precede all the lower case letters, or vice versa. | |
5659 | ||
5660 | @end itemize | |
5661 | ||
5662 | ||
5663 | Some implementations may generalize these procedures to take more than | |
5664 | two arguments, as with the corresponding numerical predicates. | |
5665 | ||
5666 | @end deffn | |
5667 | ||
5668 | ||
5669 | ||
5670 | @deffn {library procedure} char-ci=? char1 char2 | |
5671 | @deffnx {library procedure} char-ci<? char1 char2 | |
5672 | @deffnx {library procedure} char-ci>? char1 char2 | |
5673 | @deffnx {library procedure} char-ci<=? char1 char2 | |
5674 | @deffnx {library procedure} char-ci>=? char1 char2 | |
5675 | ||
5676 | @ignore nodomain | |
5677 | Both @var{char1} and @var{char2} must be characters. | |
5678 | @end ignore | |
5679 | ||
5680 | These procedures are similar to @samp{char=?} et cetera, but they treat | |
5681 | upper case and lower case letters as the same. For example, @samp{(char-ci=? #\A #\a)} returns @t{#t}. Some | |
5682 | implementations may generalize these procedures to take more than two | |
5683 | arguments, as with the corresponding numerical predicates. | |
5684 | ||
5685 | @end deffn | |
5686 | ||
5687 | ||
5688 | ||
5689 | @deffn {library procedure} char-alphabetic? char | |
5690 | @deffnx {library procedure} char-numeric? char | |
5691 | @deffnx {library procedure} char-whitespace? char | |
5692 | @deffnx {library procedure} char-upper-case? letter | |
5693 | @deffnx {library procedure} char-lower-case? letter | |
5694 | ||
5695 | These procedures return @t{#t} if their arguments are alphabetic, | |
5696 | numeric, whitespace, upper case, or lower case characters, respectively, | |
5697 | otherwise they return @t{#f}. The following remarks, which are specific to | |
5698 | the ASCII character set, are intended only as a guide: The alphabetic characters | |
5699 | are the 52 upper and lower case letters. The numeric characters are the | |
5700 | ten decimal digits. The whitespace characters are space, tab, line | |
5701 | feed, form feed, and carriage return. | |
5702 | @end deffn | |
5703 | ||
5704 | ||
5705 | @c %R4%%\begin{entry}{% | |
5706 | @c \proto{char-upper-case?}{ letter}{procedure} | |
5707 | @c \proto{char-lower-case?}{ letter}{procedure}} | |
5708 | ||
5709 | @c \domain{\var{Letter} must be an alphabetic character.} | |
5710 | @c These procedures return \schtrue{} if their arguments are upper case or | |
5711 | @c lower case characters, respectively, otherwise they return \schfalse. | |
5712 | @c \end{entry} | |
5713 | ||
5714 | ||
5715 | ||
5716 | @deffn {procedure} char->integer char | |
5717 | @deffnx {procedure} integer->char @var{n} | |
5718 | ||
5719 | Given a character, @samp{char->integer} returns an exact integer | |
5720 | representation of the character. Given an exact integer that is the image of | |
5721 | a character under @samp{char->integer}, @samp{integer->char} | |
5722 | returns that character. These procedures implement order-preserving isomorphisms | |
5723 | between the set of characters under the @code{char<=?} ordering and some | |
5724 | @vindex @w{char<=?} | |
5725 | subset of the integers under the @samp{<=} ordering. That is, if | |
5726 | ||
5727 | ||
5728 | @format | |
5729 | @t{(char<=? @var{a} @var{b}) @result{} #t @r{}and (<= @var{x} @var{y}) @result{} #t | |
5730 | } | |
5731 | @end format | |
5732 | ||
5733 | ||
5734 | ||
5735 | @noindent | |
5736 | and @var{x} and @var{y} are in the domain of | |
5737 | @samp{integer->char}, then | |
5738 | ||
5739 | ||
5740 | @format | |
5741 | @t{(<= (char->integer @var{a}) | |
5742 | (char->integer @var{b})) ==> #t | |
5743 | ||
5744 | (char<=? (integer->char @var{x}) | |
5745 | (integer->char @var{y})) ==> #t | |
5746 | } | |
5747 | @end format | |
5748 | ||
5749 | ||
5750 | @end deffn | |
5751 | ||
5752 | ||
5753 | ||
5754 | @deffn {library procedure} char-upcase char | |
5755 | @deffnx {library procedure} char-downcase char | |
5756 | ||
5757 | @ignore nodomain | |
5758 | @var{Char} must be a character. | |
5759 | @end ignore | |
5760 | ||
5761 | These procedures return a character @var{char2} such that @samp{(char-ci=? @var{char} @var{char2})}. In addition, if @var{char} is | |
5762 | alphabetic, then the result of @samp{char-upcase} is upper case and the | |
5763 | result of @samp{char-downcase} is lower case. | |
5764 | ||
5765 | @end deffn | |
5766 | ||
5767 | ||
5768 | @node Strings, Vectors, Characters, Other data types | |
5769 | @subsection Strings | |
5770 | ||
5771 | ||
5772 | ||
5773 | Strings are sequences of characters. | |
5774 | @c In some implementations of Scheme | |
5775 | @c they are immutable; other implementations provide destructive procedures | |
5776 | @c such as {\cf string-set!}\ that alter string objects. | |
5777 | Strings are written as sequences of characters enclosed within doublequotes | |
5778 | (@samp{"}). A doublequote can be written inside a string only by escaping | |
5779 | it with a backslash (\), as in | |
5780 | ||
5781 | ||
5782 | @example | |
5783 | ||
5784 | "The word \"recursion\" has many meanings." | |
5785 | ||
5786 | @end example | |
5787 | ||
5788 | ||
5789 | A backslash can be written inside a string only by escaping it with another | |
5790 | backslash. Scheme does not specify the effect of a backslash within a | |
5791 | string that is not followed by a doublequote or backslash. | |
5792 | ||
5793 | A string constant may continue from one line to the next, but | |
5794 | the exact contents of such a string are unspecified. | |
5795 | @c this is | |
5796 | @c usually a bad idea because | |
5797 | @c the exact effect may vary from one computer | |
5798 | @c system to another. | |
5799 | ||
5800 | The @emph{length} of a string is the number of characters that it | |
5801 | contains. This number is an exact, non-negative integer that is fixed when the | |
5802 | string is created. The @dfn{valid indexes} of a string are the | |
5803 | @cindex @w{valid indexes} | |
5804 | exact non-negative integers less than the length of the string. The first | |
5805 | character of a string has index 0, the second has index 1, and so on. | |
5806 | ||
5807 | In phrases such as ``the characters of @var{string} beginning with | |
5808 | index @var{start} and ending with index @var{end},'' it is understood | |
5809 | that the index @var{start} is inclusive and the index @var{end} is | |
5810 | exclusive. Thus if @var{start} and @var{end} are the same index, a null | |
5811 | substring is referred to, and if @var{start} is zero and @var{end} is | |
5812 | the length of @var{string}, then the entire string is referred to. | |
5813 | ||
5814 | Some of the procedures that operate on strings ignore the | |
5815 | difference between upper and lower case. The versions that ignore case | |
5816 | have @w{``@samp{-ci}''} (for ``case insensitive'') embedded in their | |
5817 | names. | |
5818 | ||
5819 | ||
5820 | ||
5821 | @deffn {procedure} string? obj | |
5822 | ||
5823 | Returns @t{#t} if @var{obj} is a string, otherwise returns @t{#f}. | |
5824 | @end deffn | |
5825 | ||
5826 | ||
5827 | ||
5828 | @deffn {procedure} make-string @var{k} | |
5829 | @deffnx {procedure} make-string @var{k} char | |
5830 | ||
5831 | @c \domain{\vr{k} must be a non-negative integer, and \var{char} must be | |
5832 | @c a character.} | |
7fb9c4af AW |
5833 | @samp{Make-string} returns a newly allocated string of |
5834 | length @var{k}. If @var{char} is given, then all elements of the string | |
5835 | are initialized to @var{char}, otherwise the contents of the | |
5836 | @var{string} are unspecified. | |
a0e07ba4 NJ |
5837 | |
5838 | @end deffn | |
5839 | ||
5840 | ||
5841 | @deffn {library procedure} string char @dots{}, | |
5842 | ||
5843 | Returns a newly allocated string composed of the arguments. | |
5844 | ||
5845 | @end deffn | |
5846 | ||
5847 | ||
5848 | @deffn {procedure} string-length string | |
5849 | ||
5850 | Returns the number of characters in the given @var{string}. | |
5851 | @end deffn | |
5852 | ||
5853 | ||
5854 | ||
5855 | @deffn {procedure} string-ref string @var{k} | |
5856 | ||
5857 | @var{k} must be a valid index of @var{string}. | |
7fb9c4af | 5858 | @samp{String-ref} returns character @var{k} of @var{string} using zero-origin indexing. |
a0e07ba4 NJ |
5859 | @end deffn |
5860 | ||
5861 | ||
5862 | ||
5863 | @deffn {procedure} string-set! string k char | |
5864 | ||
5865 | ||
5866 | @c \var{String} must be a string, | |
5867 | @var{k} must be a valid index of @var{string} | |
5868 | @c , and \var{char} must be a character | |
5869 | . | |
7fb9c4af | 5870 | @samp{String-set!} stores @var{char} in element @var{k} of @var{string} |
a0e07ba4 NJ |
5871 | and returns an unspecified value. |
5872 | @c <!> | |
5873 | ||
5874 | ||
5875 | @format | |
5876 | @t{(define (f) (make-string 3 #\*)) | |
5877 | (define (g) "***") | |
5878 | (string-set! (f) 0 #\?) ==> @emph{unspecified} | |
5879 | (string-set! (g) 0 #\?) ==> @emph{error} | |
5880 | (string-set! (symbol->string 'immutable) | |
5881 | 0 | |
5882 | #\?) ==> @emph{error} | |
5883 | } | |
5884 | @end format | |
5885 | ||
5886 | ||
5887 | @end deffn | |
5888 | ||
5889 | ||
5890 | ||
5891 | @deffn {library procedure} string=? string1 string2 | |
5892 | @deffnx {library procedure} string-ci=? string1 string2 | |
5893 | ||
5894 | Returns @t{#t} if the two strings are the same length and contain the same | |
5895 | characters in the same positions, otherwise returns @t{#f}. | |
7fb9c4af | 5896 | @samp{String-ci=?} treats |
a0e07ba4 NJ |
5897 | upper and lower case letters as though they were the same character, but |
5898 | @samp{string=?} treats upper and lower case as distinct characters. | |
5899 | ||
5900 | @end deffn | |
5901 | ||
5902 | ||
5903 | ||
5904 | @deffn {library procedure} string<? string1 string2 | |
5905 | @deffnx {library procedure} string>? string1 string2 | |
5906 | @deffnx {library procedure} string<=? string1 string2 | |
5907 | @deffnx {library procedure} string>=? string1 string2 | |
5908 | @deffnx {library procedure} string-ci<? string1 string2 | |
5909 | @deffnx {library procedure} string-ci>? string1 string2 | |
5910 | @deffnx {library procedure} string-ci<=? string1 string2 | |
5911 | @deffnx {library procedure} string-ci>=? string1 string2 | |
5912 | ||
5913 | These procedures are the lexicographic extensions to strings of the | |
5914 | corresponding orderings on characters. For example, @samp{string<?} is | |
5915 | the lexicographic ordering on strings induced by the ordering | |
5916 | @samp{char<?} on characters. If two strings differ in length but | |
5917 | are the same up to the length of the shorter string, the shorter string | |
5918 | is considered to be lexicographically less than the longer string. | |
5919 | ||
5920 | Implementations may generalize these and the @samp{string=?} and | |
5921 | @samp{string-ci=?} procedures to take more than two arguments, as with | |
5922 | the corresponding numerical predicates. | |
5923 | ||
5924 | @end deffn | |
5925 | ||
5926 | ||
5927 | ||
5928 | @deffn {library procedure} substring string start end | |
5929 | ||
7fb9c4af | 5930 | @var{String} must be a string, and @var{start} and @var{end} |
a0e07ba4 NJ |
5931 | must be exact integers satisfying |
5932 | ||
5933 | ||
5934 | @center 0 <= @var{start} <= @var{end} <= @w{@t{(string-length @var{string})@r{.}}} | |
5935 | ||
7fb9c4af | 5936 | @samp{Substring} returns a newly allocated string formed from the characters of |
a0e07ba4 NJ |
5937 | @var{string} beginning with index @var{start} (inclusive) and ending with index |
5938 | @var{end} (exclusive). | |
5939 | @end deffn | |
5940 | ||
5941 | ||
5942 | ||
5943 | @deffn {library procedure} string-append @var{string} @dots{}, | |
5944 | ||
5945 | Returns a newly allocated string whose characters form the concatenation of the | |
5946 | given strings. | |
5947 | ||
5948 | @end deffn | |
5949 | ||
5950 | ||
5951 | ||
5952 | @deffn {library procedure} string->list string | |
5953 | @deffnx {library procedure} list->string list | |
5954 | ||
7fb9c4af AW |
5955 | @samp{String->list} returns a newly allocated list of the |
5956 | characters that make up the given string. @samp{List->string} | |
a0e07ba4 | 5957 | returns a newly allocated string formed from the characters in the list |
7fb9c4af | 5958 | @var{list}, which must be a list of characters. @samp{String->list} |
a0e07ba4 NJ |
5959 | and @samp{list->string} are |
5960 | inverses so far as @samp{equal?} is concerned. | |
5961 | @c Implementations that provide | |
5962 | @c destructive operations on strings should ensure that the result of | |
5963 | @c {\cf list\coerce{}string} is newly allocated. | |
5964 | ||
5965 | @end deffn | |
5966 | ||
5967 | ||
5968 | ||
5969 | @deffn {library procedure} string-copy string | |
5970 | ||
5971 | Returns a newly allocated copy of the given @var{string}. | |
5972 | ||
5973 | @end deffn | |
5974 | ||
5975 | ||
5976 | ||
5977 | @deffn {library procedure} string-fill! string char | |
5978 | ||
5979 | Stores @var{char} in every element of the given @var{string} and returns an | |
5980 | unspecified value. | |
5981 | @c <!> | |
5982 | ||
5983 | @end deffn | |
5984 | ||
5985 | ||
5986 | @node Vectors, , Strings, Other data types | |
5987 | @subsection Vectors | |
5988 | ||
5989 | ||
5990 | ||
ecb87335 | 5991 | Vectors are heterogeneous structures whose elements are indexed |
a0e07ba4 NJ |
5992 | by integers. A vector typically occupies less space than a list |
5993 | of the same length, and the average time required to access a randomly | |
5994 | chosen element is typically less for the vector than for the list. | |
5995 | ||
5996 | The @emph{length} of a vector is the number of elements that it | |
5997 | contains. This number is a non-negative integer that is fixed when the | |
5998 | vector is created. The @emph{valid indexes} of a | |
5999 | @cindex @w{valid indexes} | |
6000 | vector are the exact non-negative integers less than the length of the | |
6001 | vector. The first element in a vector is indexed by zero, and the last | |
6002 | element is indexed by one less than the length of the vector. | |
6003 | ||
6004 | Vectors are written using the notation @t{#(@var{obj} @dots{},)}. | |
6005 | For example, a vector of length 3 containing the number zero in element | |
6006 | 0, the list @samp{(2 2 2 2)} in element 1, and the string @samp{"Anna"} in | |
6007 | element 2 can be written as following: | |
6008 | ||
6009 | ||
6010 | @example | |
6011 | ||
6012 | #(0 (2 2 2 2) "Anna") | |
6013 | ||
6014 | @end example | |
6015 | ||
6016 | ||
6017 | Note that this is the external representation of a vector, not an | |
6018 | expression evaluating to a vector. Like list constants, vector | |
6019 | constants must be quoted: | |
6020 | ||
6021 | ||
6022 | @example | |
6023 | ||
6024 | '#(0 (2 2 2 2) "Anna") | |
6025 | ==> #(0 (2 2 2 2) "Anna") | |
6026 | ||
6027 | @end example | |
6028 | ||
6029 | ||
6030 | @ignore todo | |
6031 | Pitman sez: The visual similarity to lists is bound to be confusing | |
6032 | to some. Elaborate on the distinction. | |
6033 | @end ignore | |
6034 | ||
6035 | ||
6036 | ||
6037 | ||
6038 | @deffn {procedure} vector? obj | |
6039 | ||
6040 | Returns @t{#t} if @var{obj} is a vector, otherwise returns @t{#f}. | |
6041 | @end deffn | |
6042 | ||
6043 | ||
6044 | ||
6045 | @deffn {procedure} make-vector k | |
6046 | @deffnx {procedure} make-vector k fill | |
6047 | ||
6048 | Returns a newly allocated vector of @var{k} elements. If a second | |
6049 | argument is given, then each element is initialized to @var{fill}. | |
6050 | Otherwise the initial contents of each element is unspecified. | |
6051 | ||
6052 | @end deffn | |
6053 | ||
6054 | ||
6055 | ||
6056 | @deffn {library procedure} vector obj @dots{}, | |
6057 | ||
6058 | Returns a newly allocated vector whose elements contain the given | |
6059 | arguments. Analogous to @samp{list}. | |
6060 | ||
6061 | ||
6062 | @format | |
6063 | @t{(vector 'a 'b 'c) ==> #(a b c) | |
6064 | } | |
6065 | @end format | |
6066 | ||
6067 | @end deffn | |
6068 | ||
6069 | ||
6070 | ||
6071 | @deffn {procedure} vector-length vector | |
6072 | ||
6073 | Returns the number of elements in @var{vector} as an exact integer. | |
6074 | @end deffn | |
6075 | ||
6076 | ||
6077 | ||
6078 | @deffn {procedure} vector-ref vector k | |
6079 | ||
6080 | @var{k} must be a valid index of @var{vector}. | |
7fb9c4af | 6081 | @samp{Vector-ref} returns the contents of element @var{k} of |
a0e07ba4 NJ |
6082 | @var{vector}. |
6083 | ||
6084 | ||
6085 | @format | |
6086 | @t{(vector-ref '#(1 1 2 3 5 8 13 21) | |
6087 | 5) | |
6088 | ==> 8 | |
6089 | (vector-ref '#(1 1 2 3 5 8 13 21) | |
6090 | (let ((i (round (* 2 (acos -1))))) | |
6091 | (if (inexact? i) | |
6092 | (inexact->exact i) | |
6093 | i))) | |
6094 | ==> 13 | |
6095 | } | |
6096 | @end format | |
6097 | ||
6098 | @end deffn | |
6099 | ||
6100 | ||
6101 | ||
6102 | @deffn {procedure} vector-set! vector k obj | |
6103 | ||
6104 | @var{k} must be a valid index of @var{vector}. | |
7fb9c4af | 6105 | @samp{Vector-set!} stores @var{obj} in element @var{k} of @var{vector}. |
a0e07ba4 NJ |
6106 | The value returned by @samp{vector-set!} is unspecified. |
6107 | @c <!> | |
6108 | ||
6109 | ||
6110 | @format | |
6111 | @t{(let ((vec (vector 0 '(2 2 2 2) "Anna"))) | |
6112 | (vector-set! vec 1 '("Sue" "Sue")) | |
6113 | vec) | |
6114 | ==> #(0 ("Sue" "Sue") "Anna") | |
6115 | ||
6116 | (vector-set! '#(0 1 2) 1 "doe") | |
6117 | ==> @emph{error} ; constant vector | |
6118 | } | |
6119 | @end format | |
6120 | ||
6121 | @end deffn | |
6122 | ||
6123 | ||
6124 | ||
6125 | @deffn {library procedure} vector->list vector | |
6126 | @deffnx {library procedure} list->vector list | |
6127 | ||
7fb9c4af AW |
6128 | @samp{Vector->list} returns a newly allocated list of the objects contained |
6129 | in the elements of @var{vector}. @samp{List->vector} returns a newly | |
a0e07ba4 NJ |
6130 | created vector initialized to the elements of the list @var{list}. |
6131 | ||
6132 | ||
6133 | @format | |
6134 | @t{(vector->list '#(dah dah didah)) | |
6135 | ==> (dah dah didah) | |
6136 | (list->vector '(dididit dah)) | |
6137 | ==> #(dididit dah) | |
6138 | } | |
6139 | @end format | |
6140 | ||
6141 | @end deffn | |
6142 | ||
6143 | ||
6144 | ||
6145 | @deffn {library procedure} vector-fill! vector fill | |
6146 | ||
6147 | Stores @var{fill} in every element of @var{vector}. | |
6148 | The value returned by @samp{vector-fill!} is unspecified. | |
6149 | @c <!> | |
6150 | ||
6151 | @end deffn | |
6152 | ||
6153 | ||
6154 | @node Control features, Eval, Other data types, Standard procedures | |
6155 | @section Control features | |
6156 | ||
6157 | ||
6158 | ||
6159 | @c Intro flushed; not very a propos any more. | |
6160 | @c Procedures should be discussed somewhere, however. | |
6161 | ||
6162 | This chapter describes various primitive procedures which control the | |
6163 | flow of program execution in special ways. | |
6164 | The @samp{procedure?} predicate is also described here. | |
6165 | ||
6166 | @ignore todo | |
6167 | @t{Procedure?} doesn't belong in a section with the name | |
6168 | ``control features.'' What to do? | |
6169 | @end ignore | |
6170 | ||
6171 | ||
6172 | ||
6173 | @deffn {procedure} procedure? obj | |
6174 | ||
6175 | Returns @t{#t} if @var{obj} is a procedure, otherwise returns @t{#f}. | |
6176 | ||
6177 | ||
6178 | @format | |
6179 | @t{(procedure? car) ==> #t | |
6180 | (procedure? 'car) ==> #f | |
6181 | (procedure? (lambda (x) (* x x))) | |
6182 | ==> #t | |
6183 | (procedure? '(lambda (x) (* x x))) | |
6184 | ==> #f | |
6185 | (call-with-current-continuation procedure?) | |
6186 | ==> #t | |
6187 | } | |
6188 | @end format | |
6189 | ||
6190 | ||
6191 | @end deffn | |
6192 | ||
6193 | ||
6194 | ||
6195 | @deffn {procedure} apply proc arg1 @dots{} args | |
6196 | ||
7fb9c4af | 6197 | @var{Proc} must be a procedure and @var{args} must be a list. |
a0e07ba4 NJ |
6198 | Calls @var{proc} with the elements of the list |
6199 | @samp{(append (list @var{arg1} @dots{},) @var{args})} as the actual | |
6200 | arguments. | |
6201 | ||
6202 | ||
6203 | @format | |
6204 | @t{(apply + (list 3 4)) ==> 7 | |
6205 | ||
6206 | (define compose | |
6207 | (lambda (f g) | |
6208 | (lambda args | |
6209 | (f (apply g args))))) | |
6210 | ||
6211 | ((compose sqrt *) 12 75) ==> 30 | |
6212 | } | |
6213 | @end format | |
6214 | ||
6215 | @end deffn | |
6216 | ||
6217 | ||
6218 | ||
7fb9c4af | 6219 | @deffn {library procedure} map proc list1 list2 @dots{}, |
a0e07ba4 NJ |
6220 | |
6221 | The @var{list}s must be lists, and @var{proc} must be a | |
6222 | procedure taking as many arguments as there are @i{list}s | |
6223 | and returning a single value. If more | |
6224 | than one @var{list} is given, then they must all be the same length. | |
7fb9c4af | 6225 | @samp{Map} applies @var{proc} element-wise to the elements of the |
a0e07ba4 NJ |
6226 | @var{list}s and returns a list of the results, in order. |
6227 | The dynamic order in which @var{proc} is applied to the elements of the | |
6228 | @var{list}s is unspecified. | |
6229 | ||
6230 | ||
6231 | @format | |
6232 | @t{(map cadr '((a b) (d e) (g h))) | |
6233 | ==> (b e h) | |
6234 | ||
6235 | (map (lambda (n) (expt n n)) | |
6236 | '(1 2 3 4 5)) | |
6237 | ==> (1 4 27 256 3125) | |
6238 | ||
6239 | (map + '(1 2 3) '(4 5 6)) ==> (5 7 9) | |
6240 | ||
6241 | (let ((count 0)) | |
6242 | (map (lambda (ignored) | |
6243 | (set! count (+ count 1)) | |
6244 | count) | |
6245 | '(a b))) ==> (1 2) @var{or} (2 1) | |
6246 | } | |
6247 | @end format | |
6248 | ||
6249 | ||
6250 | @end deffn | |
6251 | ||
6252 | ||
6253 | ||
6254 | @deffn {library procedure} for-each proc list1 list2 @dots{}, | |
6255 | ||
6256 | The arguments to @samp{for-each} are like the arguments to @samp{map}, but | |
6257 | @samp{for-each} calls @var{proc} for its side effects rather than for its | |
6258 | values. Unlike @samp{map}, @samp{for-each} is guaranteed to call @var{proc} on | |
6259 | the elements of the @var{list}s in order from the first element(s) to the | |
6260 | last, and the value returned by @samp{for-each} is unspecified. | |
6261 | ||
6262 | ||
6263 | @format | |
6264 | @t{(let ((v (make-vector 5))) | |
6265 | (for-each (lambda (i) | |
6266 | (vector-set! v i (* i i))) | |
6267 | '(0 1 2 3 4)) | |
6268 | v) ==> #(0 1 4 9 16) | |
6269 | } | |
6270 | @end format | |
6271 | ||
6272 | ||
6273 | @end deffn | |
6274 | ||
6275 | ||
6276 | ||
6277 | @deffn {library procedure} force promise | |
6278 | ||
6279 | Forces the value of @var{promise} (see @code{delay}, | |
6280 | @vindex @w{delay} | |
6281 | section @pxref{Delayed evaluation}). If no value has been computed for | |
6282 | @cindex @w{promise} | |
6283 | the promise, then a value is computed and returned. The value of the | |
6284 | promise is cached (or ``memoized'') so that if it is forced a second | |
6285 | time, the previously computed value is returned. | |
6286 | @c without any recomputation. | |
6287 | @c [As pointed out by Marc Feeley, the "without any recomputation" | |
6288 | @c isn't necessarily true. --Will] | |
6289 | ||
6290 | ||
6291 | @format | |
6292 | @t{(force (delay (+ 1 2))) ==> 3 | |
6293 | (let ((p (delay (+ 1 2)))) | |
6294 | (list (force p) (force p))) | |
6295 | ==> (3 3) | |
6296 | ||
6297 | (define a-stream | |
6298 | (letrec ((next | |
6299 | (lambda (n) | |
6300 | (cons n (delay (next (+ n 1))))))) | |
6301 | (next 0))) | |
6302 | (define head car) | |
6303 | (define tail | |
6304 | (lambda (stream) (force (cdr stream)))) | |
6305 | ||
6306 | (head (tail (tail a-stream))) | |
6307 | ==> 2 | |
6308 | } | |
6309 | @end format | |
6310 | ||
6311 | ||
7fb9c4af | 6312 | @samp{Force} and @samp{delay} are mainly intended for programs written in |
a0e07ba4 NJ |
6313 | functional style. The following examples should not be considered to |
6314 | illustrate good programming style, but they illustrate the property that | |
6315 | only one value is computed for a promise, no matter how many times it is | |
6316 | forced. | |
6317 | @c the value of a promise is computed at most once. | |
6318 | @c [As pointed out by Marc Feeley, it may be computed more than once, | |
6319 | @c but as I observed we can at least insist that only one value be | |
6320 | @c used! -- Will] | |
6321 | ||
6322 | ||
6323 | @format | |
6324 | @t{(define count 0) | |
6325 | (define p | |
6326 | (delay (begin (set! count (+ count 1)) | |
6327 | (if (> count x) | |
6328 | count | |
6329 | (force p))))) | |
6330 | (define x 5) | |
6331 | p ==> @i{}a promise | |
6332 | (force p) ==> 6 | |
6333 | p ==> @i{}a promise, still | |
6334 | (begin (set! x 10) | |
6335 | (force p)) ==> 6 | |
6336 | } | |
6337 | @end format | |
6338 | ||
6339 | ||
6340 | Here is a possible implementation of @samp{delay} and @samp{force}. | |
6341 | Promises are implemented here as procedures of no arguments, | |
6342 | and @samp{force} simply calls its argument: | |
6343 | ||
6344 | ||
6345 | @format | |
6346 | @t{(define force | |
6347 | (lambda (object) | |
6348 | (object))) | |
6349 | } | |
6350 | @end format | |
6351 | ||
6352 | ||
6353 | We define the expression | |
6354 | ||
6355 | ||
6356 | @format | |
6357 | @t{(delay @r{<expression>}) | |
6358 | } | |
6359 | @end format | |
6360 | ||
6361 | ||
6362 | to have the same meaning as the procedure call | |
6363 | ||
6364 | ||
6365 | @format | |
6366 | @t{(make-promise (lambda () @r{<expression>}))@r{} | |
6367 | } | |
6368 | @end format | |
6369 | ||
6370 | ||
6371 | as follows | |
6372 | ||
6373 | ||
6374 | @format | |
6375 | @t{(define-syntax delay | |
6376 | (syntax-rules () | |
6377 | ((delay expression) | |
6378 | (make-promise (lambda () expression))))), | |
6379 | } | |
6380 | @end format | |
6381 | ||
6382 | ||
6383 | where @samp{make-promise} is defined as follows: | |
6384 | ||
6385 | @c \begin{scheme} | |
6386 | @c (define make-promise | |
6387 | @c (lambda (proc) | |
6388 | @c (let ((already-run? \schfalse) (result \schfalse)) | |
6389 | @c (lambda () | |
6390 | @c (cond ((not already-run?) | |
6391 | @c (set! result (proc)) | |
6392 | @c (set! already-run? \schtrue))) | |
6393 | @c result))))% | |
6394 | @c \end{scheme} | |
6395 | ||
6396 | ||
6397 | @format | |
6398 | @t{(define make-promise | |
6399 | (lambda (proc) | |
6400 | (let ((result-ready? #f) | |
6401 | (result #f)) | |
6402 | (lambda () | |
6403 | (if result-ready? | |
6404 | result | |
6405 | (let ((x (proc))) | |
6406 | (if result-ready? | |
6407 | result | |
6408 | (begin (set! result-ready? #t) | |
6409 | (set! result x) | |
6410 | result)))))))) | |
6411 | } | |
6412 | @end format | |
6413 | ||
6414 | ||
6415 | ||
6416 | @quotation | |
6417 | @emph{Rationale:} | |
6418 | A promise may refer to its own value, as in the last example above. | |
6419 | Forcing such a promise may cause the promise to be forced a second time | |
6420 | before the value of the first force has been computed. | |
6421 | This complicates the definition of @samp{make-promise}. | |
6422 | @end quotation | |
6423 | ||
6424 | ||
6425 | Various extensions to this semantics of @samp{delay} and @samp{force} | |
6426 | are supported in some implementations: | |
6427 | ||
6428 | ||
6429 | ||
6430 | @itemize @bullet | |
6431 | ||
6432 | @item | |
6433 | Calling @samp{force} on an object that is not a promise may simply | |
6434 | return the object. | |
6435 | ||
6436 | @item | |
6437 | It may be the case that there is no means by which a promise can be | |
6438 | operationally distinguished from its forced value. That is, expressions | |
6439 | like the following may evaluate to either @t{#t} or to @t{#f}, | |
6440 | depending on the implementation: | |
6441 | ||
6442 | ||
6443 | @format | |
6444 | @t{(eqv? (delay 1) 1) ==> @emph{unspecified} | |
6445 | (pair? (delay (cons 1 2))) ==> @emph{unspecified} | |
6446 | } | |
6447 | @end format | |
6448 | ||
6449 | ||
6450 | @item | |
6451 | Some implementations may implement ``implicit forcing,'' where | |
6452 | the value of a promise is forced by primitive procedures like @samp{cdr} | |
6453 | and @samp{+}: | |
6454 | ||
6455 | ||
6456 | @format | |
6457 | @t{(+ (delay (* 3 7)) 13) ==> 34 | |
6458 | } | |
6459 | @end format | |
6460 | ||
6461 | ||
6462 | @end itemize | |
6463 | ||
6464 | @end deffn | |
6465 | ||
6466 | ||
6467 | @deffn {procedure} call-with-current-continuation proc | |
6468 | ||
7fb9c4af | 6469 | @var{Proc} must be a procedure of one |
a0e07ba4 NJ |
6470 | argument. The procedure @samp{call-with-current-continuation} packages |
6471 | up the current continuation (see the rationale below) as an ``escape | |
6472 | procedure'' and passes it as an argument to | |
6473 | @cindex @w{escape procedure} | |
6474 | @var{proc}. The escape procedure is a Scheme procedure that, if it is | |
6475 | later called, will abandon whatever continuation is in effect at that later | |
6476 | time and will instead use the continuation that was in effect | |
6477 | when the escape procedure was created. Calling the escape procedure | |
6478 | may cause the invocation of @var{before} and @var{after} thunks installed using | |
6479 | @code{dynamic-wind}. | |
6480 | @vindex @w{dynamic-wind} | |
6481 | ||
6482 | The escape procedure accepts the same number of arguments as the continuation to | |
6483 | the original call to @t{call-with-current-continuation}. | |
6484 | Except for continuations created by the @samp{call-with-values} | |
6485 | procedure, all continuations take exactly one value. The | |
6486 | effect of passing no value or more than one value to continuations | |
6487 | that were not created by @t{call-with-values} is unspecified. | |
6488 | ||
6489 | The escape procedure that is passed to @var{proc} has | |
6490 | unlimited extent just like any other procedure in Scheme. It may be stored | |
6491 | in variables or data structures and may be called as many times as desired. | |
6492 | ||
6493 | The following examples show only the most common ways in which | |
6494 | @samp{call-with-current-continuation} is used. If all real uses were as | |
6495 | simple as these examples, there would be no need for a procedure with | |
6496 | the power of @samp{call-with-current-continuation}. | |
6497 | ||
6498 | ||
6499 | @format | |
6500 | @t{(call-with-current-continuation | |
6501 | (lambda (exit) | |
6502 | (for-each (lambda (x) | |
6503 | (if (negative? x) | |
6504 | (exit x))) | |
6505 | '(54 0 37 -3 245 19)) | |
6506 | #t)) ==> -3 | |
6507 | ||
6508 | (define list-length | |
6509 | (lambda (obj) | |
6510 | (call-with-current-continuation | |
6511 | (lambda (return) | |
6512 | (letrec ((r | |
6513 | (lambda (obj) | |
6514 | (cond ((null? obj) 0) | |
6515 | ((pair? obj) | |
6516 | (+ (r (cdr obj)) 1)) | |
6517 | (else (return #f)))))) | |
6518 | (r obj)))))) | |
6519 | ||
6520 | (list-length '(1 2 3 4)) ==> 4 | |
6521 | ||
6522 | (list-length '(a b . c)) ==> #f | |
6523 | } | |
6524 | @end format | |
6525 | ||
6526 | ||
6527 | ||
6528 | @quotation | |
6529 | @emph{Rationale:} | |
6530 | ||
6531 | A common use of @samp{call-with-current-continuation} is for | |
6532 | structured, non-local exits from loops or procedure bodies, but in fact | |
6533 | @samp{call-with-current-continuation} is extremely useful for implementing a | |
6534 | wide variety of advanced control structures. | |
6535 | ||
6536 | Whenever a Scheme expression is evaluated there is a | |
6537 | @dfn{continuation} wanting the result of the expression. The continuation | |
6538 | @cindex @w{continuation} | |
6539 | represents an entire (default) future for the computation. If the expression is | |
6540 | evaluated at top level, for example, then the continuation might take the | |
6541 | result, print it on the screen, prompt for the next input, evaluate it, and | |
6542 | so on forever. Most of the time the continuation includes actions | |
6543 | specified by user code, as in a continuation that will take the result, | |
6544 | multiply it by the value stored in a local variable, add seven, and give | |
6545 | the answer to the top level continuation to be printed. Normally these | |
6546 | ubiquitous continuations are hidden behind the scenes and programmers do not | |
6547 | think much about them. On rare occasions, however, a programmer may | |
6548 | need to deal with continuations explicitly. | |
7fb9c4af | 6549 | @samp{Call-with-current-continuation} allows Scheme programmers to do |
a0e07ba4 NJ |
6550 | that by creating a procedure that acts just like the current |
6551 | continuation. | |
6552 | ||
6553 | Most programming languages incorporate one or more special-purpose | |
6554 | escape constructs with names like @t{exit}, @w{@samp{return}}, or | |
6555 | even @t{goto}. In 1965, however, Peter Landin [Landin65] | |
6556 | invented a general purpose escape operator called the J-operator. John | |
6557 | Reynolds [Reynolds72] described a simpler but equally powerful | |
6558 | construct in 1972. The @samp{catch} special form described by Sussman | |
6559 | and Steele in the 1975 report on Scheme is exactly the same as | |
6560 | Reynolds's construct, though its name came from a less general construct | |
6561 | in MacLisp. Several Scheme implementors noticed that the full power of the | |
6562 | @code{catch} construct could be provided by a procedure instead of by a | |
6563 | @vindex @w{catch} | |
6564 | special syntactic construct, and the name | |
6565 | @samp{call-with-current-continuation} was coined in 1982. This name is | |
6566 | descriptive, but opinions differ on the merits of such a long name, and | |
6567 | some people use the name @code{call/cc} instead. | |
6568 | @vindex @w{call/cc} | |
6569 | @end quotation | |
6570 | ||
6571 | ||
6572 | @end deffn | |
6573 | ||
6574 | ||
6575 | @deffn {procedure} values obj @dots{} | |
6576 | ||
6577 | Delivers all of its arguments to its continuation. | |
6578 | Except for continuations created by the @code{call-with-values} | |
6579 | @vindex @w{call-with-values} | |
6580 | procedure, all continuations take exactly one value. | |
6581 | @t{Values} might be defined as follows: | |
6582 | ||
6583 | @format | |
6584 | @t{(define (values . things) | |
6585 | (call-with-current-continuation | |
6586 | (lambda (cont) (apply cont things)))) | |
6587 | } | |
6588 | @end format | |
6589 | ||
6590 | ||
6591 | @end deffn | |
6592 | ||
6593 | ||
6594 | @deffn {procedure} call-with-values producer consumer | |
6595 | ||
6596 | Calls its @var{producer} argument with no values and | |
6597 | a continuation that, when passed some values, calls the | |
6598 | @var{consumer} procedure with those values as arguments. | |
6599 | The continuation for the call to @var{consumer} is the | |
6600 | continuation of the call to @t{call-with-values}. | |
6601 | ||
6602 | ||
6603 | @format | |
6604 | @t{(call-with-values (lambda () (values 4 5)) | |
6605 | (lambda (a b) b)) | |
6606 | ==> 5 | |
6607 | ||
6608 | (call-with-values * -) ==> -1 | |
6609 | } | |
6610 | @end format | |
6611 | ||
6612 | ||
6613 | @end deffn | |
6614 | ||
6615 | ||
6616 | @deffn {procedure} dynamic-wind before thunk after | |
6617 | ||
6618 | Calls @var{thunk} without arguments, returning the result(s) of this call. | |
7fb9c4af | 6619 | @var{Before} and @var{after} are called, also without arguments, as required |
a0e07ba4 NJ |
6620 | by the following rules (note that in the absence of calls to continuations |
6621 | captured using @code{call-with-current-continuation} the three arguments are | |
6622 | @vindex @w{call-with-current-continuation} | |
7fb9c4af | 6623 | called once each, in order). @var{Before} is called whenever execution |
a0e07ba4 NJ |
6624 | enters the dynamic extent of the call to @var{thunk} and @var{after} is called |
6625 | whenever it exits that dynamic extent. The dynamic extent of a procedure | |
6626 | call is the period between when the call is initiated and when it | |
6627 | returns. In Scheme, because of @samp{call-with-current-continuation}, the | |
6628 | dynamic extent of a call may not be a single, connected time period. | |
6629 | It is defined as follows: | |
6630 | ||
6631 | ||
6632 | @itemize @bullet | |
6633 | ||
6634 | @item | |
6635 | The dynamic extent is entered when execution of the body of the | |
6636 | called procedure begins. | |
6637 | ||
6638 | @item | |
6639 | The dynamic extent is also entered when execution is not within | |
6640 | the dynamic extent and a continuation is invoked that was captured | |
6641 | (using @samp{call-with-current-continuation}) during the dynamic extent. | |
6642 | ||
6643 | @item | |
6644 | It is exited when the called procedure returns. | |
6645 | ||
6646 | @item | |
6647 | It is also exited when execution is within the dynamic extent and | |
6648 | a continuation is invoked that was captured while not within the | |
6649 | dynamic extent. | |
6650 | ||
6651 | @end itemize | |
6652 | ||
6653 | ||
6654 | If a second call to @samp{dynamic-wind} occurs within the dynamic extent of the | |
6655 | call to @var{thunk} and then a continuation is invoked in such a way that the | |
6656 | @var{after}s from these two invocations of @samp{dynamic-wind} are both to be | |
6657 | called, then the @var{after} associated with the second (inner) call to | |
6658 | @samp{dynamic-wind} is called first. | |
6659 | ||
6660 | If a second call to @samp{dynamic-wind} occurs within the dynamic extent of the | |
6661 | call to @var{thunk} and then a continuation is invoked in such a way that the | |
6662 | @var{before}s from these two invocations of @samp{dynamic-wind} are both to be | |
6663 | called, then the @var{before} associated with the first (outer) call to | |
6664 | @samp{dynamic-wind} is called first. | |
6665 | ||
6666 | If invoking a continuation requires calling the @var{before} from one call | |
6667 | to @samp{dynamic-wind} and the @var{after} from another, then the @var{after} | |
6668 | is called first. | |
6669 | ||
6670 | The effect of using a captured continuation to enter or exit the dynamic | |
6671 | extent of a call to @var{before} or @var{after} is undefined. | |
6672 | ||
6673 | ||
6674 | @format | |
6675 | @t{(let ((path '()) | |
6676 | (c #f)) | |
6677 | (let ((add (lambda (s) | |
6678 | (set! path (cons s path))))) | |
6679 | (dynamic-wind | |
6680 | (lambda () (add 'connect)) | |
6681 | (lambda () | |
6682 | (add (call-with-current-continuation | |
6683 | (lambda (c0) | |
6684 | (set! c c0) | |
6685 | 'talk1)))) | |
6686 | (lambda () (add 'disconnect))) | |
6687 | (if (< (length path) 4) | |
6688 | (c 'talk2) | |
6689 | (reverse path)))) | |
6690 | ||
6691 | ==> (connect talk1 disconnect | |
6692 | connect talk2 disconnect) | |
6693 | } | |
6694 | @end format | |
6695 | ||
6696 | @end deffn | |
6697 | ||
6698 | @node Eval, Input and output, Control features, Standard procedures | |
6699 | @section Eval | |
6700 | ||
6701 | ||
6702 | ||
6703 | @deffn {procedure} eval expression environment-specifier | |
6704 | ||
6705 | Evaluates @var{expression} in the specified environment and returns its value. | |
7fb9c4af | 6706 | @var{Expression} must be a valid Scheme expression represented as data, |
a0e07ba4 NJ |
6707 | and @var{environment-specifier} must be a value returned by one of the |
6708 | three procedures described below. | |
6709 | Implementations may extend @samp{eval} to allow non-expression programs | |
6710 | (definitions) as the first argument and to allow other | |
6711 | values as environments, with the restriction that @samp{eval} is not | |
6712 | allowed to create new bindings in the environments associated with | |
6713 | @samp{null-environment} or @samp{scheme-report-environment}. | |
6714 | ||
6715 | ||
6716 | @format | |
6717 | @t{(eval '(* 7 3) (scheme-report-environment 5)) | |
6718 | ==> 21 | |
6719 | ||
6720 | (let ((f (eval '(lambda (f x) (f x x)) | |
6721 | (null-environment 5)))) | |
6722 | (f + 10)) | |
6723 | ==> 20 | |
6724 | } | |
6725 | @end format | |
6726 | ||
6727 | ||
6728 | @end deffn | |
6729 | ||
6730 | ||
6731 | @deffn {procedure} scheme-report-environment version | |
6732 | @deffnx {procedure} null-environment version | |
6733 | ||
7fb9c4af | 6734 | @var{Version} must be the exact integer @samp{5}, |
a0e07ba4 NJ |
6735 | corresponding to this revision of the Scheme report (the |
6736 | Revised^5 Report on Scheme). | |
7fb9c4af | 6737 | @samp{Scheme-report-environment} returns a specifier for an |
a0e07ba4 NJ |
6738 | environment that is empty except for all bindings defined in |
6739 | this report that are either required or both optional and | |
7fb9c4af | 6740 | supported by the implementation. @samp{Null-environment} returns |
a0e07ba4 NJ |
6741 | a specifier for an environment that is empty except for the |
6742 | (syntactic) bindings for all syntactic keywords defined in | |
6743 | this report that are either required or both optional and | |
6744 | supported by the implementation. | |
6745 | ||
6746 | Other values of @var{version} can be used to specify environments | |
6747 | matching past revisions of this report, but their support is not | |
6748 | required. An implementation will signal an error if @var{version} | |
6749 | is neither @samp{5} nor another value supported by | |
6750 | the implementation. | |
6751 | ||
6752 | The effect of assigning (through the use of @samp{eval}) a variable | |
6753 | bound in a @samp{scheme-report-environment} | |
6754 | (for example @samp{car}) is unspecified. Thus the environments specified | |
6755 | by @samp{scheme-report-environment} may be immutable. | |
6756 | ||
6757 | @end deffn | |
6758 | ||
6759 | ||
6760 | @deffn {optional procedure} interaction-environment | |
6761 | ||
6762 | This procedure returns a specifier for the environment that | |
6763 | contains imple@-men@-ta@-tion-defined bindings, typically a superset of | |
6764 | those listed in the report. The intent is that this procedure | |
6765 | will return the environment in which the implementation would evaluate | |
6766 | expressions dynamically typed by the user. | |
6767 | ||
6768 | @end deffn | |
6769 | ||
6770 | @node Input and output, , Eval, Standard procedures | |
6771 | @section Input and output | |
6772 | ||
6773 | @menu | |
6774 | * Ports:: | |
6775 | * Input:: | |
6776 | * Output:: | |
6777 | * System interface:: | |
6778 | @end menu | |
6779 | ||
6780 | ||
6781 | @node Ports, Input, Input and output, Input and output | |
6782 | @subsection Ports | |
6783 | ||
6784 | ||
6785 | ||
6786 | Ports represent input and output devices. To Scheme, an input port is a | |
6787 | Scheme object that can deliver characters upon command, while an output port | |
6788 | is a Scheme object that can accept characters. | |
6789 | @cindex @w{port} | |
6790 | ||
6791 | @ignore todo | |
6792 | Haase: Mention that there are alternatives to files? | |
6793 | @end ignore | |
6794 | ||
6795 | ||
6796 | ||
6797 | @deffn {library procedure} call-with-input-file string proc | |
6798 | @deffnx {library procedure} call-with-output-file string proc | |
6799 | ||
7fb9c4af | 6800 | @var{String} should be a string naming a file, and |
a0e07ba4 NJ |
6801 | @var{proc} should be a procedure that accepts one argument. |
6802 | For @samp{call-with-input-file}, | |
6803 | the file should already exist; for | |
6804 | @samp{call-with-output-file}, | |
6805 | the effect is unspecified if the file | |
6806 | already exists. These procedures call @var{proc} with one argument: the | |
6807 | port obtained by opening the named file for input or output. If the | |
6808 | file cannot be opened, an error is signalled. If @var{proc} returns, | |
6809 | then the port is closed automatically and the value(s) yielded by the | |
6810 | @var{proc} is(are) returned. If @var{proc} does not return, then | |
6811 | the port will not be closed automatically unless it is possible to | |
6812 | prove that the port will never again be used for a read or write | |
6813 | operation. | |
6814 | @c Scheme | |
6815 | @c will not close the port unless it can prove that the port will never | |
6816 | @c again be used for a read or write operation. | |
6817 | ||
6818 | ||
6819 | @quotation | |
6820 | @emph{Rationale:} | |
6821 | Because Scheme's escape procedures have unlimited extent, it is | |
6822 | possible to escape from the current continuation but later to escape back in. | |
6823 | If implementations were permitted to close the port on any escape from the | |
6824 | current continuation, then it would be impossible to write portable code using | |
6825 | both @samp{call-with-current-continuation} and @samp{call-with-input-file} or | |
6826 | @samp{call-with-output-file}. | |
6827 | @ignore todo | |
6828 | Pitman wants more said here; maybe encourage users to call | |
6829 | @var{close-foo-port}; maybe talk about process switches (?). | |
6830 | @end ignore | |
6831 | ||
6832 | @end quotation | |
6833 | ||
6834 | @end deffn | |
6835 | ||
6836 | ||
6837 | ||
6838 | @deffn {procedure} input-port? obj | |
6839 | @deffnx {procedure} output-port? obj | |
6840 | ||
6841 | Returns @t{#t} if @var{obj} is an input port or output port | |
6842 | respectively, otherwise returns @t{#f}. | |
6843 | ||
6844 | @ignore todo | |
6845 | Won't necessarily return true after port is closed. | |
6846 | @end ignore | |
6847 | ||
6848 | ||
6849 | @end deffn | |
6850 | ||
6851 | ||
6852 | ||
6853 | @deffn {procedure} current-input-port | |
6854 | @deffnx {procedure} current-output-port | |
6855 | ||
6856 | Returns the current default input or output port. | |
6857 | ||
6858 | @end deffn | |
6859 | ||
6860 | ||
6861 | ||
6862 | @deffn {optional procedure} with-input-from-file string thunk | |
6863 | @deffnx {optional procedure} with-output-to-file string thunk | |
6864 | ||
7fb9c4af AW |
6865 | @var{String} should be a string naming a file, and |
6866 | @var{proc} should be a procedure of no arguments. | |
a0e07ba4 NJ |
6867 | For @samp{with-input-from-file}, |
6868 | the file should already exist; for | |
6869 | @samp{with-output-to-file}, | |
6870 | the effect is unspecified if the file | |
6871 | already exists. | |
6872 | The file is opened for input or output, an input or output port | |
6873 | connected to it is made the default value returned by | |
6874 | @samp{current-input-port} or @samp{current-output-port} | |
6875 | (and is used by @t{(read)}, @t{(write @var{obj})}, and so forth), | |
6876 | and the | |
6877 | @var{thunk} is called with no arguments. When the @var{thunk} returns, | |
6878 | the port is closed and the previous default is restored. | |
7fb9c4af | 6879 | @samp{With-input-from-file} and @samp{with-output-to-file} return(s) the |
a0e07ba4 NJ |
6880 | value(s) yielded by @var{thunk}. |
6881 | If an escape procedure | |
6882 | is used to escape from the continuation of these procedures, their | |
6883 | behavior is implementation dependent. | |
6884 | ||
6885 | @ignore todo | |
6886 | OK this with authors?? | |
6887 | @end ignore | |
6888 | ||
6889 | @c current continuation changes in such a way | |
6890 | @c as to make it doubtful that the \var{thunk} will ever return. | |
6891 | ||
6892 | @ignore todo | |
6893 | Freeman: | |
6894 | Throughout this section I wanted to see ``the value of @t{(current-input-port)}'' | |
6895 | instead of ``the value returned by @var{current-input-port}''. (Same for | |
6896 | @var{current-output-port}.) | |
6897 | @end ignore | |
6898 | ||
6899 | ||
6900 | ||
6901 | @end deffn | |
6902 | ||
6903 | ||
6904 | ||
6905 | @deffn {procedure} open-input-file filename | |
6906 | ||
6907 | Takes a string naming an existing file and returns an input port capable of | |
6908 | delivering characters from the file. If the file cannot be opened, an error is | |
6909 | signalled. | |
6910 | ||
6911 | @end deffn | |
6912 | ||
6913 | ||
6914 | ||
6915 | @deffn {procedure} open-output-file filename | |
6916 | ||
6917 | Takes a string naming an output file to be created and returns an output | |
6918 | port capable of writing characters to a new file by that name. If the file | |
6919 | cannot be opened, an error is signalled. If a file with the given name | |
6920 | already exists, the effect is unspecified. | |
6921 | ||
6922 | @end deffn | |
6923 | ||
6924 | ||
6925 | ||
6926 | @deffn {procedure} close-input-port port | |
6927 | @deffnx {procedure} close-output-port port | |
6928 | ||
6929 | Closes the file associated with @var{port}, rendering the @var{port} | |
6930 | incapable of delivering or accepting characters. | |
6931 | @ignore todo | |
6932 | But maybe a no-op | |
6933 | on some ports, e.g. terminals or editor buffers. | |
6934 | @end ignore | |
6935 | ||
6936 | These routines have no effect if the file has already been closed. | |
6937 | The value returned is unspecified. | |
6938 | ||
6939 | @ignore todo | |
6940 | Ramsdell: Some note is needed explaining why there are two | |
6941 | different close procedures. | |
6942 | @end ignore | |
6943 | ||
6944 | ||
6945 | @ignore todo | |
6946 | A port isn't necessarily still a port after it has been closed? | |
6947 | @end ignore | |
6948 | ||
6949 | ||
6950 | @end deffn | |
6951 | ||
6952 | ||
6953 | @node Input, Output, Ports, Input and output | |
6954 | @subsection Input | |
6955 | ||
6956 | ||
6957 | ||
6958 | ||
6959 | @noindent | |
6960 | @w{ } | |
6961 | @c ??? | |
6962 | @sp 5 | |
6963 | @ignore todo | |
6964 | The input routines have some things in common, maybe explain here. | |
6965 | @end ignore | |
6966 | ||
6967 | ||
6968 | ||
6969 | @deffn {library procedure} read | |
6970 | @deffnx {library procedure} read port | |
6971 | ||
7fb9c4af | 6972 | @samp{Read} converts external representations of Scheme objects into the |
a0e07ba4 NJ |
6973 | objects themselves. That is, it is a parser for the nonterminal |
6974 | <datum> (see sections @pxref{External representation} and | |
7fb9c4af | 6975 | @pxref{Pairs and lists}). @samp{Read} returns the next |
a0e07ba4 NJ |
6976 | object parsable from the given input @var{port}, updating @var{port} to point to |
6977 | the first character past the end of the external representation of the object. | |
6978 | ||
6979 | If an end of file is encountered in the input before any | |
6980 | characters are found that can begin an object, then an end of file | |
6981 | object is returned. | |
6982 | @ignore todo | |
6983 | ||
6984 | @end ignore | |
6985 | The port remains open, and further attempts | |
6986 | to read will also return an end of file object. If an end of file is | |
6987 | encountered after the beginning of an object's external representation, | |
6988 | but the external representation is incomplete and therefore not parsable, | |
6989 | an error is signalled. | |
6990 | ||
6991 | The @var{port} argument may be omitted, in which case it defaults to the | |
6992 | value returned by @samp{current-input-port}. It is an error to read from | |
6993 | a closed port. | |
6994 | @end deffn | |
6995 | ||
6996 | ||
6997 | @deffn {procedure} read-char | |
6998 | @deffnx {procedure} read-char port | |
6999 | ||
7000 | Returns the next character available from the input @var{port}, updating | |
7001 | the @var{port} to point to the following character. If no more characters | |
7fb9c4af | 7002 | are available, an end of file object is returned. @var{Port} may be |
a0e07ba4 NJ |
7003 | omitted, in which case it defaults to the value returned by @samp{current-input-port}. |
7004 | ||
7005 | @end deffn | |
7006 | ||
7007 | ||
7008 | ||
7009 | @deffn {procedure} peek-char | |
7010 | @deffnx {procedure} peek-char port | |
7011 | ||
7012 | Returns the next character available from the input @var{port}, | |
7013 | @emph{without} updating | |
7014 | the @var{port} to point to the following character. If no more characters | |
7fb9c4af | 7015 | are available, an end of file object is returned. @var{Port} may be |
a0e07ba4 NJ |
7016 | omitted, in which case it defaults to the value returned by @samp{current-input-port}. |
7017 | ||
7018 | ||
7019 | @quotation | |
7020 | @emph{Note:} | |
7021 | The value returned by a call to @samp{peek-char} is the same as the | |
7022 | value that would have been returned by a call to @samp{read-char} with the | |
7023 | same @var{port}. The only difference is that the very next call to | |
7024 | @samp{read-char} or @samp{peek-char} on that @var{port} will return the | |
7025 | value returned by the preceding call to @samp{peek-char}. In particular, a call | |
7026 | to @samp{peek-char} on an interactive port will hang waiting for input | |
7027 | whenever a call to @samp{read-char} would have hung. | |
7028 | @end quotation | |
7029 | ||
7030 | ||
7031 | @end deffn | |
7032 | ||
7033 | ||
7034 | ||
7035 | @deffn {procedure} eof-object? obj | |
7036 | ||
7037 | Returns @t{#t} if @var{obj} is an end of file object, otherwise returns | |
7038 | @t{#f}. The precise set of end of file objects will vary among | |
7039 | implementations, but in any case no end of file object will ever be an object | |
7040 | that can be read in using @samp{read}. | |
7041 | ||
7042 | @end deffn | |
7043 | ||
7044 | ||
7045 | ||
7046 | @deffn {procedure} char-ready? | |
7047 | @deffnx {procedure} char-ready? port | |
7048 | ||
7049 | Returns @t{#t} if a character is ready on the input @var{port} and | |
7050 | returns @t{#f} otherwise. If @samp{char-ready} returns @t{#t} then | |
7051 | the next @samp{read-char} operation on the given @var{port} is guaranteed | |
7052 | not to hang. If the @var{port} is at end of file then @samp{char-ready?} | |
7fb9c4af | 7053 | returns @t{#t}. @var{Port} may be omitted, in which case it defaults to |
a0e07ba4 NJ |
7054 | the value returned by @samp{current-input-port}. |
7055 | ||
7056 | ||
7057 | @quotation | |
7058 | @emph{Rationale:} | |
7fb9c4af | 7059 | @samp{Char-ready?} exists to make it possible for a program to |
a0e07ba4 NJ |
7060 | accept characters from interactive ports without getting stuck waiting for |
7061 | input. Any input editors associated with such ports must ensure that | |
7062 | characters whose existence has been asserted by @samp{char-ready?} cannot | |
7063 | be rubbed out. If @samp{char-ready?} were to return @t{#f} at end of | |
7064 | file, a port at end of file would be indistinguishable from an interactive | |
7065 | port that has no ready characters. | |
7066 | @end quotation | |
7067 | ||
7068 | @end deffn | |
7069 | ||
7070 | ||
7071 | @node Output, System interface, Input, Input and output | |
7072 | @subsection Output | |
7073 | ||
7074 | ||
7075 | ||
7076 | @c We've got to put something here to fix the indentation!! | |
7077 | ||
7078 | @noindent | |
7079 | @w{} | |
7080 | @sp 5 | |
7081 | ||
7082 | ||
7083 | @deffn {library procedure} write obj | |
7084 | @deffnx {library procedure} write obj port | |
7085 | ||
7086 | Writes a written representation of @var{obj} to the given @var{port}. Strings | |
7087 | that appear in the written representation are enclosed in doublequotes, and | |
7088 | within those strings backslash and doublequote characters are | |
7089 | escaped by backslashes. | |
7090 | Character objects are written using the @samp{#\} notation. | |
7fb9c4af | 7091 | @samp{Write} returns an unspecified value. The |
a0e07ba4 NJ |
7092 | @var{port} argument may be omitted, in which case it defaults to the value |
7093 | returned by @samp{current-output-port}. | |
7094 | ||
7095 | @end deffn | |
7096 | ||
7097 | ||
7098 | ||
7099 | @deffn {library procedure} display obj | |
7100 | @deffnx {library procedure} display obj port | |
7101 | ||
7102 | Writes a representation of @var{obj} to the given @var{port}. Strings | |
7103 | that appear in the written representation are not enclosed in | |
7104 | doublequotes, and no characters are escaped within those strings. Character | |
7105 | objects appear in the representation as if written by @samp{write-char} | |
7fb9c4af | 7106 | instead of by @samp{write}. @samp{Display} returns an unspecified value. |
a0e07ba4 NJ |
7107 | The @var{port} argument may be omitted, in which case it defaults to the |
7108 | value returned by @samp{current-output-port}. | |
7109 | ||
7110 | ||
7111 | @quotation | |
7112 | @emph{Rationale:} | |
7fb9c4af | 7113 | @samp{Write} is intended |
a0e07ba4 NJ |
7114 | for producing mach@-ine-readable output and @samp{display} is for producing |
7115 | human-readable output. Implementations that allow ``slashification'' | |
7116 | within symbols will probably want @samp{write} but not @samp{display} to | |
7117 | slashify funny characters in symbols. | |
7118 | @end quotation | |
7119 | ||
7120 | @end deffn | |
7121 | ||
7122 | ||
7123 | ||
7124 | @deffn {library procedure} newline | |
7125 | @deffnx {library procedure} newline port | |
7126 | ||
7127 | Writes an end of line to @var{port}. Exactly how this is done differs | |
7128 | from one operating system to another. Returns an unspecified value. | |
7129 | The @var{port} argument may be omitted, in which case it defaults to the | |
7130 | value returned by @samp{current-output-port}. | |
7131 | ||
7132 | @end deffn | |
7133 | ||
7134 | ||
7135 | ||
7136 | @deffn {procedure} write-char char | |
7137 | @deffnx {procedure} write-char char port | |
7138 | ||
7139 | Writes the character @var{char} (not an external representation of the | |
7140 | character) to the given @var{port} and returns an unspecified value. The | |
7141 | @var{port} argument may be omitted, in which case it defaults to the value | |
7142 | returned by @samp{current-output-port}. | |
7143 | ||
7144 | @end deffn | |
7145 | ||
7146 | ||
7147 | @node System interface, , Output, Input and output | |
7148 | @subsection System interface | |
7149 | ||
7150 | ||
7151 | Questions of system interface generally fall outside of the domain of this | |
7152 | report. However, the following operations are important enough to | |
7153 | deserve description here. | |
7154 | ||
7155 | ||
7156 | ||
7157 | @deffn {optional procedure} load filename | |
7158 | ||
7159 | @ignore todo | |
7160 | Fix | |
7161 | @end ignore | |
7162 | ||
7163 | ||
7164 | @c \domain{\var{Filename} should be a string naming an existing file | |
7165 | @c containing Scheme source code.} The {\cf load} procedure reads | |
7fb9c4af | 7166 | @var{Filename} should be a string naming an existing file |
a0e07ba4 NJ |
7167 | containing Scheme source code. The @samp{load} procedure reads |
7168 | expressions and definitions from the file and evaluates them | |
7169 | sequentially. It is unspecified whether the results of the expressions | |
7170 | are printed. The @samp{load} procedure does not affect the values | |
7171 | returned by @samp{current-input-port} and @samp{current-output-port}. | |
7fb9c4af | 7172 | @samp{Load} returns an unspecified value. |
a0e07ba4 NJ |
7173 | |
7174 | ||
7175 | @quotation | |
7176 | @emph{Rationale:} | |
7177 | For portability, @samp{load} must operate on source files. | |
7178 | Its operation on other kinds of files necessarily varies among | |
7179 | implementations. | |
7180 | @end quotation | |
7181 | ||
7182 | @end deffn | |
7183 | ||
7184 | ||
7185 | ||
7186 | @deffn {optional procedure} transcript-on filename | |
7187 | @deffnx {optional procedure} transcript-off | |
7188 | ||
7fb9c4af | 7189 | @var{Filename} must be a string naming an output file to be |
a0e07ba4 NJ |
7190 | created. The effect of @samp{transcript-on} is to open the named file |
7191 | for output, and to cause a transcript of subsequent interaction between | |
7192 | the user and the Scheme system to be written to the file. The | |
7193 | transcript is ended by a call to @samp{transcript-off}, which closes the | |
7194 | transcript file. Only one transcript may be in progress at any time, | |
7195 | though some implementations may relax this restriction. The values | |
7196 | returned by these procedures are unspecified. | |
7197 | ||
7198 | @c \begin{note} | |
7199 | @c These procedures are redundant in some systems, but | |
7200 | @c systems that need them should provide them. | |
7201 | @c \end{note} | |
7202 | @end deffn | |
7203 | ||
7204 | @page | |
7205 | ||
7206 | @c @include{syn} | |
7207 | @node Formal syntax and semantics, Notes, Standard procedures, top | |
7208 | @chapter Formal syntax and semantics | |
7209 | ||
7210 | @menu | |
7211 | * Formal syntax:: | |
7212 | * Formal semantics:: | |
7213 | * Derived expression type:: | |
7214 | @end menu | |
7215 | ||
7216 | ||
7217 | ||
7218 | This chapter provides formal descriptions of what has already been | |
7219 | described informally in previous chapters of this report. | |
7220 | ||
7221 | @ignore todo | |
7222 | Allow grammar to say that else clause needn't be last? | |
7223 | @end ignore | |
7224 | ||
7225 | ||
7226 | ||
7227 | @node Formal syntax, Formal semantics, Formal syntax and semantics, Formal syntax and semantics | |
7228 | @section Formal syntax | |
7229 | ||
7230 | @menu | |
7231 | * Lexical structure:: | |
7232 | * External representation:: | |
7233 | * Expression:: | |
7234 | * Quasiquotations:: | |
7235 | * Transformers:: | |
7236 | * Programs and definitions:: | |
7237 | @end menu | |
7238 | ||
7239 | ||
7240 | ||
7241 | This section provides a formal syntax for Scheme written in an extended | |
7242 | BNF. | |
7243 | ||
7244 | All spaces in the grammar are for legibility. Case is insignificant; | |
7245 | for example, @samp{#x1A} and @samp{#X1a} are equivalent. <empty> | |
7246 | stands for the empty string. | |
7247 | ||
7248 | The following extensions to BNF are used to make the description more | |
7249 | concise: <thing>* means zero or more occurrences of | |
7250 | <thing>; and <thing>+ means at least one | |
7251 | <thing>. | |
7252 | ||
7253 | ||
7254 | @node Lexical structure, External representation, Formal syntax, Formal syntax | |
7255 | @subsection Lexical structure | |
7256 | ||
7257 | ||
7258 | This section describes how individual tokens (identifiers, | |
7259 | @cindex @w{token} | |
7260 | numbers, etc.) are formed from sequences of characters. The following | |
7261 | sections describe how expressions and programs are formed from sequences | |
7262 | of tokens. | |
7263 | ||
7264 | <Intertoken space> may occur on either side of any token, but not | |
7265 | within a token. | |
7266 | ||
7267 | Tokens which require implicit termination (identifiers, numbers, | |
7268 | characters, and dot) may be terminated by any <delimiter>, but not | |
7269 | necessarily by anything else. | |
7270 | ||
7271 | The following five characters are reserved for future extensions to the | |
7272 | language: @t{[ ] @{ @} |} | |
7273 | ||
7274 | ||
7275 | @format | |
7276 | @t{<token> --> <identifier> | <boolean> | <number> | |
7277 | @cindex @w{identifier} | |
7278 | | <character> | <string> | |
7279 | | ( | ) | #( | @t{'} | @t{`} | , | ,@@ | @b{.} | |
7280 | <delimiter> --> <whitespace> | ( | ) | " | ; | |
7281 | <whitespace> --> <space or newline> | |
7282 | <comment> --> ; <@r{all subsequent characters up to a} | |
7283 | @r{line break>} | |
7284 | @cindex @w{comment} | |
7285 | <atmosphere> --> <whitespace> | <comment> | |
7286 | <intertoken space> --> <atmosphere>*} | |
7287 | ||
7288 | @end format | |
7289 | ||
7290 | ||
7291 | ||
7292 | ||
7293 | ||
7294 | ||
7295 | @c This is a kludge, but \multicolumn doesn't work in tabbing environments. | |
7296 | ||
7297 | ||
7298 | ||
7299 | @format | |
7300 | @t{<identifier> --> <initial> <subsequent>* | |
7301 | | <peculiar identifier> | |
7302 | <initial> --> <letter> | <special initial> | |
7303 | <letter> --> a | b | c | ... | z | |
7304 | ||
7305 | <special initial> --> ! | $ | % | & | * | / | : | < | = | |
7306 | | > | ? | ^ | _ | ~ | |
7307 | <subsequent> --> <initial> | <digit> | |
7308 | | <special subsequent> | |
7309 | <digit> --> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | |
7310 | <special subsequent> --> + | - | .@: | @@ | |
7311 | <peculiar identifier> --> + | - | ... | |
7312 | <syntactic keyword> --> <expression keyword> | |
7313 | @cindex @w{syntactic keyword} | |
7314 | @cindex @w{keyword} | |
7315 | | else | => | define | |
7316 | | unquote | unquote-splicing | |
7317 | <expression keyword> --> quote | lambda | if | |
7318 | | set! | begin | cond | and | or | case | |
7319 | | let | let* | letrec | do | delay | |
7320 | | quasiquote | |
7321 | ||
7322 | @w{@samp{<variable> @result{} <}}@r{any <identifier> that isn't} | |
7323 | @cindex @w{variable} | |
7324 | @w{ @r{also a <syntactic keyword>>}} | |
7325 | ||
7326 | <boolean> --> #t | #f | |
7327 | <character> --> #\ <any character> | |
7328 | | #\ <character name> | |
7329 | <character name> --> space | newline | |
7330 | ||
7331 | <string> --> " <string element>* " | |
7332 | <string element> --> <any character other than " or \> | |
7333 | | \" | \\ } | |
7334 | ||
7335 | @end format | |
7336 | ||
7337 | ||
7338 | ||
7339 | ||
7340 | ||
7341 | ||
7342 | ||
7343 | @format | |
7344 | @t{<number> --> <num 2>| <num 8> | |
7345 | | <num 10>| <num 16> | |
7346 | } | |
7347 | ||
7348 | @end format | |
7349 | ||
7350 | ||
7351 | ||
7352 | The following rules for <num R>, <complex R>, <real | |
7353 | R>, <ureal R>, <uinteger R>, and <prefix R> | |
7354 | should be replicated for @w{R = 2, 8, 10,} | |
7355 | and 16. There are no rules for <decimal 2>, <decimal | |
7356 | 8>, and <decimal 16>, which means that numbers containing | |
7357 | decimal points or exponents must be in decimal radix. | |
7358 | @ignore todo | |
7359 | Mark Meyer and David Bartley want to fix this. (What? -- Will) | |
7360 | @end ignore | |
7361 | ||
7362 | ||
7363 | ||
7364 | @format | |
7365 | @t{<num R> --> <prefix R> <complex R> | |
7366 | <complex R> --> <real R> | <real R> @@ <real R> | |
7367 | | <real R> + <ureal R> i | <real R> - <ureal R> i | |
7368 | | <real R> + i | <real R> - i | |
7369 | | + <ureal R> i | - <ureal R> i | + i | - i | |
7370 | <real R> --> <sign> <ureal R> | |
7371 | <ureal R> --> <uinteger R> | |
7372 | | <uinteger R> / <uinteger R> | |
7373 | | <decimal R> | |
7374 | <decimal 10> --> <uinteger 10> <suffix> | |
7375 | | . <digit 10>+ #* <suffix> | |
7376 | | <digit 10>+ . <digit 10>* #* <suffix> | |
7377 | | <digit 10>+ #+ . #* <suffix> | |
7378 | <uinteger R> --> <digit R>+ #* | |
7379 | <prefix R> --> <radix R> <exactness> | |
7380 | | <exactness> <radix R> | |
7381 | } | |
7382 | ||
7383 | @end format | |
7384 | ||
7385 | ||
7386 | ||
7387 | ||
7388 | @format | |
7389 | @t{<suffix> --> <empty> | |
7390 | | <exponent marker> <sign> <digit 10>+ | |
7391 | <exponent marker> --> e | s | f | d | l | |
7392 | <sign> --> <empty> | + | - | |
7393 | <exactness> --> <empty> | #i | #e | |
7394 | @vindex #e | |
7395 | @vindex #i | |
7396 | <radix 2> --> #b | |
7397 | @vindex #b | |
7398 | <radix 8> --> #o | |
7399 | @vindex #o | |
7400 | <radix 10> --> <empty> | #d | |
7401 | <radix 16> --> #x | |
7402 | @vindex #x | |
7403 | <digit 2> --> 0 | 1 | |
7404 | <digit 8> --> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |
7405 | <digit 10> --> <digit> | |
7406 | <digit 16> --> <digit 10> | a | b | c | d | e | f } | |
7407 | ||
7408 | @end format | |
7409 | ||
7410 | ||
7411 | ||
7412 | @ignore todo | |
7413 | Mark Meyer of TI sez, shouldn't we allow @t{1e3/2}? | |
7414 | @end ignore | |
7415 | ||
7416 | ||
7417 | ||
7418 | @node External representation, Expression, Lexical structure, Formal syntax | |
7419 | @subsection External representations | |
7420 | ||
7421 | ||
7422 | ||
7423 | <Datum> is what the @code{read} procedure (section @pxref{Input}) | |
7424 | @vindex @w{read} | |
7425 | successfully parses. Note that any string that parses as an | |
7426 | <ex@-pres@-sion> will also parse as a <datum>. | |
7427 | ||
7428 | ||
7429 | @format | |
7430 | @t{<datum> --> <simple datum> | <compound datum> | |
7431 | <simple datum> --> <boolean> | <number> | |
7432 | | <character> | <string> | <symbol> | |
7433 | <symbol> --> <identifier> | |
7434 | <compound datum> --> <list> | <vector> | |
7435 | <list> --> (<datum>*) | (<datum>+ .@: <datum>) | |
7436 | | <abbreviation> | |
7437 | <abbreviation> --> <abbrev prefix> <datum> | |
7438 | <abbrev prefix> --> ' | ` | , | ,@@ | |
7439 | <vector> --> #(<datum>*) } | |
7440 | ||
7441 | @end format | |
7442 | ||
7443 | ||
7444 | ||
7445 | ||
7446 | @node Expression, Quasiquotations, External representation, Formal syntax | |
7447 | @subsection Expressions | |
7448 | ||
7449 | ||
7450 | ||
7451 | @format | |
7452 | @t{<expression> --> <variable> | |
7453 | | <literal> | |
7454 | | <procedure call> | |
7455 | | <lambda expression> | |
7456 | | <conditional> | |
7457 | | <assignment> | |
7458 | | <derived expression> | |
7459 | | <macro use> | |
7460 | | <macro block> | |
7461 | ||
7462 | <literal> --> <quotation> | <self-evaluating> | |
7463 | <self-evaluating> --> <boolean> | <number> | |
7464 | | <character> | <string> | |
7465 | <quotation> --> '<datum> | (quote <datum>) | |
7466 | <procedure call> --> (<operator> <operand>*) | |
7467 | <operator> --> <expression> | |
7468 | <operand> --> <expression> | |
7469 | ||
7470 | <lambda expression> --> (lambda <formals> <body>) | |
7471 | <formals> --> (<variable>*) | <variable> | |
7472 | | (<variable>+ .@: <variable>) | |
7473 | <body> --> <definition>* <sequence> | |
7474 | <sequence> --> <command>* <expression> | |
7475 | <command> --> <expression> | |
7476 | ||
7477 | <conditional> --> (if <test> <consequent> <alternate>) | |
7478 | <test> --> <expression> | |
7479 | <consequent> --> <expression> | |
7480 | <alternate> --> <expression> | <empty> | |
7481 | ||
7482 | <assignment> --> (set! <variable> <expression>) | |
7483 | ||
7484 | <derived expression> --> | |
7485 | (cond <cond clause>+) | |
7486 | | (cond <cond clause>* (else <sequence>)) | |
7487 | | (case <expression> | |
7488 | <case clause>+) | |
7489 | | (case <expression> | |
7490 | <case clause>* | |
7491 | (else <sequence>)) | |
7492 | | (and <test>*) | |
7493 | | (or <test>*) | |
7494 | | (let (<binding spec>*) <body>) | |
7495 | | (let <variable> (<binding spec>*) <body>) | |
7496 | | (let* (<binding spec>*) <body>) | |
7497 | | (letrec (<binding spec>*) <body>) | |
7498 | | (begin <sequence>) | |
7499 | | (do (<iteration spec>*) | |
7500 | (<test> <do result>) | |
7501 | <command>*) | |
7502 | | (delay <expression>) | |
7503 | | <quasiquotation> | |
7504 | ||
7505 | <cond clause> --> (<test> <sequence>) | |
7506 | | (<test>) | |
7507 | | (<test> => <recipient>) | |
7508 | <recipient> --> <expression> | |
7509 | <case clause> --> ((<datum>*) <sequence>) | |
7510 | <binding spec> --> (<variable> <expression>) | |
7511 | <iteration spec> --> (<variable> <init> <step>) | |
7512 | | (<variable> <init>) | |
7513 | <init> --> <expression> | |
7514 | <step> --> <expression> | |
7515 | <do result> --> <sequence> | <empty> | |
7516 | ||
7517 | <macro use> --> (<keyword> <datum>*) | |
7518 | <keyword> --> <identifier> | |
7519 | ||
7520 | <macro block> --> | |
7521 | (let-syntax (<syntax spec>*) <body>) | |
7522 | | (letrec-syntax (<syntax spec>*) <body>) | |
7523 | <syntax spec> --> (<keyword> <transformer spec>) | |
7524 | ||
7525 | } | |
7526 | ||
7527 | @end format | |
7528 | ||
7529 | ||
7530 | ||
7531 | @node Quasiquotations, Transformers, Expression, Formal syntax | |
7532 | @subsection Quasiquotations | |
7533 | ||
7534 | ||
7535 | The following grammar for quasiquote expressions is not context-free. | |
7536 | It is presented as a recipe for generating an infinite number of | |
7537 | production rules. Imagine a copy of the following rules for D = 1, 2,3, @dots{}. D keeps track of the nesting depth. | |
7538 | ||
7539 | ||
7540 | @format | |
7541 | @t{<quasiquotation> --> <quasiquotation 1> | |
7542 | <qq template 0> --> <expression> | |
7543 | <quasiquotation D> --> `<qq template D> | |
7544 | | (quasiquote <qq template D>) | |
7545 | <qq template D> --> <simple datum> | |
7546 | | <list qq template D> | |
7547 | | <vector qq template D> | |
7548 | | <unquotation D> | |
7549 | <list qq template D> --> (<qq template or splice D>*) | |
7550 | | (<qq template or splice D>+ .@: <qq template D>) | |
7551 | | '<qq template D> | |
7552 | | <quasiquotation D+1> | |
7553 | <vector qq template D> --> #(<qq template or splice D>*) | |
7554 | <unquotation D> --> ,<qq template D-1> | |
7555 | | (unquote <qq template D-1>) | |
7556 | <qq template or splice D> --> <qq template D> | |
7557 | | <splicing unquotation D> | |
7558 | <splicing unquotation D> --> ,@@<qq template D-1> | |
7559 | | (unquote-splicing <qq template D-1>) } | |
7560 | ||
7561 | @end format | |
7562 | ||
7563 | ||
7564 | ||
7565 | In <quasiquotation>s, a <list qq template D> can sometimes | |
7566 | be confused with either an <un@-quota@-tion D> or a <splicing | |
7567 | un@-quo@-ta@-tion D>. The interpretation as an | |
7568 | <un@-quo@-ta@-tion> or <splicing | |
7569 | un@-quo@-ta@-tion D> takes precedence. | |
7570 | ||
7571 | @node Transformers, Programs and definitions, Quasiquotations, Formal syntax | |
7572 | @subsection Transformers | |
7573 | ||
7574 | ||
7575 | ||
7576 | @format | |
7577 | @t{<transformer spec> --> | |
7578 | (syntax-rules (<identifier>*) <syntax rule>*) | |
7579 | <syntax rule> --> (<pattern> <template>) | |
7580 | <pattern> --> <pattern identifier> | |
7581 | | (<pattern>*) | |
7582 | | (<pattern>+ . <pattern>) | |
7583 | | (<pattern>* <pattern> <ellipsis>) | |
7584 | | #(<pattern>*) | |
7585 | | #(<pattern>* <pattern> <ellipsis>) | |
7586 | | <pattern datum> | |
7587 | <pattern datum> --> <string> | |
7588 | | <character> | |
7589 | | <boolean> | |
7590 | | <number> | |
7591 | <template> --> <pattern identifier> | |
7592 | | (<template element>*) | |
7593 | | (<template element>+ . <template>) | |
7594 | | #(<template element>*) | |
7595 | | <template datum> | |
7596 | <template element> --> <template> | |
7597 | | <template> <ellipsis> | |
7598 | <template datum> --> <pattern datum> | |
7599 | <pattern identifier> --> <any identifier except @samp{...}> | |
7600 | <ellipsis> --> <the identifier @samp{...}> | |
7601 | } | |
7602 | ||
7603 | @end format | |
7604 | ||
7605 | ||
7606 | ||
7607 | @node Programs and definitions, , Transformers, Formal syntax | |
7608 | @subsection Programs and definitions | |
7609 | ||
7610 | ||
7611 | ||
7612 | @format | |
7613 | @t{<program> --> <command or definition>* | |
7614 | <command or definition> --> <command> | |
7615 | | <definition> | |
7616 | | <syntax definition> | |
7617 | | (begin <command or definition>+) | |
7618 | <definition> --> (define <variable> <expression>) | |
7619 | | (define (<variable> <def formals>) <body>) | |
7620 | | (begin <definition>*) | |
7621 | <def formals> --> <variable>* | |
7622 | | <variable>* .@: <variable> | |
7623 | <syntax definition> --> | |
7624 | (define-syntax <keyword> <transformer spec>) | |
7625 | } | |
7626 | ||
7627 | @end format | |
7628 | ||
7629 | ||
7630 | ||
7631 | @node Formal semantics, Derived expression type, Formal syntax, Formal syntax and semantics | |
7632 | @section Formal semantics | |
7633 | ||
7634 | ||
7635 | This section provides a formal denotational semantics for the primitive | |
7636 | expressions of Scheme and selected built-in procedures. The concepts | |
7637 | and notation used here are described in @sc{[Stoy77]}. | |
7638 | ||
7639 | @quotation | |
7640 | @emph{Note:} The formal semantics section was written in La@TeX{} which | |
7641 | is incompatible with @TeX{}info. See the Formal semantics section of | |
7642 | the original document from which this was derived. | |
7643 | @end quotation | |
7644 | ||
7645 | ||
7646 | @c @include{derive} | |
7647 | @node Derived expression type, , Formal semantics, Formal syntax and semantics | |
7648 | @section Derived expression types | |
7649 | ||
7650 | ||
7651 | ||
7652 | This section gives macro definitions for the derived expression types in | |
7653 | terms of the primitive expression types (literal, variable, call, @samp{lambda}, | |
7654 | @samp{if}, @samp{set!}). See section @ref{Control features} for a possible | |
7655 | definition of @samp{delay}. | |
7656 | ||
7657 | ||
7658 | @example | |
7659 | ||
7660 | (define-syntax cond | |
7661 | (syntax-rules (else =>) | |
7662 | ((cond (else result1 result2 ...)) | |
7663 | (begin result1 result2 ...)) | |
7664 | ((cond (test => result)) | |
7665 | (let ((temp test)) | |
7666 | (if temp (result temp)))) | |
7667 | ((cond (test => result) clause1 clause2 ...) | |
7668 | (let ((temp test)) | |
7669 | (if temp | |
7670 | (result temp) | |
7671 | (cond clause1 clause2 ...)))) | |
7672 | ((cond (test)) test) | |
7673 | ((cond (test) clause1 clause2 ...) | |
7674 | (let ((temp test)) | |
7675 | (if temp | |
7676 | temp | |
7677 | (cond clause1 clause2 ...)))) | |
7678 | ((cond (test result1 result2 ...)) | |
7679 | (if test (begin result1 result2 ...))) | |
7680 | ((cond (test result1 result2 ...) | |
7681 | clause1 clause2 ...) | |
7682 | (if test | |
7683 | (begin result1 result2 ...) | |
7684 | (cond clause1 clause2 ...))))) | |
7685 | ||
7686 | @end example | |
7687 | ||
7688 | ||
7689 | ||
7690 | @example | |
7691 | ||
7692 | (define-syntax case | |
7693 | (syntax-rules (else) | |
7694 | ((case (key ...) | |
7695 | clauses ...) | |
7696 | (let ((atom-key (key ...))) | |
7697 | (case atom-key clauses ...))) | |
7698 | ((case key | |
7699 | (else result1 result2 ...)) | |
7700 | (begin result1 result2 ...)) | |
7701 | ((case key | |
7702 | ((atoms ...) result1 result2 ...)) | |
7703 | (if (memv key '(atoms ...)) | |
7704 | (begin result1 result2 ...))) | |
7705 | ((case key | |
7706 | ((atoms ...) result1 result2 ...) | |
7707 | clause clauses ...) | |
7708 | (if (memv key '(atoms ...)) | |
7709 | (begin result1 result2 ...) | |
7710 | (case key clause clauses ...))))) | |
7711 | ||
7712 | @end example | |
7713 | ||
7714 | ||
7715 | ||
7716 | @example | |
7717 | ||
7718 | (define-syntax and | |
7719 | (syntax-rules () | |
7720 | ((and) #t) | |
7721 | ((and test) test) | |
7722 | ((and test1 test2 ...) | |
7723 | (if test1 (and test2 ...) #f)))) | |
7724 | ||
7725 | @end example | |
7726 | ||
7727 | ||
7728 | ||
7729 | @example | |
7730 | ||
7731 | (define-syntax or | |
7732 | (syntax-rules () | |
7733 | ((or) #f) | |
7734 | ((or test) test) | |
7735 | ((or test1 test2 ...) | |
7736 | (let ((x test1)) | |
7737 | (if x x (or test2 ...)))))) | |
7738 | ||
7739 | @end example | |
7740 | ||
7741 | ||
7742 | ||
7743 | @example | |
7744 | ||
7745 | (define-syntax let | |
7746 | (syntax-rules () | |
7747 | ((let ((name val) ...) body1 body2 ...) | |
7748 | ((lambda (name ...) body1 body2 ...) | |
7749 | val ...)) | |
7750 | ((let tag ((name val) ...) body1 body2 ...) | |
7751 | ((letrec ((tag (lambda (name ...) | |
7752 | body1 body2 ...))) | |
7753 | tag) | |
7754 | val ...)))) | |
7755 | ||
7756 | @end example | |
7757 | ||
7758 | ||
7759 | ||
7760 | @example | |
7761 | ||
7762 | (define-syntax let* | |
7763 | (syntax-rules () | |
7764 | ((let* () body1 body2 ...) | |
7765 | (let () body1 body2 ...)) | |
7766 | ((let* ((name1 val1) (name2 val2) ...) | |
7767 | body1 body2 ...) | |
7768 | (let ((name1 val1)) | |
7769 | (let* ((name2 val2) ...) | |
7770 | body1 body2 ...))))) | |
7771 | ||
7772 | @end example | |
7773 | ||
7774 | ||
7775 | The following @samp{letrec} macro uses the symbol @samp{<undefined>} | |
7776 | in place of an expression which returns something that when stored in | |
7777 | a location makes it an error to try to obtain the value stored in the | |
7778 | location (no such expression is defined in Scheme). | |
7779 | A trick is used to generate the temporary names needed to avoid | |
7780 | specifying the order in which the values are evaluated. | |
7781 | This could also be accomplished by using an auxiliary macro. | |
7782 | ||
7783 | ||
7784 | @example | |
7785 | ||
7786 | (define-syntax letrec | |
7787 | (syntax-rules () | |
7788 | ((letrec ((var1 init1) ...) body ...) | |
7789 | (letrec "generate temp names" | |
7790 | (var1 ...) | |
7791 | () | |
7792 | ((var1 init1) ...) | |
7793 | body ...)) | |
7794 | ((letrec "generate temp names" | |
7795 | () | |
7796 | (temp1 ...) | |
7797 | ((var1 init1) ...) | |
7798 | body ...) | |
7799 | (let ((var1 <undefined>) ...) | |
7800 | (let ((temp1 init1) ...) | |
7801 | (set! var1 temp1) | |
7802 | ... | |
7803 | body ...))) | |
7804 | ((letrec "generate temp names" | |
7805 | (x y ...) | |
7806 | (temp ...) | |
7807 | ((var1 init1) ...) | |
7808 | body ...) | |
7809 | (letrec "generate temp names" | |
7810 | (y ...) | |
7811 | (newtemp temp ...) | |
7812 | ((var1 init1) ...) | |
7813 | body ...)))) | |
7814 | ||
7815 | @end example | |
7816 | ||
7817 | ||
7818 | ||
7819 | @example | |
7820 | ||
7821 | (define-syntax begin | |
7822 | (syntax-rules () | |
7823 | ((begin exp ...) | |
7824 | ((lambda () exp ...))))) | |
7825 | ||
7826 | @end example | |
7827 | ||
7828 | ||
7829 | The following alternative expansion for @samp{begin} does not make use of | |
7830 | the ability to write more than one expression in the body of a lambda | |
7831 | expression. In any case, note that these rules apply only if the body | |
7832 | of the @samp{begin} contains no definitions. | |
7833 | ||
7834 | ||
7835 | @example | |
7836 | ||
7837 | (define-syntax begin | |
7838 | (syntax-rules () | |
7839 | ((begin exp) | |
7840 | exp) | |
7841 | ((begin exp1 exp2 ...) | |
7842 | (let ((x exp1)) | |
7843 | (begin exp2 ...))))) | |
7844 | ||
7845 | @end example | |
7846 | ||
7847 | ||
7848 | The following definition | |
7849 | of @samp{do} uses a trick to expand the variable clauses. | |
7850 | As with @samp{letrec} above, an auxiliary macro would also work. | |
7851 | The expression @samp{(if #f #f)} is used to obtain an unspecific | |
7852 | value. | |
7853 | ||
7854 | ||
7855 | @example | |
7856 | ||
7857 | (define-syntax do | |
7858 | (syntax-rules () | |
7859 | ((do ((var init step ...) ...) | |
7860 | (test expr ...) | |
7861 | command ...) | |
7862 | (letrec | |
7863 | ((loop | |
7864 | (lambda (var ...) | |
7865 | (if test | |
7866 | (begin | |
7867 | (if #f #f) | |
7868 | expr ...) | |
7869 | (begin | |
7870 | command | |
7871 | ... | |
7872 | (loop (do "step" var step ...) | |
7873 | ...)))))) | |
7874 | (loop init ...))) | |
7875 | ((do "step" x) | |
7876 | x) | |
7877 | ((do "step" x y) | |
7878 | y))) | |
7879 | ||
7880 | @end example | |
7881 | ||
7882 | ||
7883 | @c `a = Q_1[a] | |
7884 | @c `(a b c ... . z) = `(a . (b c ...)) | |
7885 | @c `(a . b) = (append Q*_0[a] `b) | |
7886 | @c `(a) = Q*_0[a] | |
7887 | @c Q*_0[a] = (list 'a) | |
7888 | @c Q*_0[,a] = (list a) | |
7889 | @c Q*_0[,@a] = a | |
7890 | @c Q*_0[`a] = (list 'quasiquote Q*_1[a]) | |
7891 | @c `#(a b ...) = (list->vector `(a b ...)) | |
7892 | @c ugh. | |
7893 | ||
7894 | @page | |
7895 | ||
7896 | @c @include{notes} | |
7897 | @node Notes, Additional material, Formal syntax and semantics, top | |
7898 | @unnumbered Notes | |
7899 | ||
7900 | @menu | |
7901 | * Language changes:: | |
7902 | @end menu | |
7903 | ||
7904 | ||
7905 | ||
7906 | @ignore todo | |
7907 | Perhaps this section should be made to disappear. | |
7908 | Can these remarks be moved somewhere else? | |
7909 | @end ignore | |
7910 | ||
7911 | ||
7912 | @node Language changes, , Notes, Notes | |
7913 | @unnumberedsec Language changes | |
7914 | ||
7915 | ||
7916 | ||
7917 | This section enumerates the changes that have been made to Scheme since | |
7918 | the ``Revised^4 report'' [R4RS] was published. | |
7919 | ||
7920 | ||
7921 | ||
7922 | @itemize @bullet | |
7923 | ||
7924 | ||
7925 | @item | |
7926 | The report is now a superset of the IEEE standard for Scheme | |
7927 | [IEEEScheme]: implementations that conform to the report will | |
7928 | also conform to the standard. This required the following changes: | |
7929 | ||
7930 | ||
7931 | @itemize @bullet | |
7932 | ||
7933 | ||
7934 | @item | |
7935 | The empty list is now required to count as true. | |
7936 | ||
7937 | @item | |
7938 | The classification of features as essential or inessential has been | |
7939 | removed. There are now three classes of built-in procedures: primitive, | |
7940 | library, and optional. The optional procedures are @samp{load}, | |
7941 | @samp{with-input-from-file}, @samp{with-output-to-file}, | |
7942 | @samp{transcript-on}, @samp{transcript-off}, and | |
7943 | @samp{interaction-environment}, | |
7944 | and @samp{-} and @samp{/} with more than two arguments. | |
7945 | None of these are in the IEEE standard. | |
7946 | ||
7947 | @item | |
7948 | Programs are allowed to redefine built-in procedures. Doing so | |
7949 | will not change the behavior of other built-in procedures. | |
7950 | ||
7951 | @end itemize | |
7952 | ||
7953 | ||
7954 | @item | |
7955 | @emph{Port} has been added to the list of disjoint types. | |
7956 | ||
7957 | @item | |
7958 | The macro appendix has been removed. High-level macros are now part | |
7959 | of the main body of the report. The rewrite rules for derived expressions | |
7960 | have been replaced with macro definitions. There are no reserved identifiers. | |
7961 | ||
7962 | @item | |
7fb9c4af | 7963 | @samp{Syntax-rules} now allows vector patterns. |
a0e07ba4 NJ |
7964 | |
7965 | @item | |
7966 | Multiple-value returns, @samp{eval}, and @samp{dynamic-wind} have | |
7967 | been added. | |
7968 | ||
7969 | @item | |
7970 | The calls that are required to be implemented in a properly tail-recursive | |
7971 | fashion are defined explicitly. | |
7972 | ||
7973 | @item | |
7974 | `@samp{@@}' can be used within identifiers. `@samp{|}' is reserved | |
7975 | for possible future extensions. | |
7976 | ||
7977 | ||
7978 | @end itemize | |
7979 | ||
7980 | ||
7981 | @c %R4%% | |
7982 | @c \subsection*{Keywords as variable names} | |
7983 | ||
7984 | @c Some implementations allow arbitrary syntactic | |
7985 | @c keywords \index{keyword}\index{syntactic keyword}to be used as variable | |
7986 | @c names, instead of reserving them, as this report would have | |
7987 | @c it.\index{variable} But this creates ambiguities in the interpretation | |
7988 | @c of expressions: for example, in the following, it's not clear whether | |
7989 | @c the expression {\tt (if 1 2 3)} should be treated as a procedure call or | |
7990 | @c as a conditional. | |
7991 | ||
7992 | @c \begin{scheme} | |
7993 | @c (define if list) | |
7994 | @c (if 1 2 3) \ev 2 {\em{}or} (1 2 3)% | |
7995 | @c \end{scheme} | |
7996 | ||
7997 | @c These ambiguities are usually resolved in some consistent way within any | |
7998 | @c given implementation, but no particular treatment stands out as being | |
7999 | @c clearly superior to any other, so these situations were excluded for the | |
8000 | @c purposes of this report. | |
8001 | ||
8002 | @c %R4%% | |
8003 | @c \subsection*{Macros} | |
8004 | ||
8005 | @c Scheme does not have any standard facility for defining new kinds of | |
8006 | @c expressions.\index{macros} | |
8007 | ||
8008 | @c \vest The ability to alter the syntax of the language creates | |
8009 | @c numerous problems. All current implementations of Scheme have macro | |
8010 | @c facilities that solve those problems to one degree or another, but the | |
8011 | @c solutions are quite different and it isn't clear at this time which | |
8012 | @c solution is best, or indeed whether any of the solutions are truly | |
8013 | @c adequate. Rather than standardize, we are encouraging implementations | |
8014 | @c to continue to experiment with different solutions. | |
8015 | ||
8016 | @c \vest The main problems with traditional macros are: They must be | |
8017 | @c defined to the system before any code using them is loaded; this is a | |
8018 | @c common source of obscure bugs. They are usually global; macros can be | |
8019 | @c made to follow lexical scope rules \todo{flushed: ``as in Common | |
8020 | @c Lisp's {\tt macrolet}''; OK?}, but many people find the resulting scope rules | |
8021 | @c confusing. Unless they are written very carefully, macros are | |
8022 | @c vulnerable to inadvertent capture of free variables; to get around this, | |
8023 | @c for example, macros may have to generate code in which procedure values | |
8024 | @c appear as quoted constants. There is a similar problem with syntactic | |
8025 | @c keywords if the keywords of special forms are not reserved. If keywords | |
8026 | @c are reserved, then either macros introduce new reserved words, | |
8027 | @c invalidating old code, or else special forms defined by the programmer | |
8028 | @c do not have the same status as special forms defined by the system. | |
8029 | ||
8030 | @c \todo{Refer to Pitman's special forms paper.} | |
8031 | @c \todo{Pitman sez: Discuss importance of having a small number of special forms | |
8032 | @c so that programs can inspect each other.} | |
8033 | ||
8034 | @ignore todo | |
8035 | Move cwcc history back here? --- Andy Cromarty is concerned about | |
8036 | confusion over who the audience is. | |
8037 | @end ignore | |
8038 | ||
8039 | ||
8040 | @ignore todo | |
8041 | Cromarty: | |
8042 | 23. NOTES, p.35ff.: This material should stay somehow. We need to | |
8043 | make it clear that R^3 Scheme is not being touted as Yet Another | |
8044 | Ultimate Solution To The Programming Language Problem, but rather | |
8045 | as a snapshot of a *process* of good design, for which not all | |
8046 | answers have yet been found. We also ought to use the opportunity | |
8047 | for publicity afforded us by SIGPLAN to advertise some of the thorny | |
8048 | unsolved problems that need further research, and encourage | |
8049 | language designers to work on them. | |
8050 | @end ignore | |
8051 | ||
8052 | ||
8053 | @c @include{repository} | |
8054 | @node Additional material, Example, Notes, top | |
8055 | @unnumbered Additional material | |
8056 | ||
8057 | ||
8058 | The Internet Scheme Repository at | |
8059 | ||
8060 | @center | |
8061 | @center @url{http://www.cs.indiana.edu/scheme-repository/} | |
8062 | @center | |
8063 | ||
8064 | contains an extensive Scheme bibliography, as well as papers, | |
8065 | programs, implementations, and other material related to Scheme. | |
8066 | ||
8067 | @page | |
8068 | ||
8069 | @c @include{example} | |
8070 | ||
8071 | @node Example, Bibliography, Additional material, top | |
8072 | @unnumbered Example | |
8073 | ||
8074 | @c -*- Mode: Lisp; Package: SCHEME; Syntax: Common-lisp -*- | |
8075 | ||
8076 | ||
7fb9c4af | 8077 | @samp{Integrate-system} integrates the system |
a0e07ba4 NJ |
8078 | |
8079 | ||
8080 | @center y_k^^ = f_k(y_1, y_2, @dots{}, y_n), k = 1, @dots{}, n | |
8081 | ||
8082 | of differential equations with the method of Runge-Kutta. | |
8083 | ||
8084 | The parameter @t{system-derivative} is a function that takes a system | |
8085 | state (a vector of values for the state variables y_1, @dots{}, y_n) | |
8086 | and produces a system derivative (the values y_1^^, @dots{},y_n^^). The parameter @t{initial-state} provides an initial | |
8087 | system state, and @t{h} is an initial guess for the length of the | |
8088 | integration step. | |
8089 | ||
8090 | The value returned by @samp{integrate-system} is an infinite stream of | |
8091 | system states. | |
8092 | ||
8093 | ||
8094 | @example | |
8095 | ||
8096 | (define integrate-system | |
8097 | (lambda (system-derivative initial-state h) | |
8098 | (let ((next (runge-kutta-4 system-derivative h))) | |
8099 | (letrec ((states | |
8100 | (cons initial-state | |
8101 | (delay (map-streams next | |
8102 | states))))) | |
8103 | states)))) | |
8104 | ||
8105 | @end example | |
8106 | ||
8107 | ||
7fb9c4af AW |
8108 | @samp{Runge-Kutta-4} takes a function, @t{f}, that produces a |
8109 | system derivative from a system state. @samp{Runge-Kutta-4} | |
a0e07ba4 NJ |
8110 | produces a function that takes a system state and |
8111 | produces a new system state. | |
8112 | ||
8113 | ||
8114 | @example | |
8115 | ||
8116 | (define runge-kutta-4 | |
8117 | (lambda (f h) | |
8118 | (let ((*h (scale-vector h)) | |
8119 | (*2 (scale-vector 2)) | |
8120 | (*1/2 (scale-vector (/ 1 2))) | |
8121 | (*1/6 (scale-vector (/ 1 6)))) | |
8122 | (lambda (y) | |
8123 | ;; y @r{}is a system state | |
8124 | (let* ((k0 (*h (f y))) | |
8125 | (k1 (*h (f (add-vectors y (*1/2 k0))))) | |
8126 | (k2 (*h (f (add-vectors y (*1/2 k1))))) | |
8127 | (k3 (*h (f (add-vectors y k2))))) | |
8128 | (add-vectors y | |
8129 | (*1/6 (add-vectors k0 | |
8130 | (*2 k1) | |
8131 | (*2 k2) | |
8132 | k3)))))))) | |
8133 | @c |--------------------------------------------------| | |
8134 | ||
8135 | (define elementwise | |
8136 | (lambda (f) | |
8137 | (lambda vectors | |
8138 | (generate-vector | |
8139 | (vector-length (car vectors)) | |
8140 | (lambda (i) | |
8141 | (apply f | |
8142 | (map (lambda (v) (vector-ref v i)) | |
8143 | vectors))))))) | |
8144 | ||
8145 | @c |--------------------------------------------------| | |
8146 | (define generate-vector | |
8147 | (lambda (size proc) | |
8148 | (let ((ans (make-vector size))) | |
8149 | (letrec ((loop | |
8150 | (lambda (i) | |
8151 | (cond ((= i size) ans) | |
8152 | (else | |
8153 | (vector-set! ans i (proc i)) | |
8154 | (loop (+ i 1))))))) | |
8155 | (loop 0))))) | |
8156 | ||
8157 | (define add-vectors (elementwise +)) | |
8158 | ||
8159 | (define scale-vector | |
8160 | (lambda (s) | |
8161 | (elementwise (lambda (x) (* x s))))) | |
8162 | ||
8163 | @end example | |
8164 | ||
8165 | ||
7fb9c4af | 8166 | @samp{Map-streams} is analogous to @samp{map}: it applies its first |
a0e07ba4 NJ |
8167 | argument (a procedure) to all the elements of its second argument (a |
8168 | stream). | |
8169 | ||
8170 | ||
8171 | @example | |
8172 | ||
8173 | (define map-streams | |
8174 | (lambda (f s) | |
8175 | (cons (f (head s)) | |
8176 | (delay (map-streams f (tail s)))))) | |
8177 | ||
8178 | @end example | |
8179 | ||
8180 | ||
8181 | Infinite streams are implemented as pairs whose car holds the first | |
8182 | element of the stream and whose cdr holds a promise to deliver the rest | |
8183 | of the stream. | |
8184 | ||
8185 | ||
8186 | @example | |
8187 | ||
8188 | (define head car) | |
8189 | (define tail | |
8190 | (lambda (stream) (force (cdr stream)))) | |
8191 | ||
8192 | @end example | |
8193 | ||
8194 | ||
8195 | @sp 6 | |
8196 | The following illustrates the use of @samp{integrate-system} in | |
8197 | integrating the system | |
8198 | ||
8199 | ||
8200 | @center C dv_C / dt = -i_L - v_C / R | |
8201 | ||
8202 | ||
8203 | ||
8204 | @center L di_L / dt = v_C | |
8205 | ||
8206 | which models a damped oscillator. | |
8207 | ||
8208 | ||
8209 | @example | |
8210 | ||
8211 | (define damped-oscillator | |
8212 | (lambda (R L C) | |
8213 | (lambda (state) | |
8214 | (let ((Vc (vector-ref state 0)) | |
8215 | (Il (vector-ref state 1))) | |
8216 | (vector (- 0 (+ (/ Vc (* R C)) (/ Il C))) | |
8217 | (/ Vc L)))))) | |
8218 | ||
8219 | (define the-states | |
8220 | (integrate-system | |
8221 | (damped-oscillator 10000 1000 .001) | |
8222 | '#(1 0) | |
8223 | .01)) | |
8224 | ||
8225 | @end example | |
8226 | ||
8227 | ||
8228 | @ignore todo | |
8229 | Show some output? | |
8230 | @end ignore | |
8231 | ||
8232 | ||
8233 | @c (letrec ((loop (lambda (s) | |
8234 | @c (newline) | |
8235 | @c (write (head s)) | |
8236 | @c (loop (tail s))))) | |
8237 | @c (loop the-states)) | |
8238 | ||
8239 | @c #(1 0) | |
8240 | @c #(0.99895054 9.994835e-6) | |
8241 | @c #(0.99780226 1.9978681e-5) | |
8242 | @c #(0.9965554 2.9950552e-5) | |
8243 | @c #(0.9952102 3.990946e-5) | |
8244 | @c #(0.99376684 4.985443e-5) | |
8245 | @c #(0.99222565 5.9784474e-5) | |
8246 | @c #(0.9905868 6.969862e-5) | |
8247 | @c #(0.9888506 7.9595884e-5) | |
8248 | @c #(0.9870173 8.94753e-5) | |
8249 | ||
8250 | @page | |
8251 | ||
8252 | @c \newpage % Put bib on it's own page (it's just one) | |
8253 | @c \twocolumn[\vspace{-.18in}]% Last bib item was on a page by itself. | |
8254 | @c \renewcommand{\bibname}{References} | |
8255 | @c @include{bib} | |
8256 | ||
8257 | @c My reference for proper reference format is: | |
8258 | @c Mary-Claire van Leunen. | |
8259 | @c {\em A Handbook for Scholars.} | |
8260 | @c Knopf, 1978. | |
8261 | @c I think the references list would look better in ``open'' format, | |
8262 | @c i.e. with the three blocks for each entry appearing on separate | |
8263 | @c lines. I used the compressed format for SIGPLAN in the interest of | |
8264 | @c space. In open format, when a block runs over one line, | |
8265 | @c continuation lines should be indented; this could probably be done | |
8266 | @c using some flavor of latex list environment. Maybe the right thing | |
8267 | @c to do in the long run would be to convert to Bibtex, which probably | |
8268 | @c does the right thing, since it was implemented by one of van | |
8269 | @c Leunen's colleagues at DEC SRC. | |
8270 | @c -- Jonathan | |
8271 | ||
8272 | @c I tried to follow Jonathan's format, insofar as I understood it. | |
8273 | @c I tried to order entries lexicographically by authors (with singly | |
8274 | @c authored papers first), then by date. | |
8275 | @c In some cases I replaced a technical report or conference paper | |
8276 | @c by a subsequent journal article, but I think there are several | |
8277 | @c more such replacements that ought to be made. | |
8278 | @c -- Will, 1991. | |
8279 | ||
8280 | @c This is just a personal remark on your question on the RRRS: | |
8281 | @c The language CUCH (Curry-Church) was implemented by 1964 and | |
8282 | @c is a practical version of the lambda-calculus (call-by-name). | |
8283 | @c One reference you may find in Formal Language Description Languages | |
8284 | @c for Computer Programming T.~B.~Steele, 1965 (or so). | |
8285 | @c -- Matthias Felleisen | |
8286 | ||
8287 | @c Rather than try to keep the bibliography up-to-date, which is hopeless | |
8288 | @c given the time between updates, I replaced the bulk of the references | |
8289 | @c with a pointer to the Scheme Repository. Ozan Yigit's bibliography in | |
8290 | @c the repository is a superset of the R4RS one. | |
8291 | @c The bibliography now contains only items referenced within the report. | |
8292 | @c -- Richard, 1996. | |
8293 | ||
8294 | @node Bibliography, Index, Example, top | |
8295 | @unnumbered Bibliography | |
8296 | ||
8297 | ||
8298 | @itemize @bullet | |
8299 | @c 999 | |
8300 | ||
8301 | ||
8302 | @item [SICP] | |
8303 | @pindex SICP | |
8304 | Harold Abelson and Gerald Jay Sussman with Julie Sussman. | |
8305 | @emph{Structure and Interpretation of Computer Programs, second edition.} | |
8306 | MIT Press, Cambridge, 1996. | |
8307 | ||
8308 | @item [Bawden88] | |
8309 | @c new | |
8310 | Alan Bawden and Jonathan Rees. | |
8311 | @pindex Bawden88 | |
8312 | Syntactic closures. | |
8313 | In @emph{Proceedings of the 1988 ACM Symposium on Lisp and | |
8314 | Functional Programming}, pages 86--95. | |
8315 | ||
8316 | @item [howtoprint] | |
8317 | @pindex howtoprint | |
8318 | Robert G. Burger and R. Kent Dybvig. | |
8319 | Printing floating-point numbers quickly and accurately. | |
8320 | In @emph{Proceedings of the ACM SIGPLAN '96 Conference | |
8321 | on Programming Language Design and Implementation}, pages 108--116. | |
8322 | ||
8323 | @item [RRRS] | |
8324 | @pindex RRRS | |
8325 | William Clinger, editor. | |
8326 | The revised revised report on Scheme, or an uncommon Lisp. | |
8327 | MIT Artificial Intelligence Memo 848, August 1985. | |
8328 | Also published as Computer Science Department Technical Report 174, | |
8329 | Indiana University, June 1985. | |
8330 | ||
8331 | @item [howtoread] | |
8332 | @c new | |
8333 | William Clinger. | |
8334 | @pindex howtoread | |
8335 | How to read floating point numbers accurately. | |
8336 | In @emph{Proceedings of the ACM SIGPLAN '90 Conference | |
8337 | on Programming Language Design and Implementation}, pages 92--101. | |
8338 | Proceedings published as @emph{SIGPLAN Notices} 25(6), June 1990. | |
8339 | ||
8340 | @item [R4RS] | |
8341 | @pindex R4RS | |
8342 | William Clinger and Jonathan Rees, editors. | |
8343 | The revised^4 report on the algorithmic language Scheme. | |
8344 | In @emph{ACM Lisp Pointers} 4(3), pages 1--55, 1991. | |
8345 | ||
8346 | @item [macrosthatwork] | |
8347 | @c new | |
8348 | William Clinger and Jonathan Rees. | |
8349 | @pindex macrosthatwork | |
8350 | Macros that work. | |
8351 | In @emph{Proceedings of the 1991 ACM Conference on Principles of | |
8352 | Programming Languages}, pages 155--162. | |
8353 | ||
8354 | @item [propertailrecursion] | |
8355 | @c new | |
8356 | William Clinger. | |
8357 | @pindex propertailrecursion | |
8358 | Proper Tail Recursion and Space Efficiency. | |
8359 | To appear in @emph{Proceedings of the 1998 ACM Conference on Programming | |
8360 | Language Design and Implementation}, June 1998. | |
8361 | ||
8362 | @item [syntacticabstraction] | |
8363 | @pindex syntacticabstraction | |
8364 | R. Kent Dybvig, Robert Hieb, and Carl Bruggeman. | |
8365 | Syntactic abstraction in Scheme. | |
8366 | @emph{Lisp and Symbolic Computation} 5(4):295--326, 1993. | |
8367 | ||
8368 | @item [Scheme311] | |
8369 | @pindex Scheme311 | |
8370 | Carol Fessenden, William Clinger, Daniel P. Friedman, and Christopher Haynes. | |
8371 | Scheme 311 version 4 reference manual. | |
8372 | Indiana University Computer Science Technical Report 137, February 1983. | |
8373 | Superseded by [Scheme84]. | |
8374 | ||
8375 | @item [Scheme84] | |
8376 | @pindex Scheme84 | |
8377 | D. Friedman, C. Haynes, E. Kohlbecker, and M. Wand. | |
8378 | Scheme 84 interim reference manual. | |
8379 | Indiana University Computer Science Technical Report 153, January 1985. | |
8380 | ||
8381 | @item [IEEE] | |
8382 | @pindex IEEE | |
8383 | @emph{IEEE Standard 754-1985. IEEE Standard for Binary Floating-Point | |
8384 | Arithmetic.} IEEE, New York, 1985. | |
8385 | ||
8386 | @item [IEEEScheme] | |
8387 | @pindex IEEEScheme | |
8388 | @emph{IEEE Standard 1178-1990. IEEE Standard for the Scheme | |
8389 | Programming Language.} IEEE, New York, 1991. | |
8390 | ||
8391 | @item [Kohlbecker86] | |
8392 | @pindex Kohlbecker86 | |
8393 | Eugene E. Kohlbecker Jr. | |
8394 | @emph{Syntactic Extensions in the Programming Language Lisp.} | |
8395 | PhD thesis, Indiana University, August 1986. | |
8396 | ||
8397 | @item [hygienic] | |
8398 | @pindex hygienic | |
8399 | Eugene E. Kohlbecker Jr., Daniel P. Friedman, Matthias Felleisen, and Bruce Duba. | |
8400 | Hygienic macro expansion. | |
8401 | In @emph{Proceedings of the 1986 ACM Conference on Lisp | |
8402 | and Functional Programming}, pages 151--161. | |
8403 | ||
8404 | @item [Landin65] | |
8405 | @pindex Landin65 | |
8406 | Peter Landin. | |
8407 | A correspondence between Algol 60 and Church's lambda notation: Part I. | |
8408 | @emph{Communications of the ACM} 8(2):89--101, February 1965. | |
8409 | ||
8410 | @item [MITScheme] | |
8411 | @pindex MITScheme | |
8412 | MIT Department of Electrical Engineering and Computer Science. | |
8413 | Scheme manual, seventh edition. | |
8414 | September 1984. | |
8415 | ||
8416 | @item [Naur63] | |
8417 | @pindex Naur63 | |
8418 | Peter Naur et al. | |
8419 | Revised report on the algorithmic language Algol 60. | |
8420 | @emph{Communications of the ACM} 6(1):1--17, January 1963. | |
8421 | ||
8422 | @item [Penfield81] | |
8423 | @pindex Penfield81 | |
8424 | Paul Penfield, Jr. | |
8425 | Principal values and branch cuts in complex APL. | |
8426 | In @emph{APL '81 Conference Proceedings,} pages 248--256. | |
8427 | ACM SIGAPL, San Francisco, September 1981. | |
8428 | Proceedings published as @emph{APL Quote Quad} 12(1), ACM, September 1981. | |
8429 | ||
8430 | @item [Pitman83] | |
8431 | @pindex Pitman83 | |
8432 | Kent M. Pitman. | |
8433 | The revised MacLisp manual (Saturday evening edition). | |
8434 | MIT Laboratory for Computer Science Technical Report 295, May 1983. | |
8435 | ||
8436 | @item [Rees82] | |
8437 | @pindex Rees82 | |
8438 | Jonathan A. Rees and Norman I. Adams IV. | |
8439 | T: A dialect of Lisp or, lambda: The ultimate software tool. | |
8440 | In @emph{Conference Record of the 1982 ACM Symposium on Lisp and | |
8441 | Functional Programming}, pages 114--122. | |
8442 | ||
8443 | @item [Rees84] | |
8444 | @pindex Rees84 | |
8445 | Jonathan A. Rees, Norman I. Adams IV, and James R. Meehan. | |
8446 | The T manual, fourth edition. | |
8447 | Yale University Computer Science Department, January 1984. | |
8448 | ||
8449 | @item [R3RS] | |
8450 | @pindex R3RS | |
8451 | Jonathan Rees and William Clinger, editors. | |
8452 | The revised^3 report on the algorithmic language Scheme. | |
8453 | In @emph{ACM SIGPLAN Notices} 21(12), pages 37--79, December 1986. | |
8454 | ||
8455 | @item [Reynolds72] | |
8456 | @pindex Reynolds72 | |
8457 | John Reynolds. | |
8458 | Definitional interpreters for higher order programming languages. | |
8459 | In @emph{ACM Conference Proceedings}, pages 717--740. | |
8460 | ACM, | |
8461 | @ignore todo | |
8462 | month? | |
8463 | @end ignore | |
8464 | 1972. | |
8465 | ||
8466 | @item [Scheme78] | |
8467 | @pindex Scheme78 | |
8468 | Guy Lewis Steele Jr. and Gerald Jay Sussman. | |
8469 | The revised report on Scheme, a dialect of Lisp. | |
8470 | MIT Artificial Intelligence Memo 452, January 1978. | |
8471 | ||
8472 | @item [Rabbit] | |
8473 | @pindex Rabbit | |
8474 | Guy Lewis Steele Jr. | |
8475 | Rabbit: a compiler for Scheme. | |
8476 | MIT Artificial Intelligence Laboratory Technical Report 474, May 1978. | |
8477 | ||
8478 | @item [CLtL] | |
8479 | @pindex CLtL | |
8480 | Guy Lewis Steele Jr. | |
8481 | @emph{Common Lisp: The Language, second edition.} | |
8482 | Digital Press, Burlington MA, 1990. | |
8483 | ||
8484 | @item [Scheme75] | |
8485 | @pindex Scheme75 | |
8486 | Gerald Jay Sussman and Guy Lewis Steele Jr. | |
8487 | Scheme: an interpreter for extended lambda calculus. | |
8488 | MIT Artificial Intelligence Memo 349, December 1975. | |
8489 | ||
8490 | @item [Stoy77] | |
8491 | @pindex Stoy77 | |
8492 | Joseph E. Stoy. | |
8493 | @emph{Denotational Semantics: The Scott-Strachey Approach to | |
8494 | Programming Language Theory.} | |
8495 | MIT Press, Cambridge, 1977. | |
8496 | ||
8497 | @item [TImanual85] | |
8498 | @pindex TImanual85 | |
8499 | Texas Instruments, Inc. | |
8500 | TI Scheme Language Reference Manual. | |
8501 | Preliminary version 1.0, November 1985. | |
8502 | ||
8503 | @end itemize | |
8504 | ||
8505 | ||
8506 | ||
8507 | ||
8508 | @page | |
8509 | ||
8510 | ||
8511 | @c Adjustment to avoid having the last index entry on a page by itself. | |
8512 | @c \addtolength{\baselineskip}{-0.1pt} | |
8513 | ||
8514 | @node Index, , Bibliography, top | |
8515 | @unnumbered Alphabetic index of definitions of concepts, keywords, and procedures | |
8516 | ||
8517 | ||
8518 | ||
8519 | The principal entry for each term, procedure, or keyword is listed | |
8520 | first, separated from the other entries by a semicolon. | |
8521 | ||
8522 | @sp 6 | |
8523 | ||
8524 | @unnumberedsec Concepts | |
8525 | @printindex cp | |
8526 | @page | |
8527 | @unnumberedsec Procedures | |
8528 | @printindex fn | |
8529 | ||
8530 | @ifinfo | |
8531 | @unnumberedsec References | |
8532 | @printindex pg | |
8533 | @end ifinfo | |
8534 | ||
8535 | ||
8536 | @contents | |
8537 | @bye |