0abf4dfc4871ddb754e8fc4025f2acc9678de879
[mudman.git] / language.md
1 % The Muddle Programming Language
2 % Greg Pfister
3   S. W. Galley
4   et al.
5 % 1979
6
7 MIT Technical Report 293
8
9 Laboratory for Computer Science\
10 Massachusetts Institute of Technology\
11 545 Technology Square\
12 Cambridge, Massachusetts 02139
13
14 Copyright
15 =========
16
17 This document is free of known copyright restrictions.
18
19 Abstract
20 ========
21
22 The Muddle programming language began existence in late 1970 (under
23 the name Muddle) as a successor to Lisp (Moon, 1974), a candidate
24 vehicle for the Dynamic Modeling System, and a possible base for
25 implementation of Planner (Hewitt, 1969). The original design goals
26 included an interactive integrated environment for programming,
27 debugging, loading, and editing: ease in learning and use; facilities
28 for structured, modular, shared programs; extensibility of syntax,
29 data types and operators: data-type checking for debugging and
30 optional data-type declarations for compiled efficiency; associative
31 storage, coroutining, and graphics. Along the way to reaching those
32 goals, it developed flexible input/output (including the ARPA
33 Network), and flexible interrupt and signal handling. It now serves as
34 a base for software prototyping, research, development, education, and
35 implementation of the majority of programs at MIT-DMS: a library of
36 sharable modules, a coherent user interface, special research
37 projects, autonomous daemons, etc.
38
39 This document was originally intended to be a simple low-level
40 introduction to Muddle. It has, however, acquired a case of
41 elephantiasis and now amounts to a discursive description of the whole
42 interpreter, as realized in Muddle release numbers 55 (ITS version)
43 and 105 (Tenex and Tops-20 versions). (Significant changes from the
44 previous edition are marked in the margin.) A low-level introduction
45 may still be had by restricting one's attention to specially-marked
46 sections only. The scope of the document is confined as much as
47 possible to the interpreter itself. Other adjuncts (compiler,
48 assembler, pre-loaded user programs, library) are mentioned as little
49 as possible, despite their value in promoting the language seen by a
50 user from "basic survival" to "comfortable living". Indeed, Muddle
51 could not fulfill the above design goals without the compiler,
52 assembler, structure editor, control-stack printer, context printer,
53 pretty-printer, dynamic loader, and library system -- all of which are
54 not part of the interpreter but programs written in Muddle and
55 symbiotic with one another. Further information on these adjuncts can
56 be found in Lebling's (1979) document.
57
58 Acknowledgements
59 ----------------
60
61 I was not a member of the original group which labored for two years
62 in the design and initial implementation of Muddle; that group was
63 composed principally of Gerald Sussman, Carl Hewit, Chris Reeve, Dave
64 Cressey, and later Bruce Daniels. I would therefore like to take this
65 opportunity to thank my Muddle mentors, chiefly Chris Reeve and Bruce
66 Daniels, for remaining civil through several months of verbal
67 badgering. I believe that I learned more than "just another
68 programming language" in learning Muddle, and I am grateful for this
69 opportunity to pass on some of that knowledge. What I cannot pass on
70 is the knowledge gained by using Muddle as a system; that I can only
71 ask you to share.
72
73 For editing the content of this document and correcting some
74 misconceptions, I would like to thank Chris Reeve, Bruce Daniels, and
75 especially Gerald Sussman, one of whose good ideas I finally did use.
76
77 Greg Pfister\
78 December 15, 1972
79
80 Since Greg left the fold, I have taken up the banner and updated his
81 document. The main sources for small revisions have been the on-line
82 file of changes to Muddle, for which credit goes to Neal Ryan as well
83 as Reeve and Daniels, and the set of on-line abstracts for interpreter
84 Subroutines, contributed by unnamed members of the Programming
85 Technology Division. Some new sections were written almost entirely by
86 others: Dave Lebling wrote chapter 14 and appendix 3, Jim Michener
87 section 14.3, Reeve chapter 19 and appendix 1, Daniels and Reeve
88 appendix 2. Brian Berkowitz section 22.7, Tak To section 17.2.2, and
89 Ryan section 17.1.3. Sue Pitkin did the tedious task of marking
90 phrases in the manuscript for indexing. Pitts Jarvis and Jack Haverty
91 advised on the use of PUB and the XGP. Many PTD people commented
92 helpfully on a draft version.
93
94 My task has been to impose some uniformity and structure on these
95 diverse resources (so that the result sounds less like a dozen hackers
96 typing at a dozen terminals for a dozen days) and to enjoy some of the
97 richness of Muddle from the inside. I especially thank Chris Reeve
98 ("the oracle") for the patience to answer questions and resolve
99 doubts, as he no doubt as done innumerable times before.
100
101 S. W. Galley\
102 May 23, 1979
103
104 This work was supported by the Advanced Research Projects Agency of
105 the Department of Defense and was monitored by the Office of Naval
106 Research under contract N00014-75-C-0661.
107
108 This document was prepared using [the PUB
109 system](http://www.nomodes.com/pub_manual.html) (originally from the
110 Stanford Artificial Intelligence Laboratory) and printed on the Xerox
111 Graphics Printer of the M.I.T. Artificial Intelligence Laboratory.
112
113 Foreword
114 --------
115
116 Trying to explain Muddle to an uninitiate is somewhat like trying to
117 untie a Gordian knot. Whatever topic one chooses to discuss first,
118 full discussion of it appears to imply discussion of everything else.
119 What follows is a discursive presentation of Muddle in an order
120 apparently requiring the fewest forward references. It is not perfect
121 in that regard; however, if you are patient and willing to accept a
122 few, stated things as "magic" until they can be explained better, you
123 will probably not have too many problems understanding what is going
124 on.
125
126 There are no "practice problems"; you are assumed to be learning
127 Muddle for some purpose, and your work in achieving that purpose will
128 be more useful and motivated than artificial problems. In several
129 cases, the examples contain illustrations of important points which
130 are not covered in the text. Ignore examples as your peril.
131
132 This document does not assume knowledge of any specific programming
133 language on the \[sic\] your part. However, "computational literacy"
134 is assumed: you should have written at least one program before. Also
135 very little familiarity is assumed with the interactive time-sharing
136 operating systems under which Muddle runs -- ITS, Tenex, and Tops-20
137 -- namely just file and user naming conventions.
138
139 ### Notation
140
141 Sections marked \[1\] are recommended for any uninitiate's first
142 reading, in lieu of a separate introduction for Muddle. \[On first
143 reading, text within brackets like these should be ignored.\]
144
145 Most specifically indicated examples herein are composed of pairs of
146 lines. The first line of a pair, the input, always ends in `$` (which
147 is how the ASCII character `ESC` is represented, and which always
148 represents it). The second line is the result of Muddle's groveling
149 over the first. If you were to type all the first lines at Muddle, it
150 would respond with all the second lines. (More exactly, the "first
151 line" is one or more objects in Muddle followed by `$`, and the
152 "second line" is everything up to the next "first line".)
153
154 Anything which is written in the Muddle language or which is typed on
155 a computer terminal appears herein in a fixed width font, as in
156 `ROOT`. A metasyntactic variable -- something to be replaced in actual
157 use by something else -- appears as *radix:fix*, in an italic font;
158 often the variable will have both a meaning and a data type (as here),
159 but sometimes one of those will be ommitted, for obvious reasons.
160
161 An ellipsis (...) indicates that something uninteresting has been
162 omitted. The character `^` means that the following character is to be
163 "controllified": it is usually typed by holding down a terminal's
164 `CTRL` key and striking the other key.
165
166 Chapter 1. Basic Introduction
167 =============================
168
169 The purpose of this chapter is to provide you with that minimal amount
170 of information needed to experiment with Muddle while reading this
171 document. It is strongly recommended that you do experiment,
172 especially upon reaching chapter 5 (Simple Functions).
173
174 1.1. Loading Muddle \[1\]
175 -------------------------
176
177 First, catch your rabbit. Somehow get the interpreter running -- the
178 program in the file `SYS:TS.Muddle` in the ITS version or
179 `SYS:Muddle.SAV` in the Tenex version or `SYS:Muddle.EXE` in the
180 Tops-20 version. The interpreter will first type out some news
181 relating to Muddle, if any, then type
182
183     LISTENING-AT-LEVEL 1 PROCESS 1
184
185 and then wait for you to type something.
186
187 The program which you are now running is an interpreter for the
188 language Muddle. **All** it knows how to do is interpret Muddle
189 expressions. There is no special "command language"; you communicate
190 with the program -- make it do things for you -- by actually typing
191 legal Muddle expressions, which it then interprets. **Everything** you
192 can do at a terminal can be done in a program, and vice versa, in
193 exactly the same way.
194
195 The program will be referred to as just "Muddle" (or "the
196 interpreter") from here on. There is no ambiguity, since the program
197 is just an incarnation of the concept "Muddle".
198
199 1.2. Typing \[1\]
200 -----------------
201
202 Typing a character at Muddle normally just causes that character to be
203 echoed (printed on your terminal) and remembered in a buffer. The only
204 characters for which this is normally not true act as follows:
205
206 Typing `$` (`ESC`) causes Muddle to echo dollar-sign and causes the
207 contents of the buffer (the characters which you've typed) to be
208 interpreted as an expression(s) in Muddle. When this interpretation is
209 done, the result will be printed and Muddle will wait for more typing.
210 `ESC` will be represented by the glyph `$` in this document.
211
212 Typing the rubout character (`DEL` in the ITS and Top-20 versions,
213 `CTRL`+`A` in the Tenex version) causes the last character in the
214 buffer -- the one most recently typed -- to be thrown away (deleted).
215 If you now immediately type another rubout, once again the last
216 character is deleted -- namely the second most recently typed. Etc.
217 The character deleted is echoed, so you can see what you're doing. On
218 some "display" terminals, rubout will "echo" by causing the deleted
219 character to disappear. If no characters are in the buffer, rubout
220 echoes as a carriage-return line-feed.
221
222 Typing `^@` (`CTRL`+`@`) deletes everything you have typed since the
223 last `$`, and prints a carriage-return line-feed.
224
225 Typing `^D` (`CTRL`+`D`) causes the current input buffer to be typed
226 back out at you. This allows you to see what you really have, without
227 the confusing re-echoed characters produced by rubout.
228
229 Typing `^L` (`CTRL`+`L`) produces the same effect as typing `^D`,
230 except that, if your terminal is a "display" terminal (for example,
231 IMLAC, ARDS, Datapoint), it firsts clears the screen.
232
233 Typing `^G` (`CTRL`+`G`) causes Muddle to stop whatever it is doing
234 and act as if an error had occurred ([section
235 1.4](#14-errors-simple-considerations-1)). `^G` is generally most
236 useful for temporary interruptions to check the progress of a
237 computation. `^G` is "reversible" -- that is, it does not destroy any
238 of the "state" of the computation it interrupts. To "undo" a `^G`,
239 type the characters
240
241     <ERRET T>$
242
243 (This is discussed more fully far below, in section 16.4.)
244
245 Typing `^S` (`CTRL`+`S`) causes Muddle to **throw away** what it is
246 currently doing and return a normal "listening" state. (In the Tenex
247 and Tops-20 versions, `^O` also should have the same effect.) `^S` is
248 generally most useful for aborting infinite loops and similar terrible
249 things. `^S` **destroys** whatever is going on, and so it is **not**
250 reversible.
251
252 Most expressions in Muddle include "brackets" (generically meant) that
253 must be correctly paired and nested. If you end your typing with the
254 pair of characters `!$` (`!`+`ESC`), all currently unpaired brackets
255 (but not double-quotes, which bracket strings of characters) will
256 automatically be paired and interpretation will start. Without the
257 `!`, Muddle will just sit there waiting for you to pair them. If you
258 have improperly nested parentheses, brackets, etc., within the
259 expression you typed, an error will occur, and Muddle will tell you
260 what is wrong.
261
262 Once the brackets are properly paired, Muddle will immediately echo
263 carriage-return and line-feed, and the next thing it prints will be
264 the result of the evaluation. Thus, if a plain `$` is not so echoed,
265 you have some expression unclosed. In that case, if you have not typed
266 any characters beyond the `$`, you can usually rub out the `$` and
267 other characters back to the beginning of the unclosed expression.
268 Otherwise, what you have typed is beyond the help of rubout and `^@`;
269 if you want to abort it, use `^S`.
270
271 Muddle accepts and distinguishes between upper and lower case. All
272 "built-in functions" must be referenced in upper case.
273
274 1.3. Loading a File \[1\]
275 -------------------------
276
277 If you have a program in Muddle that you have written as an ASCII file
278 on some device, you can "load" it by typing
279
280     <FLOAD file>$
281
282 where *file* is the name of the file, in standard operating-system
283 syntax, enclosed in "s (double-quotes). Omitted parts of the file name
284 are taken by default from the file name `DSK: INPUT >` (in the ITS
285 version) or `DSK: INPUT.MUD` (in the Tenex and Tops-20 versions) in
286 the current disk directory.
287
288 Once you type `$`, Muddle will process the text in the file (including
289 `FLOAD`s) exactly as if you had typed it on a terminal and followed it
290 with `$`, except that "values" produced by the computations are not
291 printed. When Muddle is finished processing the file, it will print
292 `DONE`.
293
294 When Muddle starts running, it will `FLOAD` the file `MUDDLE INIT`
295 (ITS version) or `MUDDLE.INIT` (Tenex and Tops-20 versions), if it
296 exists.
297
298 1.4. Errors â€” Simple Considerations \[1\]
299 -----------------------------------------
300
301 When Muddle decides for some reason that something is wrong, the
302 standard sequence of evaluation is interrupted and an error function
303 is called. This produces the following terminal output:
304
305     *ERROR*
306     often-hyphenated-reason
307     function-in-which-error-occurred
308     LISTENING-AT-LEVEL integer PROCESS integer
309
310 You can now interact with Muddle as usual, typing expressions and
311 having them evaluated. There exist facilities (built-in functions)
312 allowing you to find out what went wrong, restart, or abandon whatever
313 was going on. In particular, you can recover from an error -- that is,
314 undo everything but side effects and return to the initial typing
315 phase -- by typing the following first line, to which Muddle will
316 respond with the second line:
317
318     <ERRET>$
319     LISTENING-AT-LEVEL 1 PROCESS 1
320
321 If you type the following first line while still in the error state
322 (before `<ERRET>`), Muddle will print, as shown, the arguments (or
323 "parameters or "inputs" or "independent variables") which gave
324 indigestion to the unhappy function:
325
326     <ARGS <FRAME <FRAME>>>$
327     [ arguments to unhappy function ]
328
329 This will be explained by and by.
330
331 Chapter 2. Read, Evaluate, and Print
332 ====================================
333
334 2.1. General \[1\]
335 ------------------
336
337 Once you type `$` and all brackets are correctly paired and nested,
338 the current contents of the input buffer go through processing by
339 three functions successively: first `READ`, which passes its output to
340 `EVAL` ("evaluate"), which passes its output to `PRINT`, whose output
341 is typed on the terminal.
342
343 \[Actually, the sequence is more like `READ`, `CRLF`, `EVAL`, `PRIN1`,
344 `CRLF` (explained in chapter 11); Muddle gives you a carriage-return
345 line-feed when the `READ` is complete, that is, when all brackets are
346 paired.\]
347
348 Functionally:
349
350 -   `READ`: printable representations â†’ Muddle objects
351 -   `EVAL`: Muddle objects â†’ Muddle objects
352 -   `PRINT`: Muddle objects â†’ printable representations
353
354 That is, `READ` takes ASCII text, such as is typed in at a terminal,
355 and creates the Muddle objects represented by that text. `PRINT` takes
356 Muddle objects, creates ASCII text representations of them, and types
357 them out. `EVAL`, which is the really important one, performs
358 transformations on Muddle objects.
359
360 2.2. Philosophy (TYPEs) \[1\]
361 -----------------------------
362
363 In a general sense, when you are interacting with Muddle, you are
364 dealing with a world inhabited only by a particular set of objects:
365 Muddle objects.
366
367 Muddle objects are best considered as abstract entities with abstract
368 properties. The properties of a particular Muddle object depend on the
369 class of Muddle objects to which it belongs. This class is the `TYPE`
370 of the Muddle object. Every Muddle object has a `TYPE`, and every
371 `TYPE` has its own peculiarities. There are many different `TYPE`s in
372 Muddle; they will gradually be introduced below, but in the meantime
373 here is a representative sample: `SUBR` (the `TYPE` of `READ`, `EVAL`,
374 and `PRINT`), `FSUBR`, `LIST`, `VECTOR`, `FORM`, `FUNCTION`, etc.
375 Since every object has a `TYPE`, one often abbreviates "an object of
376 `TYPE` *type*" by saying "a *type*".
377
378 The laws of the Muddle world are defined by `EVAL`. In a very real
379 sense, `EVAL` is the only Muddle object which "acts", which "does
380 something". In "acting", `EVAL` is always "following the directions"
381 of some Muddle object. Every Muddle object should be looked upon as
382 supplying a set of directions to `EVAL`; what these directions are
383 depends heavily on the `TYPE` of the Muddle object.
384
385 Since `EVAL` is so ever-present, an abbreviation is in order:
386 "evaluates to *something*" or "`EVAL`s to *something*" should be taken
387 as an abbreviation for "when given to `EVAL`, causes `EVAL` to return
388 *something*".
389
390 As abstract entities, Muddle objects are, of course, not "visible".
391 There is, however, a standard way of representing abstract Muddle
392 objects in the real world. The standard way of representing any given
393 `TYPE` of Muddle object will be given below when the `TYPE` is
394 introduced. These standard representations are what `READ`
395 understands, and what `PRINT` produces.
396
397 2.3. Example (TYPE FIX) \[1\]
398 -----------------------------
399
400     1$
401     1
402
403 The following has occurred:
404
405 First, `READ` recognized the character `1` as the representation for
406 an object of `TYPE` `FIX`, in particular the one which corresponds to
407 the integer one. (`FIX` means integer, because the decimal point is
408 understood always to be in a fixed position: at the right-hand end.)
409 `READ` built the Muddle object corresponding to the decimal
410 representation typed, and returned it.
411
412 Then `EVAL` noted that its input was of `TYPE` `FIX`. An object of
413 `TYPE` `FIX` evaluates to itself, so `EVAL` returned its input
414 undisturbed.
415
416 Then `PRINT` saw that its input was of `TYPE` `FIX`, and printed on
417 the terminal the decimal character representation of the corresponding
418 integer.
419
420 2.4. Example (TYPE FLOAT) \[1\]
421 -------------------------------
422
423     1.0$
424     1.0
425
426 What went on was entirely analogous to the preceding example, except
427 that the Muddle object was of `TYPE` `FLOAT`. (`FLOAT` means a real
428 number (of limited precision), because the decimal point can float
429 around to any convenient position: an internal exponent part tells
430 where it "really" belongs.)
431
432 2.5. Example (TYPE ATOM, PNAME) \[1\]
433 -------------------------------------
434
435     GEORGE$
436     GEORGE
437
438 This time a lot more has happened.
439
440 `READ` noted that what was typed had no special meaning, and therefore
441 assumed that it was the representation of an identifier, that is, an
442 object of `TYPE` `ATOM`. ("Atom" means more or less *indivisible*.)
443 `READ` therefore attempted to look up the representation in a table it
444 keeps for such purposes \[a `LIST` of `OBLISTS`, available as the
445 local value of the `ATOM` `OBLIST`\]. If `READ` finds an `ATOM` in its
446 table corresponding to the representation, that `ATOM` is returned as
447 `READ`'s value. If `READ` fails in looking up, it creates a new
448 `ATOM`, puts it in the table with the representation read \[`INSERT`
449 into `<1 .OBLIST>` usually\], and returns the new `ATOM`. Nothing
450 which could in any way be referenced as a legal "value" is attached to
451 the new `ATOM`. The initially-typed representation of an `ATOM`
452 becomes its `PNAME`, meaning its name for `PRINT`. One often
453 abbreviates "object of `TYPE` `ATOM` with `PNAME` *name*" by saying
454 "`ATOM` *name*".
455
456 `EVAL`, given an `ATOM`, returned just that `ATOM`.
457
458 `PRINT`, given an `ATOM`, typed out its `PNAME`.
459
460 At the end of this chapter, the question "what is a legal `PNAME`"
461 will be considered. Further on, the methods used to attach values to
462 `ATOM`s will be described.
463
464 2.6. FIXes, FLOATs, and ATOMs versus READ: Specifics
465 ----------------------------------------------------
466
467 ### 2.6.1. READ and FIXed-point Numbers
468
469 `READ` considers any grouping of characters which are solely digits to
470 be a `FIX`, and the radix of the representation is decimal by default.
471 A `-` (hyphen) immediately preceding such a grouping represents a
472 negative `FIX`. The largest `FIX` representable on the PDP-10 is two
473 to the 35th power minus one, or 34,359,738,367 (decimal): the smallest
474 is one less than the negative of that number. If you attempt to type
475 in a `FIX` outside that range, `READ` converts it to a `FLOAT`; if a
476 program you write attempts to produce a `FIX` outside that range, an
477 overflow error will occur (unless it is disabled).
478
479 The radix used by `READ` and `PRINT` is changeable by the user;
480 however, there are two formats for representations of `FIX`es which
481 cause `READ` to use a specified radix independent of the current one.
482 These are as follows:
483
484 1.  If a group of digits is immediately followed by a period (`.`),
485     `READ` interprets that group as the decimal representation of a
486     `FIX`. For example, `10.` is always interpreted by `READ` as the
487     decimal representation of ten.
488
489 2.  If a group of digits is immediately enclosed on both sides with
490     asterisks (`*`), `READ` interprets that group as the octal
491     representation of a `FIX`. For example, `*10*` is always
492     interpreted by `READ` as the octal representation of eight.
493
494 ### 2.6.2. READ and PRINT versus FLOATing-point Numbers
495
496 `PRINT` can produce, and `READ` can understand, two different formats
497 for objects of `TYPE` `FLOAT`. The first is "decimal-point" notation,
498 the second is "scientific" notation. Decimal radix is always used for
499 representations of `FLOAT`s.
500
501 "Decimal-point" notation for a `FLOAT` consists of an arbitrarily long
502 string of digits containing one `.` (period) which is followed by at
503 least one digit. `READ` will make a `FLOAT` out of any such object,
504 with a limit of precision of one part in 2 to the 27th power.
505
506 "Scientific" notation consists of:
507
508 1.  a number,
509
510 2.  immediately followed by `E` or `e` (upper or lower case letter E),
511
512 3.  immediately followed by an exponent,
513
514 where a "number" is an arbitrarily long string of digits, with or
515 without a decimal point (see following note): an an "exponent" is up
516 to two digits worth of `FIX`. This notation represents the "number" to
517 the "exponent" power of ten. Note: if the "number" as above would by
518 itself be a `FIX`, and if the "exponent" is positive, and if the
519 result is within the allowed range of `FIX`es, then the result will be
520 a `FIX`. For example, `READ` understands `10E1` as `100` (a `FIX`),
521 but `10E-1` as `1.0000000` (a `FLOAT`).
522
523 The largest-magnitude `FLOAT` which can be handled without overflow is
524 `1.7014118E+38` (decimal radix). The smallest-magnitude `FLOAT` which
525 can be handled without underflow is `.14693679E-38`.
526
527 ### 2.6.3. READ and PNAMEs
528
529 The question "what is a legal `PNAME`?" is actually not a reasonable
530 one to ask: **any** non-empty string of **arbitrary** characters can
531 be the `PNAME` of an `ATOM`. However, some `PNAME`s are easier to type
532 to `READ` than others. But even the question "what are easily typed
533 `PNAME`s?" is not too reasonable, because: `READ` decides that a group
534 of characters is a `PNAME` by **default**; if it can't possibly be
535 anything else, it's a `PNAME`. So, the rules governing the
536 specification of `PNAME`s are messy, and best expressed in terms of
537 what is not a `PNAME`. For simplicity, you can just consider any
538 uninterrupted group of upper- and lower-case letters and (customarily)
539 hyphens to be a `PNAME`; that will always work. If you neither a
540 perfectionist nor a masochist, skip to the next chapter.
541
542 #### 2.6.3.1. Non-PNAMEs
543
544 A group of characters is **not** a `PNAME` if:
545
546 1.  It represents a `FLOAT` or a `FIX`, as described above -- that is,
547     it is composed wholly of digits, or digits and a single `.`
548     (period) or digits and a `.` and the letter `E` or `e` (with
549     optional minus signs in the right places).
550
551 2.  It begins with a `.` (period).
552
553 3.  It contains -- if typed interactively -- any of the characters
554     which have special interactive effects: `^@`, `^D`, `^L`, `^G`,
555     `^O`, `$` (`ESC`), rubout.
556
557 4.  It contains a format character -- space, carriage-return,
558     line-feed, form-feed, horizontal tab, vertical tab.
559
560 5.  It contains a `,` (comma) or a `#` (number sign) or a `'` (single
561     quote) or a `;` (semicolon) or a `%` (percent sign).
562
563 6.  It contains any variety of bracket -- `(` or `)` or `[` or `]` or
564     `<` or `>` or `{` or `}` or `"`.
565
566 In addition, the character `\` (backslash) has a special
567 interpretation, as mentioned below. Also the pair of characters `!-`
568 (exclamation-point hyphen) has an extremely special interpretation,
569 which you will reach at chapter 15.
570
571 The characters mentioned in cases 4 through 6 are "separators" -- that
572 is, they signal to `READ` that whatever it was that the preceding
573 characters represented, it's done now. They can also indicate the
574 start of a new object's representation (all the opening "brackets" do
575 just that).
576
577 #### 2.6.3.2. Examples
578
579 The following examples are not in the "standard format" of "*line
580 typed in*`$` *result printed*", because they are not, in some cases,
581 completed objects; hence, `READ` would continue waiting for the
582 brackets to be closed. In other cases, they will produce errors during
583 `EVAL`uation if other -- currently irrelevant -- conditions are not
584 met. Instead, the right-hand column will be used to state just what
585 `READ` thought the input in the left-hand column really was.
586
587   ------------------------------------------------------------------------------------
588   Input                       Explanation
589   --------------------------- --------------------------------------------------------
590   `ABC$`                      an `ATOM` of `PNAME` `ABC`
591
592   `abc$`                      an `ATOM` of `PNAME` `abc`
593
594   `ARBITRARILY-LONG-PNAME$`   an `ATOM` of `PNAME` `ARBITRARILY-LONG-PNAME`
595
596   `1.2345$`                   a `FLOAT`, `PRINT`ed as `1.2345000`
597
598   `1.2.345$`                  an `ATOM` of `PNAME` `1.2.345`
599
600   `A.or.B$`                   a `ATOM` of `PNAME` `A.or.B`
601
602   `.A.or.B$`                  not an `ATOM`, but (as explained later) a `FORM`
603                               containing an `ATOM` of `PNAME` `A.or.B`.
604
605   `MORE THAN ONE$`            three `ATOM`s, with `PNAME`s `MORE`, and `THAN`, and
606                               `ONE`.
607
608   `ab(cd$`                    an `ATOM` of `PNAME` `ab`, followed by the start of
609                               something else (The something else will contain an
610                               `ATOM` of `PNAME` beginning `cd.`)
611
612   `12345A34$`                 an `ATOM` of `PNAME` `12345A35` (If the A had been an E,
613                               the object would have been a `FLOAT`.)
614   ------------------------------------------------------------------------------------
615
616 #### 2.6.3.3. Â (Backslash) in ATOMs
617
618 If you have a strange, uncontrollable compulsion to have what were
619 referred to as "separators" above as part of the `PNAME`s of your
620 `ATOM`s, you can do so by preceding them with the character `\`
621 (backslash). `\` will also magically turn an otherwise normal `FIX` or
622 `FLOAT` into an `ATOM` if it appears amongst the digits. In fact,
623 backslash in front of **any** character changes it from something
624 special to "just another character" (including the character `\`). It
625 is an escape character.
626
627 When `PRINT` confronts an `ATOM` which had to be backslashed in order
628 to be an `ATOM`, it will dutifully type out the required `\`s. They
629 will not, however, necessarily be where you typed them; they will
630 instead be at those positions which will cause `READ` the least grief.
631 For example, `PRINT` will type out a `PNAME` which consists wholly of
632 digits by first typing a `\` and then typing the digits - no matter
633 where you originally typed the `\` (or `\`s).
634
635 #### 2.6.3.4. Examples of Awful ATOMs
636
637 The following examples illustrate the amount of insanity that can be
638 perpetrated by using `\`. The format of the examples is again
639 non-standard, this time not because anything is unfinished or in
640 error, but because commenting is needed: `PRINT` doesn't do it full
641 justice.
642
643   -------------------------------------------------------------------------------
644   Input                    Explanation
645   ------------------------ ------------------------------------------------------
646   `a\ one\ and\ a\ two$`   one `ATOM`, whose `PNAME` has four spaces in it
647
648   `1234\56789$`            an `ATOM` of `PNAME` `123456789`, which `PRINT`s as
649                            `\1233456789`
650
651   `123\ $`                 an `ATOM` of `PNAME` `123space`, which `PRINT`s as
652                            `\123\`, with a space on the end
653
654   `\\$`                    an `ATOM` whose `PNAME` is a single backslash
655   -------------------------------------------------------------------------------
656
657 Chapter 3. Built-in Functions
658 =============================
659
660 3.1. Representation \[1\]
661 -------------------------
662
663 Up to this point, all the objects we have been concerned with have had
664 no internal structure discernible in Muddle. While the characteristics
665 of objects with internal structure differ greatly, the way `READ` and
666 `PRINT` handle them is uniform, to wit:
667
668 -   `READ`, when applied to the representation of a structured object,
669     builds and returns an object of the indicated `TYPE` with elements
670     formed by applying `READ` to each of their representations in
671     turn.
672
673 -   `PRINT`, when applied to a structured object, produces a
674     representation of the object, with its elements represented as
675     `PRINT` applied to each of them in turn.
676
677 A Muddle object which is used to represent the application of a
678 function to its arguments is an argument of `TYPE` `FORM`. Its printed
679 representation is
680
681     < func arg-1 arg-2 ... arg-N >
682
683 where *func* is an object which designates the function to be applied,
684 and *arg-1* through *arg-N* are object which designate the arguments
685 or "actual parameters" or "inputs". A `FORM` is just a structured
686 object which is stored and can be manipulated like a `LIST` (its
687 "primitive type" is `LIST` -- chapter 6). The application of the
688 function to the arguments is done by `EVAL`. The usual meaning of
689 "function" (uncapitalized) in this document will be anything
690 applicable to arguments.
691
692 3.2. Evaluation \[1\]
693 ---------------------
694
695 `EVAL` applied to a `FORM` acts as if following these directions:
696
697 First, example the *func* (first element) of the `FORM`. If it is an
698 `ATOM`, look at its "value" (global or local, in that order -- see
699 next chapter). If it is not an `ATOM`, `EVAL` it and look at the
700 result of the evaluation. If what you are looking at is not something
701 which can be applied to arguments, complain (via the `ERROR`
702 function). Otherwise, inspect what you are looking at and follow its
703 directions in evaluating or not evaluating the arguments (chapters 9
704 and 19) and then "apply the function" -- that is, `EVAL` the body of
705 the object gotten from *func*.
706
707 3.3. Built-in Functions (TYPE SUBR, TYPE FSUBR) \[1\]
708 -----------------------------------------------------
709
710 The built-in functions of Muddle come in two varieties: those which
711 have all their arguments `EVAL`ed before operating on them (`TYPE`
712 `SUBR`, for "subroutine", pronounced "subber") and those which have
713 none of their arguments `EVAL`ed (`TYPE` `FSUBR`, historically from
714 Lisp (Moon, 1974), pronounced "effsubber"). Collectively they will be
715 called `F/SUBR`s, although that term is not meaningful to the
716 interpreter. See appendix 2 for a listing of all `F/SUBR`s and short
717 descriptions. The term "Subroutine" will be used herein to mean both
718 `F/SUBR`s and compiled user programs (`RSUBR`s and `RSUBR-ENTRY`s --
719 chapter 19).
720
721 Unless otherwise stated, **every** Muddle built-in Subroutine is of
722 `TYPE` **`SUBR`**. Also, when it is stated that an argument of a
723 `SUBR` must be of a particular `TYPE`, note that this means that
724 `EVAL` of what is there must be of the particular `TYPE`.
725
726 Another convenient abbreviation which will be used is "the `SUBR`
727 *pname*" in place of "the `SUBR` which is initially the 'value' of the
728 `ATOM` of `PNAME` *pname*". "The `FSUBR` *pname*" will be used with a
729 similar meaning.
730
731 3.4. Examples (+ and FIX; Arithmetic) \[1\]
732 -------------------------------------------
733
734     <+ 2 4 6>$
735     12
736
737 The `SUBR` `+` adds numbers. Most of the usual arithmetic functions
738 are Muddle `SUBR`s: `+`, `-`, `*`, `/`, `MIN`, `MAX`, `MOD`, `SIN`,
739 `COS`, `ATAN`, `SQRT`, `LOG`, `EXP`, `ABS`. (See appendix 2 for short
740 descriptions of these.) All except `MOD`, which wants `FIX`es, are
741 indifferent as to whether their arguments are `FLOAT` or `FIX` or a
742 mixture. In the last case they exhibit "contagious `FLOAT`ing": one
743 argument of `TYPE` `FLOAT` forces the result to be of `TYPE` `FLOAT`.
744
745     <FIX 1.0>$
746     1
747
748 The `SUBR` `FIX` explicitly returns a `FIX`ed-point number
749 corresponding to a `FLOAT`ing-point number. `FLOAT` does the opposite.
750
751     <+ 5 <* 2 3>>$
752     11
753     <SQRT <+ <* 3 3> <* 4 4>>>$
754     5.0
755     <- 5 3 2>$
756     0
757     <- 5>$
758     -5
759     <MIN 1 2.0>$
760     1.0
761     </ 11 7 2.0>$
762     0.5
763
764 Note this last result: the division of two `FIX`es gives a `FIX` with
765 truncation, not rounding, of the remainder: the intermediate result
766 remains a `FIX` until a `FLOAT` argument is encountered.
767
768 3.5. Arithmetic Details
769 -----------------------
770
771 `+`, `-`, `*`, `/`, `MIN`, and `MAX` all take any number of arguments,
772 doing the operation with the first argument and the second, then with
773 that result and the third argument, etc. If called with no arguments,
774 each returns the identity for its operation (`0`, `0`, `1`, `1`, the
775 greatest `FLOAT`, and the least `FLOAT`, respectively); if called with
776 one argument, each acts as if the identity and the argument has been
777 supplied. They all will cause an overflow or underflow error if any
778 result, intermediate or final, is too large or too small for the
779 machine's capacity. (That error can be disabled if necessary --
780 section 16.9).
781
782 One arithmetic function that always requires some discussion is the
783 pseudo-random-number generator. Muddle's is named `RANDOM`, and it
784 always returns a `FIX`, uniformly distributed over the whole range of
785 `FIX`es. If `RANDOM` is never called with arguments, it always returns
786 the exact same sequence of numbers, for convenience in debugging.
787 "Debugged" programs should give `RANDOM` two arguments on the first
788 call, which become seeds for a new sequence. Popular choices of new
789 seeds are the numbers given by `TIME` (which see), possibly with bits
790 modified (chapter 18). Example ("pick a number from one to ten"):
791
792     <+ 1 <MOD <RANDOM> 10>>$
793     4
794
795 Chapter 4. Values of Atoms
796 ==========================
797
798 4.1. General \[1\]
799 ------------------
800
801 There are two kinds of "value" which can be attached to an `ATOM`. An
802 `ATOM` can have either, both, or neither. They interact in no way
803 (except that alternately referring to one and then the other is
804 inefficient). These two values are referred to as the **local value**
805 and the **global value** of an `ATOM`. The terms "local" and "global"
806 are relative to `PROCESS`es (chapter 20), not functions or programs.
807 The `SUBR`s which reference the local and global values of an `ATOM`,
808 and some of the characteristics of local versus global values, follow.
809
810 4.2. Global Values
811 ------------------
812
813 ### 4.2.1. SETG \[1\]
814
815 A global value can be assigned to an `ATOM` by the `SUBR` `SETG` ("set
816 global"), as in
817
818     <SETG atom any>
819
820 where *atom* must `EVAL` to an `ATOM`, and *any* can `EVAL` to
821 anything. `EVAL` of the second argument becomes the global value of
822 `EVAL` of the first argument. The value returned by the `SETG` is its
823 second argument, namely the new global value of *atom*.
824
825 Examples:
826
827     <SETG FOO <SETG BAR 500>>$
828     500
829
830 The above made the global values of both the `ATOM` `FOO` and the
831 `ATOM` `BAR` equal to the `FIX`ed-point number 500.
832
833     <SETG BAR FOO>$
834     FOO
835
836 That made the global value of the `ATOM` `BAR` equal to the `ATOM`
837 `FOO`.
838
839 ### 4.2.2. GVAL \[1\]
840
841 The `SUBR` `GVAL` ("global value") is used to reference the global
842 value of an `ATOM`.
843
844     <GVAL atom>
845
846 returns as a value the global value of *atom*. If *atom* does not
847 evaluate to an `ATOM`, or if the `ATOM` to which it evaluates has no
848 global value, an error occurs.
849
850 `GVAL` applied to an `ATOM` anywhere, in any `PROCESS`, in any
851 function, will return the same value. Any `SETG` anywhere changes the
852 global value for everybody. Global values are context-independent.
853
854 `READ` understands the character `,` (comma) as an abbreviation for an
855 application of `GVAL` to whatever follows it. `PRINT` always
856 translates an application of `GVAL` into the comma format. The
857 following are absolutely equivalent:
858
859     ,atom        <GVAL atom>
860
861 Assuming the examples in section 4.2.1 were carried out in the order
862 given, the following will evaluate as indicated:
863
864     ,FOO$
865     500
866     <GVAL FOO>$
867     500
868     ,BAR$
869     FOO
870     ,,BAR$
871     500
872
873 ### 4.2.3. Note on SUBRs and FSUBRs
874
875 The initial `GVAL`s of the `ATOM`s used to refer to Muddle "built-in"
876 Subroutines are the `SUBR`s and `FSUBR`s which actually get applied
877 when those `ATOM`s are referenced. If you don't like the way those
878 supplied routines work, you are perfectly free to `SETG` the `ATOM`s
879 to your own versions.
880
881 ### 4.2.4. GUNASSIGN
882
883     <GUNASSIGN atom>
884
885 ("global unassign") causes *atom* to have no assigned global value,
886 whether or not it had one previously. The storage used for the global
887 value can become free for other uses.
888
889 4.3. Local Values
890 -----------------
891
892 ### 4.3.1. SET \[1\]
893
894 The `SUBR` `SET` is used to assign a local value to an `ATOM`.
895 Applications of `SET` are of the form
896
897     <SET atom any>
898
899 `SET` returns `EVAL` of *any* just like `SETG`.
900
901 Examples:
902
903     <SET BAR <SET FOO 100>>$
904     100
905
906 Both `BAR` and `FOO` have been given local values equal to the
907 `FIX`ed-point number 100.
908
909     <SET FOO BAR>$
910     BAR
911
912 `FOO` has been given the local value `BAR`.
913
914 Note that neither of the above did anything to any global values `FOO`
915 and `BAR` might have had.
916
917 ### 4.3.2. LVAL \[1\]
918
919 The `SUBR` used to extract the local value of an `ATOM` is named
920 `LVAL`. As with `GVAL`, `READ` understands an abbreviation for an
921 application of `LVAL`: the character `.` (period), and `PRINT`
922 produces it. The following two representations are equivalent, and
923 when `EVAL` operates on the corresponding Muddle object, it returns
924 the current local value of *atom*:
925
926     <LVAL atom>        .atom
927
928 The local value of an `ATOM` is unique within a `PROCESS`. `SET`ting
929 an `ATOM` in one `PROCESS` has no effect on its `LVAL` in another
930 `PROCESS`, because each `PROCESS` has its own "control stack"
931 (chapters 20 and 22).
932
933 Assume **all** of the previous examples in this chapter have been
934 done. Then the following evaluate as indicated:
935
936     .BAR$
937     100
938     <LVAL BAR>$
939     100
940     .FOO$
941     BAR
942     ,.FOO$
943     FOO
944
945 ### 4.3.3. UNASSIGN
946
947     <UNASSIGN atom>
948
949 causes *atom* to have no assigned local value, whether or not it had
950 one previously.
951
952 4.4. VALUE
953 ----------
954
955 `VALUE` is a `SUBR` which takes an `ATOM` as an argument, and then:
956
957 1.  if the `ATOM` has an `LVAL`, returns the `LVAL`;
958 2.  if the `ATOM` has no `LVAL` but has a `GVAL`, returns the `GVAL`;
959 3.  if the `ATOM` has neither a `GVAL` nor an `LVAL`, calls the
960     `ERROR` function.
961
962 This order of seeking a value is the **opposite** of that used when an
963 `ATOM` is the first element of a `FORM`. The latter will be called the
964 G/LVAL, even though that name is not used in Muddle.
965
966 Example:
967
968     <UNASSIGN A>$
969     A
970     <SETG A 1>$
971     1
972     <VALUE A>$
973     1
974     <SET A 2>$
975     2
976     <VALUE A>$
977     2
978     ,A$
979     1
980
981 Chapter 5. Simple Functions
982 ===========================
983
984 5.1. General \[1\]
985 ------------------
986
987 The Muddle equivalent of a "program" (uncompiled) is an object of
988 `TYPE` `FUNCTION`. Actually, full-blown "programs" are usually
989 composed of sets of `FUNCTION`s, with most `FUNCTION`s in the set
990 acting as "subprograms".
991
992 A `FUNCTION` may be considered to be a `SUBR` or `FSUBR` which you
993 yourself define. It is "run" by using a `FORM` to apply it to
994 arguments (for example, &lt;*function arg-1 arg-2 ...*&gt;), and it
995 always "returns" a single object, which is used as the value of the
996 `FORM` that applied it. The single object may be ignored by whatever
997 "ran" the `FUNCTION` -- equivalent to "returning no value" -- or it
998 may be a structured object containing many objects -- equivalent to
999 "returning many values". Muddle is an "applicative" language, in
1000 contrast to "imperative" languages like Fortran. In Muddle it is
1001 impossible to return values through arguments in the normal case; they
1002 can be returned only as the value of the `FORM` itself, or as side
1003 effects to structured objects or global values.
1004
1005 In this chapter a simple subset of the `FUNCTION`s you can write is
1006 presented, namely `FUNCTION`s which "act like" `SUBR`s with a fixed
1007 number of arguments. While this class corresponds to about 90% of the
1008 `FUNCTION`s ever written, you won't be able to do very much with them
1009 until you read further and learn more about Muddle's control and
1010 manipulatory machinery. However, all that machinery is just a bunch of
1011 `SUBR`s and `FSUBR`s, and you already know how to "use" them; you just
1012 need to be told what they do. Once you have `FUNCTION`s under your
1013 belt, you can immediately make use of everything presented from this
1014 point on in the document. In fact, we recommend that you do so.
1015
1016 5.2. Representation \[1\]
1017 -------------------------
1018
1019 A `FUNCTION` is just another data object in Muddle, of `TYPE`
1020 `FUNCTION`. It can be manipulated like any other data object. `PRINT`
1021 represents a `FUNCTION` like this:
1022
1023     #FUNCTION (elements)
1024
1025 that is, a number sign, the `ATOM` `FUNCTION`, a left parenthesis,
1026 each of the elements of the `FUNCTION`, and a right parenthesis. Since
1027 `PRINT` represents `FUNCTION`s like this, you can type them in to
1028 `READ` this way. (But there are a few `TYPE`s for which that
1029 implication is false.)
1030
1031 The elements of a `FUNCTION` can be "any number of anythings";
1032 however, when you **use** a `FUNCTION` (apply it with a `FORM`),
1033 `EVAL` will complain if the `FUNCTION` does not look like
1034
1035     #FUNCTION (act:atom arguments:list decl body)
1036
1037 where *act* and *decl* are optional (section 9.8 and chapter 14);
1038 *body* is **at least one** Muddle object -- any old Muddle object;
1039 and, in this simple case, *arguments* is
1040
1041     (any number of ATOMs)
1042
1043 that is, something `READ` and `PRINT`ed as: left parenthesis, any
1044 number -- including zero -- of `ATOM`s, right parenthesis. (This is
1045 actually a normal Muddle object of `TYPE` `LIST`, containing only
1046 `ATOM`s.)
1047
1048 Thus, these `FUNCTION`s will cause errors -- but only **when used**:
1049
1050   Input                       Explanation
1051   --------------------------- ----------------------------------
1052   `#FUNCTION ()`              -- no argument `LIST` or body
1053   `#FUNCTION ((1) 2 7.3)`     -- non-`ATOM` in argument `LIST`
1054   `#FUNCTION ((A B C D))`     -- no body
1055   `#FUNCTION (<+ 1 2> A C)`   -- no argument `LIST`
1056
1057 These `FUNCTION`s will never cause errors because of format:
1058
1059     #FUNCTION (() 1 2 3 4 5)
1060     #FUNCTION ((A) A)
1061     #FUNCTION (()()()()()()()())
1062     #FUNCTION ((A B C D EE F G H HIYA) <+ .A .HIYA>)
1063     #FUNCTION ((Q) <SETG C <* .Q ,C>> <+ <MOD ,C 3> .Q>)
1064
1065 and the last two actually do something which might be useful. (The
1066 first three are rather pathological, but legal.)
1067
1068 5.3. Application of FUNCTIONs: Binding \[1\]
1069 --------------------------------------------
1070
1071 `FUNCTION`s, like `SUBR`s and `FSUBR`s, are applied using `FORM`s. So,
1072
1073     <#FUNCTION ((X) <* .X .X>) 5>$
1074     25
1075
1076 applied the indicated `FUNCTION` to 5 and returned 25.
1077
1078 What `EVAL` does when applying a `FUNCTION` is the following:
1079
1080 1.  Create a "world" in which the `ATOM`s of the argument `LIST` have
1081     been **`SET`** to the values applied to the `FUNCTION`, and all
1082     other `ATOM`s have their original values. This is called
1083     "binding".
1084
1085 -   In the above, this is a "world" in which `X` is `SET` to `5`.
1086
1087 2.  In that new "world", evaluate all the objects in the body of the
1088     `FUNCTION`, one after the other, from first to last.
1089
1090 -   In the above, this means evaluate `<* .X .X>` in a "world" where
1091     `X` is `SET` to `5`.
1092
1093 3.  Throw away the "world" created, and restore the `LVAL`s of all
1094     `ATOM`s bound in this application of the `FUNCTION` to their
1095     originals (if any). This is called "unbinding".
1096
1097 -   In the above, this simply gives `X` back the local value, if any,
1098     that it had before binding.
1099
1100 4.  Return as a value the **last value obtained** when the
1101     `FUNCTION`'s body was evaluated in step (2).
1102
1103 -   In the above, this means return `25` as the value.
1104
1105 The "world" mentioned above is actually an object of `TYPE`
1106 `ENVIRONMENT`. The fact that such "worlds" are separate from the
1107 `FUNCTION`s which cause their generation means that **all** Muddle
1108 `FUNCTION`s can be used recursively.
1109
1110 The only thing that is at all troublesome in this sequence is the
1111 effect of creating these new "worlds", in particular, the fact that
1112 the **previous** world is completely restored. This means that if,
1113 inside a `FUNCTION`, you `SET` one of its argument `ATOM`s to
1114 something, that new `LVAL` will **not** be remembered when `EVAL`
1115 leaves the `FUNCTION`. However, if you `SET` an `ATOM` which is
1116 **not** in the argument `LIST` (or `SETG` **any** `ATOM`) the new
1117 local (or global) value **will** be remembered. Examples:
1118
1119     <SET X 0>$
1120     0
1121     <#FUNCTION ((X) <SET X <* .X .X>>) 5>$
1122     25
1123     .X$
1124     0
1125
1126 On the other hand,
1127
1128     <SET Y 0>$
1129     0
1130     <#FUNCTION ((X) <SET Y <* .X .X>>) 5>$
1131     25
1132     .Y$
1133     25
1134
1135 By using `PRINT` as a `SUBR`, we can "see" that an argument's `LVAL`
1136 really is changed while `EVAL`uating the body of a `FUNCTION`:
1137
1138     <SET X 5>$
1139     5
1140     <#FUNCTION ((X) <PRINT .X> <+ .X 10>) 3>$
1141     3 13
1142     .X$
1143     5
1144
1145 The first number after the application `FORM` was typed out by the
1146 `PRINT`; the second is the value of the application.
1147
1148 Remembering that `LVAL`s of `ATOM`s **not** in argument `LIST`s are
1149 not changed, we can reference them within `FUNCTION`s, as in
1150
1151     <SET Z 100>$
1152     100
1153     <#FUNCTION ((Y) </ .Z .Y>) 5>$
1154     20
1155
1156 `ATOM`s used like `Z` or `Y` in the above examples are referred to as
1157 "free variables". The use of free variables, while often quite
1158 convenient, is rather dangerous unless you know **exactly** how a
1159 `FUNCTION` will **always** be used: if a `FUNCTION` containing free
1160 variables is used within a `FUNCTION` within a `FUNCTION` within ...,
1161 one of those `FUNCTION`s might just happen to use your free variable
1162 in its argument `LIST`, binding it to some unknown value and possibly
1163 causing your use of it to be erroneous. Please note that "dangerous",
1164 as used above, really means that it may be effectively **impossible**
1165 (1) for other people to use your `FUNCTION`s, and (2) for **you** to
1166 use your `FUNCTION`s a month (two weeks?) later.
1167
1168 5.4. Defining FUNCTIONs (FUNCTION and DEFINE) \[1\]
1169 ---------------------------------------------------
1170
1171 Obviously, typing `#FUNCTION (...)` all the time is neither reasonable
1172 nor adequate for many purposes. Normally, you just want a `FUNCTION`
1173 to be the `GVAL` of some `ATOM` -- the way `SUBR`s and `FSUBR`s are --
1174 so you can use it repeatedly (and recursively). Note that you
1175 generally do **not** want a `FUNCTION` to be the `LVAL` of an `ATOM`;
1176 this has the same problems as free variables. (Of course, there are
1177 always cases where you are being clever and **want** the `ATOM` to be
1178 re-bound....)
1179
1180 One way to "name" a `FUNCTION` is
1181
1182     <SETG SQUARE #FUNCTION ((X) <* .X .X>)>$
1183     #FUNCTION ((X) <* .X .X>
1184
1185 So that
1186
1187     <SQUARE 5>$
1188     25
1189     <SQUARE 100>$
1190     10000
1191
1192 Another way, which is somewhat cleaner in its typing:
1193
1194     <SETG SQUARE <FUNCTION (X) <* .X .X>>>$
1195     #FUNCTION ((X) <* .X .X>
1196
1197 `FUNCTION` is an `FSUBR` which simply makes a `FUNCTION` out of its
1198 arguments and returns the created `FUNCTION`.
1199
1200 This, however, is generally the **best** way:
1201
1202     <DEFINE SQUARE (X) <* .X .X>>$
1203     SQUARE
1204     ,SQUARE$
1205     #FUNCTION ((X) <* .X .X>
1206
1207 The last two lines immediately above are just to prove that `DEFINE`
1208 did the "right thing".
1209
1210 `DEFINE` is an `FSUBR` which `SETG`s `EVAL` of its first argument to
1211 the `FUNCTION` it makes from the rest of its arguments, and then
1212 returns `EVAL` of its first argument. `DEFINE` obviously requires the
1213 least typing of the above methods, and is "best" from that standpoint.
1214 However, the real reason for using `DEFINE` is the following: If
1215 `EVAL` of `DEFINE`'s first argument **already has** a `GVAL`, `DEFINE`
1216 produces an error. This helps to keep you from accidentally redefining
1217 things -- like Muddle `SUBR`s and `FSUBR`s. The `SETG` constructions
1218 should be used only when you really do want to redefine something.
1219 `DEFINE` will be used in the rest of this document.
1220
1221 \[Actually, if it is absolutely necessary to use `DEFINE` to
1222 "redefine" things, there is a "switch" which can be used: if the
1223 `LVAL` of the `ATOM` `REDEFINE` is `T` (or anything not of `TYPE`
1224 `FALSE`), `DEFINE` will produce no errors. The normal state can be
1225 restored by evaluating `<SET REDEFINE <>>`. See chapter 8.\]
1226
1227 5.5. Examples (Comments) \[1\]
1228 ------------------------------
1229
1230 Using `SQUARE` as defined above:
1231
1232     <DEFINE HYPOT (SIDE-1 SIDE-2)
1233             ;"This is a comment. This FUNCTION finds the
1234               length of the hypotenuse of a right triangle
1235               of sides SIDE-1 and SIDE-2."
1236         <SQRT <+ <SQUARE .SIDE-1> <SQUARE .SIDE-2>>>>$
1237     HYPOT
1238     <HYPOT 3 4>$
1239     5.0
1240
1241 Note that carriage-returns, line-feeds, tabs, etc. are just
1242 separators, like spaces. A comment is **any single** Muddle object
1243 which follows a `;` (semicolon). A comment can appear between any two
1244 Muddle objects. A comment is totally ignored by `EVAL` but remembered
1245 and associated by `READ` with the place in the `FUNCTION` (or any
1246 other structured object) where it appeared. (This will become clearer
1247 after chapter 13.) The `"`s (double-quotes) serve to make everything
1248 between them a single Muddle object, whose `TYPE` is `STRING` (chapter
1249 7). (`SQRT` is the `SUBR` which returns the square root of its
1250 argument. It always returns a `FLOAT`.)
1251
1252 A whimsical `FUNCTION`:
1253
1254     <DEFINE ONE (THETA) ;"This FUNCTION always returns 1."
1255             <+ <SQUARE <SIN .THETA>>
1256                <SQUARE <COS .THETA>>>>$
1257     ONE
1258     <ONE 5>$
1259     0.99999994
1260     <ONE 0.23>$
1261     0.99999999
1262
1263 `ONE` always returns (approximately) one, since the sum of the squares
1264 of sin(x) and cos(x) is unity for any x. (`SIN` and `COS` always
1265 return `FLOAT`s, and each takes its argument in radians. `ATAN`
1266 (arctangent) returns its value in radians. Any other trigonometric
1267 function can be compounded from these three.)
1268
1269 Muddle doesn't have a general "to the power" `SUBR`, so let's define
1270 one using `LOG` and `EXP` (log base e, and e to a power, respectively;
1271 again, they return `FLOAT`s).
1272
1273     <DEFINE ** (NUM PWR) <EXP <* .PWR <LOG .NUM>>>>$
1274     **
1275     <** 2 2>$
1276     4.0000001
1277     <** 5 3>$
1278     125.00000
1279     <** 25 0.5>$
1280     5.0000001
1281
1282 Two `FUNCTION`s which use a single global variable (Since the `GVAL`
1283 is used, it cannot be rebound.):
1284
1285     <DEFINE START () <SETG GV 0>>$
1286     START
1287     <DEFINE STEP () <SETG GV <+ ,GV 1>>>$
1288     STEP
1289     <START>$
1290     0
1291     <STEP>$
1292     1
1293     <STEP>$
1294     2
1295     <STEP>$
1296     3
1297
1298 `START` and `STEP` take no arguments, so their argument `LIST`s are
1299 empty.
1300
1301 An interesting, but pathological, `FUNCTION`:
1302
1303     <DEFINE INC (ATM) <SET .ATM <+ ..ATM 1>>>$
1304     INC
1305     <SET A 0>$
1306     0
1307     <INC A>$
1308     1
1309     <INC A>$
1310     2
1311     .A$
1312     2
1313
1314 `INC` takes an **`ATOM`** as an argument, and `SET`s that `ATOM` to
1315 its current `LVAL` plus `1`. Note that inside `INC`, the `ATOM` `ATM`
1316 is `SET` to the `ATOM` which is its argument; thus `..ATM` returns the
1317 `LVAL` of the **argument**. However, there is a problem:
1318
1319     <SET ATM 0>$
1320     0
1321     <INC ATM>$
1322
1323     *ERROR*
1324     ARG-WRONG-TYPE
1325     +
1326     LISTENING-AT-LEVEL 2 PROCESS 1
1327     <ARGS <FRAME <FRAME>>>$
1328     [ATM 1]
1329
1330 The error occurred because `.ATM` was `ATM`, the argument to `INC`,
1331 and thus `..ATM` was `ATM` also. We really want the outermost `.` in
1332 `..ATM` to be done in the "world" (`ENVIRONMENT`) which existed **just
1333 before** `INC` was entered -- and this definition of `INC` does both
1334 applications of `LVAL` in its own "world". Techniques for doing `INC`
1335 "correctly" will be covered below. Read on.
1336
1337 Chapter 6. Data Types
1338 =====================
1339
1340 6.1. General \[1\]
1341 ------------------
1342
1343 A Muddle object consists of two parts: its `TYPE` and its "data part"
1344 (appendix 1). The interpretation of the "data part" of an object
1345 depends of course on its `TYPE`. The structural organization of an
1346 object, that is, the way it is organized in storage, is referred to as
1347 its "primitive type". While there are many different `TYPE`s of
1348 objects in Muddle, there are fewer primitive types.
1349
1350 All structured objects in Muddle are ordered sequences of elements. As
1351 such, there are `SUBR`s which operate on all of them uniformly, as
1352 ordered sequences. On the other hand, the reason for having different
1353 primitive types of structured objects is that there are useful
1354 qualities of structured objects which are mutually incompatible. There
1355 are, therefore, `SUBR`s which do not work on all structured objects:
1356 these `SUBR`s exist to take full advantage of those mutually
1357 incompatible qualities. The most-commonly-used primitive types of
1358 structured objects are discussed in chapter 7, along with those
1359 special `SUBR`s operating on them.
1360
1361 It is very easy to make a new Muddle object that differs from an old
1362 one only in `TYPE`, as long as the primitive type is unchanged. It is
1363 relatively difficult to make a new structured object that differs from
1364 an old one in primitive type, even if it has the same elements.
1365
1366 Before talking any more about structured objects, some information
1367 needs to be given about `TYPE`s in general.
1368
1369 6.2. Printed Representation \[1\]
1370 ---------------------------------
1371
1372 There are many `TYPE`s for which Muddle has no specific
1373 representation. There aren't enough different kinds of brackets. The
1374 representation used for `TYPE`s without any special representation is
1375
1376     #type representation-as-if-it-were-its-primitive-type
1377
1378 `READ` will understand that format for **any** `TYPE`, and `PRINT`
1379 will use it by default. This representational format will be referred
1380 to below as "\# notation". It was used above to represent `FUNCTION`s.
1381
1382 6.3. SUBRs Related to TYPEs
1383 ---------------------------
1384
1385 ### 6.3.1. TYPE \[1\]
1386
1387     <TYPE any>
1388
1389 returns an **`ATOM`** whose `PNAME` corresponds to the `TYPE` of
1390 *any*. There is no `TYPE` "TYPE". To type a `TYPE` (aren't homonyms
1391 wonderful?), just type the appropriate `ATOM`, like `FIX` or `FLOAT`
1392 or `ATOM` etc. However, in this document we will use the convention
1393 that a metasyntactic variable can have *type* for a "data type": for
1394 example, *foo:type* means that the `TYPE` of *foo* is `ATOM`, but the
1395 `ATOM` must be something that the `SUBR` `TYPE` can return.
1396
1397 Examples:
1398
1399     <TYPE 1>$
1400     FIX
1401     <TYPE 1.0>$
1402     FLOAT
1403     <TYPE +>$
1404     ATOM
1405     <TYPE ,+>$
1406     SUBR
1407     <TYPE GEORGE>$
1408     ATOM
1409
1410 ### 6.3.2. PRIMTYPE \[1\]
1411
1412     <PRIMTYPE any>
1413
1414 evaluates to the primitive type of *any*. The `PRIMTYPE` of *any* is
1415 an `ATOM` which also represents a `TYPE`. The way an object can be
1416 **manipulated** depends solely upon its `PRIMTYPE`; the way it is
1417 **evaluated** depends upon its `TYPE`.
1418
1419 Examples:
1420
1421     <PRIMTYPE 1>$
1422     WORD
1423     <PRIMTYPE 1.0>$
1424     WORD
1425     <PRIMTYPE ,+>$
1426     WORD
1427     <PRIMTYPE GEORGE>$
1428     ATOM
1429
1430 ### 6.3.3. TYPEPRIM \[1\]
1431
1432     <TYPEPRIM type>
1433
1434 returns the `PRIMTYPE` of an object whose `TYPE` is *type*. *type* is,
1435 as usual, an `ATOM` used to designate a `TYPE`.
1436
1437 Examples:
1438
1439     <TYPEPRIM FIX>$
1440     WORD
1441     <TYPEPRIM FLOAT>$
1442     WORD
1443     <TYPEPRIM SUBR>$
1444     WORD
1445     <TYPEPRIM ATOM>$
1446     ATOM
1447     <TYPEPRIM FORM>$
1448     LIST
1449
1450 ### 6.3.4. CHTYPE \[1\]
1451
1452     <CHTYPE any type>
1453
1454 ("change type") returns a new object that has `TYPE` *type* and the
1455 same "data part" as *any* (appendix 1).
1456
1457     <CHTYPE (+ 2 2) FORM>$
1458     <+ 2 2>
1459
1460 An error is generated if the `PRIMTYPE` of *any* is not the same as
1461 the `TYPEPRIM` of *type*. An error will also be generated if the
1462 attempted `CHTYPE` is dangerous and/or senseless, for example,
1463 `CHTYPE`ing a `FIX` to a `SUBR`. Unfortunately, there are few useful
1464 examples we can do at this point.
1465
1466 \[`CHTYPE`ing a `FIX` to a `FLOAT` or vice versa produces, in general,
1467 nonsense, since the bit formats for `FIX`es and `FLOAT`s are
1468 different. The `SUBR`s `FIX` and `FLOAT` convert between those
1469 formats. Useful obscurity: because of their internal representations
1470 on the PDP-10, `<CHTYPE <MAX> FIX>` gives the least possible `FIX`,
1471 and analogously for `MIN`.\]
1472
1473 Passing note: "\# notation" is just an instruction to `READ` saying
1474 "`READ` the representation of the `PRIMTYPE` normally and (literally)
1475 `CHTYPE` it to the specified `TYPE`". \[Or, if the `PRIMTYPE` is
1476 `TEMPLATE`, "apply the `GVAL` of the `TYPE` name (which should be a
1477 `TEMPLATE` constructor) to the given elements of the `PRIMTYPE`
1478 `TEMPLATE` as arguments."\]
1479
1480 6.4. More SUBRs Related to TYPEs
1481 --------------------------------
1482
1483 ### 6.4.1. ALLTYPES
1484
1485     <ALLTYPES>
1486
1487 returns a `VECTOR` (chapter 7) containing just those `ATOM`s which can
1488 currently be returned by `TYPE` or `PRIMTYPE`. This is the very
1489 "`TYPE` vector" (section 22.1) that the interpreter uses: look, but
1490 don't touch. No examples: try it, or see appendix 3.
1491
1492 ### 6.4.2. VALID-TYPE?
1493
1494     <VALID-TYPE? atom>
1495
1496 returns `#FALSE ()` if *atom* is not the name of a `TYPE`, and the
1497 same object that `<TYPE-C atom>` (section 19.5) returns if it is.
1498
1499 ### 6.4.3. NEWTYPE
1500
1501 Muddle is a type-extensible language, in the sense that the programmer
1502 can invent new `TYPE`s and use them in every way that the predefined
1503 `TYPE`s can be used. A program-defined `TYPE` is called a `NEWTYPE`.
1504 New `PRIMTYPE`s cannot be invented except by changing the interpreter;
1505 thus the `TYPEPRIM` of a `NEWTYPE` must be chosen from those already
1506 available. But the name of a `NEWTYPE` (an `ATOM` of course) can be
1507 chosen freely -- so long as it does not conflict with an existing
1508 `TYPE` name. More importantly, the program that defines a `NEWTYPE`
1509 can be included in a set of programs for manipulating objects of the
1510 `NEWTYPE` in ways that are more meaningful than the predefined `SUBR`s
1511 of Muddle.
1512
1513 Typically an object of a `NEWTYPE` is a structure that is a model of
1514 some entity in the real world -- or whatever world the program is
1515 concerned with -- and the elements of the structure are models of
1516 parts or aspects of the real-world entity. A `NEWTYPE` definition is a
1517 convenient way of formalizing this correspondence, of writing it down
1518 for all to see and use rather than keeping it in your head. If the
1519 defining set of programs provides functions for manipulating the
1520 `NEWTYPE` objects in all ways that are meaningful for the intended
1521 uses of the `NEWTYPE`, then any other program that wants to use the
1522 `NEWTYPE` can call the manipulation functions for all its needs, and
1523 it need never know or care about the internal details of the `NEWTYPE`
1524 objects. This technique is a standard way of providing modularity and
1525 abstraction.
1526
1527 For example, suppose you wanted to deal with airline schedules. If you
1528 were to construct a set of programs that define and manipulate a
1529 `NEWTYPE` called `FLIGHT`, then you could make that set into a
1530 standard package of programs and call on it to handle all information
1531 pertaining to scheduled airline flights. Since all `FLIGHT`s would
1532 have the same quantity of information (more or less) and you would
1533 want quick access to individual elements, you would not want the
1534 `TYPEPRIM` to be `LIST`. Since the elements would be of various
1535 `TYPE`s, you would not want the `TYPEPRIM` to be `UVECTOR` -- nor its
1536 variations `STRING` or `BYTES`. The natural choice would be a
1537 `TYPEPRIM` of `VECTOR` (although you could gain space and lose time
1538 with `TEMPLATE` instead).
1539
1540 Now, the individual elements of a `FLIGHT` would, no doubt, have
1541 `TYPE`s and meanings that don't change. The elements of a `FLIGHT`
1542 might be airline code, flight number, originating-airport code, list
1543 of intermediate stops, destination-airport code, type of aircraft,
1544 days of operation, etc. Each and every `FLIGHT` would have the airline
1545 code for its first element (say), the flight number for its second,
1546 and so on. It is natural to invent names (`ATOM`s) for these elements
1547 and always refer to the elements by name. For example, you could
1548 `<SETG AIRLINE 1>` or `<SETG AIRLINE <OFFSET 1 FLIGHT>>` -- and in
1549 either case `<MANIFEST AIRLINE>` so the compiler can generate more
1550 efficient code. Then, if the local value of `F` were a `FLIGHT`,
1551 `<AIRLINE .F>` would return the airline code, and `<AIRLINE .F AA>`
1552 would set the airline code to `AA`. Once that is done, you can forget
1553 about which element comes first: all you need to know are the names of
1554 the offsets.
1555
1556 The next step is to notice that, outside the package of `FLIGHT`
1557 functions, no one needs to know whether `AIRLINE` is just an offset or
1558 in fact a function of some kind. For example, the scheduled duration
1559 of a flight might not be explicitly stored in a `FLIGHT`, just the
1560 scheduled times of departure and arrival. But, if the package had the
1561 proper `DURATION` function for calculating the duration, then the call
1562 `<DURATION .F>` could return the duration, no matter how it is found.
1563 In this way the internal details of the package are conveniently
1564 hidden from view and abstracted away.
1565
1566 The form of `NEWTYPE` definition allows for the `TYPE`s of all
1567 components of a `NEWTYPE` to be declared (chapter 14), for use both by
1568 a programmer while debugging programs that use the `NEWTYPE` and by
1569 the compiler for generating faster code. It is very convenient to have
1570 the type declaration in the `NEWTYPE` definition itself, rather than
1571 replicating it everywhere the `NEWTYPE` is used. (If you think this
1572 declaration might be obtrusive while debugging the programs in the
1573 `NEWTYPE` package, when inconsistent improvements are being made to
1574 various programs, you can either dissociate any declaration from the
1575 `NEWTYPE` or turn off Muddle type-checking completely. Actually this
1576 declaration is typically more useful to a programmer during
1577 development than it is to the compiler.)
1578
1579     <NEWTYPE atom type>
1580
1581 returns *atom*, after causing it to become the representation of a
1582 brand-new `TYPE` whose `PRIMTYPE` is `<TYPEPRIM type>`. What `NEWTYPE`
1583 actually does is make *atom* a legal argument to `CHTYPE` and
1584 `TYPEPRIM`. (Note that names of new `TYPE`s can be blocked lexically
1585 to prevent collision with other names, just like any other `ATOM`s --
1586 chapter 15.) Objects of a `NEWTYPE`-created `TYPE` can be generated by
1587 creating an object of the appropriate `PRIMTYPE` and using `CHTYPE`.
1588 They will be `PRINT`ed (initially), and can be directly typed in, by
1589 the use of "\# notation" as described above. `EVAL` of any object
1590 whose `TYPE` was created by `NEWTYPE` is initially the object itself,
1591 and, initially, you cannot `APPLY` something of a generated `TYPE` to
1592 arguments. But see below.
1593
1594 Examples:
1595
1596     <NEWTYPE GARGLE FIX>$
1597     GARGLE
1598     <TYPEPRIM GARGLE>$
1599     WORD
1600     <SET A <CHTYPE 1 GARGLE>>$
1601     #GARGLE *000000000001*
1602     <SET B #GARGLE 100>$
1603     #GARGLE *000000000144*
1604     <TYPE .B>$
1605     GARGLE
1606     <PRIMTYPE .B>$
1607     WORD
1608
1609 ### 6.4.4. PRINTTYPE, EVALTYPE and APPLYTYPE
1610
1611     <PRINTTYPE type how>
1612
1613     <EVALTYPE type how>
1614
1615     <APPLYTYPE type how>
1616
1617 all return *type*, after specifying *how* Muddle is to deal with it.
1618
1619 These three `SUBR`s can be used to make newly-generated `TYPE`s behave
1620 in arbitrary ways, or to change the characteristics of standard Muddle
1621 `TYPE`s. `PRINTTYPE` tells Muddle how to print *type*, `EVALTYPE` how
1622 to evaluate it, and `APPLYTYPE` how to apply it in a `FORM`.
1623
1624 *how* can be either a `TYPE` or something that can be applied to
1625 arguments.
1626
1627 If *how* is a `TYPE`, Muddle will treat *type* just like the `TYPE`
1628 given as *how*. *how* must have the same `TYPEPRIM` as *type*.
1629
1630 If *how* is applicable, it will be used in the following way:
1631
1632 For `PRINTTYPE`, *how* should take one argument: the object being
1633 output. *how* should output something without formatting
1634 (`PRIN1`-style); its result is ignored. (Note: *how* cannot use an
1635 output `SUBR` on *how*'s own *type*: endless recursion will result.
1636 `OUTCHAN` is bound during the application to the `CHANNEL` in use, or
1637 to a pseudo-internal channel for `FLATSIZE` -- chapter 11.) If *how*
1638 is the `SUBR` `PRINT`, *type* will receive no special treatment in
1639 printing, that is, it will be printed as it was in an initial Muddle
1640 or immediately after its defining `NEWTYPE`.
1641
1642 For `EVALTYPE`, *how* should take one argument: the object being
1643 evaluated. The value returned by *how* will be used as `EVAL` of the
1644 object. If *how* is the `SUBR` `EVAL`, *type* will receive no special
1645 treatment in its evaluation.
1646
1647 For `APPLYTYPE`, *how* should take at least one argument. The first
1648 argument will be the object being applied: the rest will be the
1649 objects it was given as arguments. The result returned by *how* will
1650 be used as the result of the application. If *how* is the `SUBR`
1651 `APPLY`, *type* will receive no special treatment in application to
1652 arguments.
1653
1654 If any of these `SUBR`s is given only one argument, that is if *how*
1655 is omitted, it returns the currently active *how* (a `TYPE` or an
1656 applicable object), or else `#FALSE ()` if *type* is receiving no
1657 special treatment in that operation.
1658
1659 Unfortunately, these examples are fully understandable only after you
1660 have read through chapter 11.
1661
1662     <DEFINE ROMAN-PRINT (NUMB)
1663     <COND (<OR <L=? .NUMB 0> <G? .NUMB 3999>>
1664            <PRINC <CHTYPE .NUMB TIME>>)
1665           (T
1666            <RCPRINT </ .NUMB 1000> '![!\M]>
1667            <RCPRINT </ .NUMB  100> '![!\C !\D !\M]>
1668            <RCPRINT </ .NUMB   10> '![!\X !\L !\C]>
1669            <RCPRINT    .NUMB       '![!\I !\V !\X]>)>>$
1670     ROMAN-PRINT
1671
1672     <DEFINE RCPRINT (MODN V)
1673     <SET MODN <MOD .MODN 10>>
1674     <COND (<==? 0 .MODN>)
1675           (<==? 1 .MODN> <PRINC <1 .V>>)
1676           (<==? 2 .MODN> <PRINC <1 .V>> <PRINC <1 .V>>)
1677           (<==? 3 .MODN> <PRINC <1 .V>> <PRINC <1 .V>> <PRINC <1 .V>>)
1678           (<==? 4 .MODN> <PRINC <1 .V>> <PRINC <2 .V>>)
1679           (<==? 5 .MODN> <PRINC <2 .V>>)
1680           (<==? 6 .MODN> <PRINC <2 .V>> <PRINC <1 .V>>)
1681           (<==? 7 .MODN> <PRINC <2 .V>> <PRINC <1 .V>> <PRINC <1 .V>>)
1682           (<==? 8 .MODN>
1683            <PRINC <2 .V>>
1684            <PRINC <1 .V>>
1685            <PRINC <1 .V>>
1686            <PRINC <1 .V>>)
1687           (<==? 9 .MODN> <PRINC <1 .V>> <PRINC <3 .V>>)>>$
1688     RCPRINT
1689
1690     <PRINTTYPE TIME FIX> ;"fairly harmless but necessary here"$
1691     TIME
1692     <PRINTTYPE FIX ,ROMAN-PRINT>    ;"hee hee!"$
1693     FIX
1694     <+ 2 2>$
1695     IV
1696     1984$
1697     MCMLXXXIV
1698     <PRINTTYPE FIX ,PRINT>$
1699     FIX
1700
1701     <NEWTYPE GRITCH LIST>   ;"a new TYPE of PRIMTYPE LIST"$
1702     GRITCH
1703     <EVALTYPE GRITCH>$
1704     #FALSE ()
1705     <EVALTYPE GRITCH LIST>  ;"evaluated like a LIST"$
1706     GRITCH
1707     <EVALTYPE GRITCH>$
1708     LIST
1709     #GRITCH (A <+ 1 2 3> !<SET A "ABC">)    ;"Type in one."$
1710     #GRTICH (A 6 !\A !\B !\C)
1711
1712     <NEWTYPE HARRY VECTOR>  ;"a new TYPE of PRIMTYPE VECTOR"$
1713     HARRY
1714     <EVALTYPE HARRY #FUNCTION ((X) <1 .X>)>
1715         ;"When a HARRY is EVALed, return its first element."$
1716     HARRY
1717     #HARRY [1 2 3 4]$
1718     1
1719
1720     <NEWTYPE WINNER LIST>   ;"a TYPE with funny application"$
1721     WINNER
1722     <APPLYTYPE WINNER>$
1723     #FALSE ()
1724     <APPLYTYPE WINNER <FUNCTION (W "TUPLE" T) (!.W !.T)>>$
1725     WINNER
1726     <APPLYTYPE WINNER>$
1727     #FUNCTION ((W "TUPLE" T (!.W !.T))
1728     <#WINNER (A B C) <+ 1 2> q>$
1729     (A B C 3 q)
1730
1731 The following sequence makes Muddle look just like Lisp. (This example
1732 is understandable only if you know Lisp (Moon, 1974); it is included
1733 only because it is so beautiful.)
1734
1735     <EVALTYPE LIST FORM>$
1736     LIST
1737     <EVALTYPE ATOM ,LVAL>$
1738     ATOM
1739
1740 So now:
1741
1742     (+ 1 2)$
1743     3
1744     (SET 'A 5)$
1745     5
1746     A$
1747     5
1748
1749 To complete the job, of course, we would have to do some `SETG`'s:
1750 `car` is `1`, `cdr` is `,REST`, and `lambda` is `,FUNCTION`. If you
1751 really do this example, you should "undo" it before continuing:
1752
1753     <EVALTYPE 'ATOM ,EVAL>$
1754     ATOM
1755     <EVALTYPE LIST ,EVAL>$
1756     LIST
1757
1758 Chapter 7. Structured Objects
1759 =============================
1760
1761 This chapter discusses structured objects in general and the five
1762 basic structured `PRIMTYPE`s. \[We defer detailed discussion of the
1763 structured `PRIMTYPE`s `TUPLE` (section 9.2) and `STORAGE` (section
1764 22.2.2).\]
1765
1766 7.1. Manipulation
1767 -----------------
1768
1769 The following `SUBR`s operate uniformly on all structured objects and
1770 generate an error if not applied to a structured object. Hereafter,
1771 *structured* represents a structured object.
1772
1773 ### 7.1.1. LENGTH \[1\]
1774
1775     <LENGTH structured>
1776
1777 evaluates to the number of elements in *structured*.
1778
1779 ### 7.1.2. NTH \[1\]
1780
1781     <NTH structured fix>
1782
1783 evaluates to the *fix*'th element of *structured*. An error occurs if
1784 *fix* is less than 1 or greater than `<LENGTH structured>`. *fix* is
1785 optional, 1 by default.
1786
1787 ### 7.1.3. REST \[1\]
1788
1789     <REST structured fix>
1790
1791 evaluates to *structured* without its first *fix* elements. *fix* is
1792 optional, 1 by default.
1793
1794 Obscure but important side effect: `REST` actually returns
1795 *structured* "`CHTYPE`d" (but not through application of `CHTYPE`) to
1796 its `PRIMTYPE`. For example, `REST` of a `FORM` is a `LIST`. `REST`
1797 with an explicit second argument of `0` has no effect except for this
1798 `TYPE` change.
1799
1800 ### 7.1.4. PUT \[1\]
1801
1802     <PUT structured fix anything-legal>
1803
1804 first makes *anything-legal* the *fix*'th element of *structured*,
1805 then evaluates to *structured*. *anything-legal* is anything which can
1806 legally be an element of *structured*; often, this is synonymous with
1807 "any Muddle object", but see below. An error occurs if *fix* is less
1808 than 1 or greater than `<LENGTH structured>`. (`PUT` is actually more
1809 general than this -- chapter 13.)
1810
1811 ### 7.1.5. GET
1812
1813     <GET structured fix>
1814
1815 evaluates the same as `<NTH structured fix>`. It is more general than
1816 `NTH`, however (chapter 13), and is included here only for symmetry
1817 with `PUT`.
1818
1819 ### 7.1.6. APPLYing a FIX \[1\]
1820
1821 `EVAL` understands the application of an object of `TYPE` `FIX` as a
1822 "shorthand" call to `NTH` or `PUT`, depending on whether it is given
1823 one or two arguments, respectively \[unless the `APPLYTYPE` of `FIX`
1824 is changed\]. That is, `EVAL` considers the following two to be
1825 identical:
1826
1827     <fix structured>
1828     <NTH structured fix>
1829
1830 and these:
1831
1832     <fix structured object>
1833     <PUT structured fix object>
1834
1835 \[However, the compiler (Lebling, 1979) cannot generate efficient code
1836 from the longer forms unless it is sure that *fix* is a `FIX` (section
1837 9.10). The two constructs are not identical even to `EVAL`, if the
1838 order of evaluation is significant: for example, these two:
1839
1840     <NTH .X <LENGTH <SET X .Y>>>        <<LENGTH <SET X .Y>> .X>
1841
1842 are **not** identical.\]
1843
1844 ### 7.1.7. SUBSTRUC
1845
1846 `SUBSTRUC` ("substructure") facilitates the construction of structures
1847 that are composed of sub-parts of existing structures. A special case
1848 of this would be a "substring" function.
1849
1850     <SUBSTRUC from:structured rest:fix amount:fix to:structured>
1851
1852 copies the first *amount* elements of `<REST from rest>` into another
1853 object and returns the latter. All arguments are optional except
1854 *from*, which must be of `PRIMTYPE` `LIST`, `VECTOR`, `TUPLE` (treated
1855 like a `VECTOR`), `STRING`, `BYTES`, or `UVECTOR`. *rest* is `0` by
1856 default, and *amount* is all the elements by default. *to*, if given,
1857 receives the copied elements, starting at its beginning; it must be an
1858 object whose `TYPE` is the `PRIMTYPE` of *from* (a `VECTOR` if *from*
1859 is a `TUPLE`). If *to* is not given, a new object is returned, of
1860 `TYPE` `<PRIMTYPE from>` (a `VECTOR` if *from* is a `TUPLE`), which
1861 **never** shares with *from*. The copying is done in one fell swoop,
1862 not an element at a time. Note: due to an implementation restriction,
1863 if *from* is of `PRIMTYPE` `LIST`, it must not share any elements with
1864 *to*.
1865
1866 7.2. Representation of Basic Structures
1867 ---------------------------------------
1868
1869 ### 7.2.1. LIST \[1\]
1870
1871     ( element-1 element-2 ... element-N )
1872
1873 represents a `LIST` of *N* elements.
1874
1875 ### 7.2.2. VECTOR \[1\]
1876
1877     [ element-1 element-2 ... element-N ]
1878
1879 represents a `VECTOR` of *N* elements. \[A `TUPLE` is just like a
1880 `VECTOR`, but it lives on the control stack.\]
1881
1882 ### 7.2.3. UVECTOR \[1\]
1883
1884     ![ element-1 element-2 ... element-N !]
1885
1886 represents a `UVECTOR` (uniform vector) of *N* elements. The second
1887 `!` (exclamation-point) is optional for input. \[A `STORAGE` is an
1888 archaic kind of `UVECTOR` that is not garbage-collected.\]
1889
1890 ### 7.2.4. STRING \[1\]
1891
1892     "characters"
1893
1894 represents a `STRING` of ASCII text. A `STRING` containing the
1895 character `"` (double-quote) is represented by placing a `\`
1896 (backslash) before the double-quote inside the `STRING`. A `\` in a
1897 `STRING` is represented by two consecutive backslashes.
1898
1899 ### 7.2.5. BYTES
1900
1901     #n {element-1 element-2 ... element-N}
1902
1903 represents a string of *N* uniformly-sized bytes of size *n* bits.
1904
1905 ### 7.2.6. TEMPLATE
1906
1907     { element-1 element-2 ... element-N }
1908
1909 represents a `TEMPLATE` of *N* elements when output, not input -- when
1910 input, a `#` and a `TYPE` must precede it.
1911
1912 7.3. Evaluation of Basic Structures
1913 -----------------------------------
1914
1915 This section and the next two describe how `EVAL` treats the basic
1916 structured `TYPE`s \[in the absence of any modifying `EVALTYPE` calls
1917 (section 6.4.4)\].
1918
1919 `EVAL` of a `STRING` \[or `BYTES` or `TEMPLATE`\] is just the original
1920 object.
1921
1922 `EVAL` acts exactly the same with `LIST`s, `VECTOR`s, and `UVECTOR`s:
1923 it generates a **new** object with elements equal to `EVAL` of the
1924 elements it is given. This is one of the simplest means of
1925 constructing a structure. However, see section 7.7.
1926
1927 7.4. Examples \[1\]
1928 -------------------
1929
1930     (1 2 <+ 3 4>)$
1931     (1 2 7)
1932     <SET FOO [5 <- 3> <TYPE "ABC">]>$
1933     [5 -3 STRING]
1934     <2 .FOO>$
1935     -3
1936     <TYPE <3 .FOO>>$
1937     ATOM
1938     <SET BAR ![("meow") (.FOO)]>$
1939     ![("meow") ([5 -3 STRING])!]
1940     <LENGTH .BAR>$
1941     2
1942     <REST <1 <2 .BAR>>>$
1943     [-3 STRING]
1944     [<SUBSTRUC <1 <2 .BAR>> 0 2>]$
1945     [[5 -3]]
1946     <PUT .FOO 1 SNEAKY>          ;"Watch out for .BAR !"$
1947     [SNEAKY -3 STRING]
1948     .BAR$
1949     ![("meow") ([SNEAKY -3 STRING])!]
1950     <SET FOO <REST <1 <1 .BAR>> 2>>$
1951     "ow"
1952     .BAR$
1953     ![("meow") ([SNEAKY -3 STRING])!]
1954
1955 7.5. Generation of Basic Structures
1956 -----------------------------------
1957
1958 Since `LIST`s, `VECTOR`s, `UVECTOR`s, and `STRING`s \[and `BYTES`es\]
1959 are all generated in a fairly uniform manner, methods of generating
1960 them will be covered together here. \[`TEMPLATE`s cannot be generated
1961 by the interpreter itself: see Lebling (1979).\]
1962
1963 ### 7.5.1. Direct Representation \[1\]
1964
1965 Since `EVAL` of a `LIST`, `VECTOR`, or `UVECTOR` is a new `LIST`,
1966 `VECTOR`, or `UVECTOR` with elements which are `EVAL` of the original
1967 elements, simply evaluating a representation of the object you want
1968 will generate it. (Care must be taken when representing a `UVECTOR`
1969 that all elements have the same `TYPE`.) This method of generation was
1970 exclusively used in the examples of section 7.4. Note that new
1971 `STRING`s \[and `BYTES`es\] will not be generated in this manner,
1972 since the contents of a `STRING` are not interpreted or copied by
1973 `EVAL`. The same is true of any other `TYPE` whose `TYPEPRIM` happens
1974 to be `LIST`, `VECTOR`, or `UVECTOR` \[again, assuming it neither has
1975 been `EVALTYPE`d nor has a built-in `EVALTYPE`, as do `FORM` and
1976 `SEGMENT`\].
1977
1978 ### 7.5.2. QUOTE \[1\]
1979
1980 `QUOTE` is an `FSUBR` of one argument which returns its argument
1981 unevaluated. `READ` and `PRINT` understand the character `'`
1982 (single-quote) as an abbreviation for a call to `QUOTE`, the way
1983 period and comma work for `LVAL` and `GVAL`. Examples:
1984
1985     <+ 1 2>$
1986     3
1987     '<+ 1 2>$
1988     <+ 1 2>
1989
1990 Any `LIST`, `VECTOR`, or `UVECTOR` in a program that is constant and
1991 need not have its elements evaluated should be represented directly
1992 and **inside a call to `QUOTE`.** This technique prevents the
1993 structure from being copied each time that portion of the program is
1994 executed. Examples hereafter will adhere to this dictum. (Note: one
1995 should **never** modify a `QUOTE`d object. The compiler will one day
1996 put it in read-only (pure) storage.)
1997
1998 ### 7.5.3. LIST, VECTOR, UVECTOR, and STRING (the SUBRs) \[1\]
1999
2000 Each of the `SUBR`s `LIST`, `VECTOR`, `UVECTOR`, and `STRING` takes
2001 any number of arguments and returns an object of the appropriate
2002 `TYPE` whose elements are `EVAL` of its arguments. There are
2003 limitations on what the arguments to `UVECTOR` and `STRING` may `EVAL`
2004 to, due to the nature of the objects generated. See sections 7.6.5 and
2005 7.6.6.
2006
2007 `LIST`, `VECTOR`, and `UVECTOR` are generally used only in special
2008 cases, since Direct Representation usually produces exactly the same
2009 effect (in the absence of errors), and the intention is more apparent.
2010 \[Note: if `.L` is a `LIST`, `<LIST !.L>` makes a copy of `.L` whereas
2011 `(!.L)` doesn't; see section 7.7.\] `STRING`, on the other hand,
2012 produces effect very different from literal `STRING`s.
2013
2014 Examples:
2015
2016     <LIST 1 <+ 2 3> ABC>$
2017     (1 5 ABC)
2018     (1 <+ 2 3> ABC)$
2019     (1 5 ABC)
2020     <STRING "A" <2 "QWERT"> <REST "ABC"> "hello">$
2021     "AWBChello"
2022     "A <+ 2 3> (5)"$
2023     "A <+ 2 3> (5)"
2024
2025 ### 7.5.4. ILIST, IVECTOR, IUVECTOR, and ISTRING \[1\]
2026
2027 Each of the `SUBR`s `ILIST`, `IVECTOR`, `IUVECTOR`, and `ISTRING`
2028 ("implicit" or "iterated" whatever) creates and returns an object of
2029 the obvious `TYPE`. The format of an application of any of them is
2030
2031     < Ithing number-of-elements:fix expression:any >
2032
2033 where *Ithing* is one of `ILIST`, `IVECTOR`, `IUVECTOR`, or `ISTRING`.
2034 An object of `LENGTH` *number-of-elements* is generated, whose
2035 elements are `EVAL` of *expression*.
2036
2037 *expression* is optional. When it is not specified, `ILIST`,
2038 `IVECTOR`, and `IUVECTOR` return objects filled with objects of `TYPE`
2039 `LOSE` (`PRIMTYPE` `WORD`) as place holders, a `TYPE` which can be
2040 passed around and have its `TYPE` checked, but otherwise is an illegal
2041 argument. If *expression* is not specified in `ISTRING`, you get a
2042 `STRING` made up of `^@` characters.
2043
2044 When *expression* is supplied as an argument, it is re-`EVAL`uated
2045 each time a new element is generated. (Actually, `EVAL` of
2046 *expression* is re-`EVAL`uated, since all of these are `SUBR`s.) See
2047 the last example for how this argument may be used.
2048
2049 \[By the way, in a construct like `<IUVECTOR 9 '.X>`, even if the
2050 `LVAL` of `X` evaluates to itself, so that the `'` could be omitted
2051 without changing the result, the compiler is much happier with the `'`
2052 in place.\]
2053
2054 `IUVECTOR` and `ISTRING` again have limitations on what *expression*
2055 may `EVAL` to; again, see sections 7.6.5 and 7.6.6.
2056
2057 Examples:
2058
2059     <ILIST 5 6>$
2060     (6 6 6 6 6)
2061     <IVECTOR 2>$
2062     [#LOSE *000000000000* #LOSE *000000000000*]
2063
2064     <SET A 0>$
2065     0
2066     <IUVECTOR 9 '<SET A <+ .A 1>>>$
2067     ![1 2 3 4 5 6 7 8 9!]
2068
2069 ### 7.5.5. FORM and IFORM
2070
2071 Sometimes the need arises to create a `FORM` without `EVAL`ing it or
2072 making it the body of a `FUNCTION`. In such cases the `SUBR`s `FORM`
2073 and `IFORM` ("implicit form") can be used (or `QUOTE` can be used).
2074 They are entirely analogous to `LIST` and `ILIST`. Example:
2075
2076     <DEFINE INC-FORM (A)
2077             <FORM SET .A <FORM + 1 <FORM LVAL .A>>>>$
2078     INC-FORM
2079     <INC-FORM FOO>$
2080     <SET FOO <+ 1 .FOO>>
2081
2082 7.6. Unique Properties of Primitive TYPEs
2083 -----------------------------------------
2084
2085 ### 7.6.1. LIST (the PRIMTYPE) \[1\]
2086
2087 An object of `PRIMTYPE` `LIST` may be considered as a "pointer chain"
2088 (appendix 1). Any Muddle object may be an element of a `PRIMTYPE`
2089 `LIST`. It is easy to add and remove elements of a `PRIMTYPE` `LIST`,
2090 but the higher N is, the longer it takes to refer to the Nth element.
2091 The `SUBR`s which work only on objects of `PRIMTYPE` `LIST` are these:
2092
2093 #### 7.6.1.1. PUTREST \[1\]
2094
2095     <PUTREST head:primtype-list tail:primtype-list>
2096
2097 changes *head* so that `<REST head>` is *tail* (actually
2098 `<CHTYPE tail LIST>`), then evaluates to *head*. Note that this
2099 actually changes *head*; it also changes anything having *head* as an
2100 element or a value. For example:
2101
2102     <SET BOW [<SET ARF (B W)>]>$
2103     [(B W)]
2104     <PUTREST .ARF '(3 4)>$
2105     (B 3 4)
2106     .BOW$
2107     [(B 3 4)]
2108
2109 `PUTREST` is probably most often used to splice lists together. For
2110 example, given that `.L` is of `PRIMTYPE` `LIST`, to leave the first
2111 *m* elements of it intact and take out the next *n* elements of it,
2112 `<PUTREST <REST .L <- m 1>> <REST .L <+ m n>>>`. Specifically,
2113
2114     <SET NUMS (1 2 3 4 5 6 7 8 9)>$
2115     (1 2 3 4 5 6 7 8 9)
2116     <PUTREST <REST .NUMS 3> <REST .NUMS 7>>$
2117     (4 8 9)
2118     .NUMS$
2119     (1 2 3 4 8 9)
2120
2121 #### 7.6.1.2. CONS
2122
2123     <CONS new list>
2124
2125 ("construct") adds *new* to the front of *list*, without copying
2126 *list*, and returns the resulting `LIST`. References to *list* are not
2127 affected.
2128
2129 \[Evaluating `<CONS .E .LIST>` is equivalent to evaluating
2130 `(.E !.LIST)` (section 7.7) but is less preferable to the compiler
2131 (Lebling, 1979).\]
2132
2133 ### 7.6.2. "Array" PRIMTYPEs \[1\]
2134
2135 `VECTORS`, `UVECTOR`s, and `STRING`s \[and `BYTES`es and `TEMPLATE`s\]
2136 may be considered as "arrays" (appendix 1). It is easy to refer to the
2137 Nth element irrespective of how large N is, and it is relatively
2138 difficult to add and delete elements. The following `SUBR`s can be
2139 used only with an object of `PRIMTYPE` `VECTOR`, `UVECTOR`, or
2140 `STRING` \[or `BYTES` or `TEMPLATE`\]. (In this section *array*
2141 represents an object of such a `PRIMTYPE`.)
2142
2143 #### 7.6.2.1. BACK \[1\]
2144
2145     <BACK array fix>
2146
2147 This is the opposite of `REST`. It evaluates to *array*, with *fix*
2148 elements put back onto its front end, and changed to its `PRIMTYPE`.
2149 *fix* is optional, 1 by default. If *fix* is greater than the number
2150 of elements which have been `REST`ed off, an error occurs. Example:
2151
2152     <SET ZOP <REST '![1 2 3 4] 3>>$
2153     ![4!]
2154     <BACK .ZOP 2>$
2155     ![2 3 4!]
2156     <SET S <REST "Right is might." 15>>$
2157     ""
2158     <BACK .S 6>$
2159     "might."
2160
2161 #### 7.6.2.2. TOP \[1\]
2162
2163     <TOP array>
2164
2165 "`BACK`s up all the way" -- that is, evaluates to *array*, with all
2166 the elements which have been `REST`ed off put back onto it, and
2167 changed to its `PRIMTYPE`. Example:
2168
2169     <TOP .ZOP>$
2170     ![1 2 3 4!]
2171
2172 ### 7.6.3. "Vector" PRIMTYPEs
2173
2174 #### 7.6.3.1. GROW
2175
2176     <GROW vu end:fix beg:fix>
2177
2178 adds/removes elements to/from either or both ends of *vu*, and returns
2179 the entire (`TOP`ped) resultant object. *vu* can be of `PRIMTYPE`
2180 `VECTOR` or `UVECTOR`. *end* specifies a lower bound for the number of
2181 elements to be added to the **end** of *vu*; *beg* specifies the same
2182 for the **beginning**. A negative *fix* specifies removal of elements.
2183
2184 The number of elements added to each respective end is *end* or *beg*
2185 **increased** to an integral multiple of *X*, where *X* is 32 for
2186 `PRIMTYPE` `VECTOR` and 64 for `PRIMTYPE` `UVECTOR` (`1` produces 32
2187 or 64; `-1` produces 0). The elements added will be `LOSE`s if *vu* is
2188 of `PRIMTYPE` `VECTOR`, and "empty" whatever-they-are's if *vu* is of
2189 `PRIMTYPE` `UVECTOR`. An "empty" object of `PRIMTYPE` `WORD` contains
2190 zero. An "empty" object of any other `PRIMTYPE` has zero in its "value
2191 word" (appendix 1) and is not safe to play with: it should be replaced
2192 via `PUT`.
2193
2194 Note that, if elements are added to the beginning of *vu*,
2195 previously-existing references to *vu* will have to use `TOP` or
2196 `BACK` to get at the added elements.
2197
2198 **Caution:** `GROW` is a **very** expensive operation; it **requires**
2199 a garbage collection (section 22.4) **every** time it is used. It
2200 should be reserved for **very special** circumstances, such as where
2201 the pattern of shared elements is terribly important.
2202
2203 Example:
2204
2205     <SET A '![1]>$
2206     ![1!]
2207     <GROW .A 0 1>$
2208     ![0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
2209     0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
2210     0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1!]
2211     .A$
2212     ![1!]
2213
2214 #### 7.6.3.2. SORT
2215
2216 This `SUBR` will sort `PRIMTYPE`s `VECTOR`, `UVECTOR` and `TUPLE`
2217 (section 9.2). It works most efficiently if the sort keys are of
2218 `PRIMTYPE` `WORD`, `ATOM` or `STRING`. However, the keys may be of any
2219 `TYPE`, and `SORT` will still work. `SORT` acts on fixed-length
2220 records which consist of one or more contiguous elements in the
2221 structure being sorted. One element in the record is declared to be
2222 the sort key. Also, any number of additional structures can be
2223 rearranged based on how the main structure is sorted.
2224
2225     <SORT pred s1 l1 off s2 l2 s3 l3 sN lN>
2226
2227 where:
2228
2229 *pred* is either (see chapter 8 for information about predicates):
2230
2231 1.  `TYPE` `FALSE`, in which case the `TYPE`s of all the sort keys
2232     must be the same; they must be of `PRIMTYPE` `WORD`, `STRING` or
2233     `ATOM`; and a radix-exchange sort is used; or
2234 2.  something applicable to two sort keys which returns `TYPE` `FALSE`
2235     if the first is not bigger than the second, in which case a shell
2236     sort is used. For example, `,G?` sorts numbers in ascending order,
2237     `,L?` in descending order. Note: if your *pred* is buggy, the
2238     `SORT` may never terminate.
2239
2240 *s1* ... *sN* are the (`PRIMTYPE`) `VECTOR`s, `UVECTOR`s or `TUPLE`s
2241 being sorted, and *s1* contains the sort keys;
2242
2243 *l1* ... *lN* are the corresponding lengths of sort records (optional,
2244 one by default); and
2245
2246 *off* is the offset from start of record to sort key (optional, zero
2247 by default).
2248
2249 `SORT` returns the sorted *s1* as a value.
2250
2251 Note: the `SUBR` `SORT` calls the `RSUBR` (chapter 19) `SORTX`; if the
2252 `RSUBR` must be loaded, you may see some output from the loader on
2253 your terminal.
2254
2255 Examples:
2256
2257     <SORT <> <SET A <IUVECTOR 500 '<RANDOM>>>>$
2258     ![...!]
2259
2260 sorts a `UVECTOR` of random integers.
2261
2262     <SET V [1 MONEY 2 SHOW 3 READY 4 GO]>$
2263     [...]
2264     <SORT <> .V 2 1>$
2265     [4 GO 1 MONEY 3 READY 2 SHOW]
2266
2267     <SORT ,L? .V 2>$
2268     [4 GO 3 READY 2 SHOW 1 MONEY]
2269     .V$
2270     [4 GO 3 READY 2 SHOW 1 MONEY]
2271
2272     <SORT <> ![2 1 4 3 6 5 8 7] 1 0 .V>$
2273     ![1 2 3 4 5 6 7 8!]
2274     .V$
2275     [GO 4 READY 3 SHOW 2 MONEY 1]
2276
2277 The first sort was based on the `ATOM`s' `PNAME`s, considering records
2278 to be two elements. The second one sorted based on the `FIX`es. The
2279 third interchanged pairs of elements of each of its structured
2280 arguments.
2281
2282 ### 7.6.4. VECTOR (the PRIMTYPE) \[1\]
2283
2284 Any Muddle object may be an element of a `PRIMTYPE` `VECTOR`. A
2285 `PRIMTYPE` `VECTOR` takes two words of storage more than an equivalent
2286 `PRIMTYPE` `LIST`, but takes it all in a contiguous chunk, whereas a
2287 `PRIMTYPE` `LIST` may be physically spread out in storage (appendix
2288 1). There are no `SUBR`s or `FSUBR`s which operate only on `PRIMTYPE`
2289 `VECTOR`.
2290
2291 ### 7.6.5. UVECTOR (the PRIMTYPE) \[1\]
2292
2293 The difference between `PRIMTYPE`s `UVECTOR` and `VECTOR` is that
2294 every element of a `PRIMTYPE` `UVECTOR` must be of the same `TYPE`. A
2295 `PRIMTYPE` `UVECTOR` takes approximately half the storage of a
2296 `PRIMTYPE` `VECTOR` or `PRIMTYPE` `LIST` and, like a `PRIMTYPE`
2297 `VECTOR`, takes it in a contiguous chunk (appendix 1).
2298
2299 \[Note: due to an implementation restriction (appendix 1), `PRIMTYPE`
2300 `STRING`s, `BYTES`es, `LOCD`s (chapter 12), and objects on the control
2301 stack (chapter 22) may **not** be elements of `PRIMTYPE` `UVECTOR`s.\]
2302
2303 The "same `TYPE`" restriction causes an equivalent restriction to
2304 apply to `EVAL` of the arguments to either of the `SUBR`s `UVECTOR` or
2305 `IUVECTOR`. Note that attempting to say
2306
2307     ![1 .A!]
2308
2309 will cause `READ` to produce an error, since you're attempting to put
2310 a `FORM` and a `FIX` into the same `UVECTOR`. On the other hand,
2311
2312     <UVECTOR 1 .A>
2313
2314 is legal, and will `EVAL` to the appropriate `UVECTOR` without error
2315 if `.A` `EVAL`s to a `TYPE` `FIX`.
2316
2317 The following `SUBR`s work on `PRIMTYPE` `UVECTOR`s along.
2318
2319 #### 7.6.5.1. UTYPE \[1\]
2320
2321     <UTYPE primtype-uvector>
2322
2323 ("uniform type") evaluates to the `TYPE` of every element in its
2324 argument. Example:
2325
2326     <UTYPE '![A B C]>$
2327     ATOM
2328
2329 #### 7.6.5.2. CHUTYPE \[1\]
2330
2331     <CHUTYPE uv:primtype-uvector type>
2332
2333 ("change uniform type") changes the `UTYPE` of *uv* to *type*,
2334 simultaneously changing the `TYPE` of all elements of *uv*, and
2335 returns the new, changed, *uv*. This works only when the `PRIMTYPE` of
2336 the elements of *uv* can remain the same through the whole procedure.
2337 (Exception: a *uv* of `UTYPE` `LOSE` can be `CHUTYPE`d to any *type*
2338 (legal in a `UVECTOR` of course); the resulting elements are "empty",
2339 as for `GROW`.)
2340
2341 `CHUTYPE` actually changes *uv*; hence **all** references to that
2342 object will reflect the change. This is quite different from `CHTYPE`.
2343
2344 Examples:
2345
2346     <SET LOST <IUVECTOR 2>>$
2347     ![#LOSE *000000000000* #LOSE *000000000000*!]
2348     <UTYPE .LOST>$
2349     LOSE
2350     <CHUTYPE .LOST FORM>$
2351     ![<> <>!]
2352     .LOST$
2353     ![<> <>!]
2354     <CHUTYPE .LOST LIST>$
2355     ![() ()!]
2356
2357 ### 7.6.6. STRING (the PRIMTYPE) and CHARACTER \[1\]
2358
2359 The best mental image of a `PRIMTYPE` `STRING` is a `PRIMTYPE`
2360 `UVECTOR` of `CHARACTER`s -- where `CHARACTER` is the Muddle `TYPE`
2361 for a single ASCII character. The representation of a `CHARACTER`, by
2362 the way, is
2363
2364     !\any-ASCII-character
2365
2366 That is, the characters `!\` (exclamation-point backslash) preceding a
2367 single ASCII character represent the corresponding object of `TYPE`
2368 `CHARACTER` (`PRIMTYPE` `WORD`). (The characters `!"`
2369 (exclamation-point double-quote) preceding a character are also
2370 acceptable for inputting a `CHARACTER`, for historical reasons.)
2371
2372 The `SUBR` `ISTRING` will produce an error if you give it an argument
2373 that produces a non-`CHARACTER`. `STRING` can take either `CHARACTER`s
2374 or `STRING`s.
2375
2376 There are no `SUBR`s which uniquely manipulate `PRIMTYPE` `STRING`s,
2377 but some are particularly useful in connection with them:
2378
2379 #### 7.6.6.1. ASCII \[1\]
2380
2381     <ASCII fix-or-character>
2382
2383 If its argument is of `TYPE` `FIX`, `ASCII` evaluates to the
2384 `CHARACTER` with the 7-bit ASCII code of its argument. Example:
2385 `<ASCII 65>` evaluates to `!\A`.
2386
2387 If its argument is of `TYPE` `CHARACTER`, `ASCII` evaluates to the
2388 `FIX`ed-point number which is its argument's 7-bit ASCII code.
2389 Example: `<ASCII !\Z>` evaluates to `90`.
2390
2391 \[Actually, a `FIX` can be `CHTYPE`d to a `CHARACTER` (or vice versa)
2392 directly, but `ASCII` checks in the former case that the `FIX` is
2393 within the permissible range.\]
2394
2395 #### 7.6.6.2. PARSE \[1\]
2396
2397     <PARSE string radix:fix>
2398
2399 `PARSE` applies to its argument `READ`'s algorithm for converting
2400 ASCII representations to Muddle objects and returns the **first**
2401 object created. The remainder of *string*, after the first object
2402 represented, is ignored. *radix* (optional, ten by default) is used
2403 for converting any `FIX`es that occur. \[See also sections 15.7.2 and
2404 17.1.3 for additional arguments.\]
2405
2406 #### 7.6.6.3. LPARSE \[1\]
2407
2408 `LPARSE` ("list parse") is exactly like `PARSE` (above), except that
2409 it parses the **entire** *string* and returns a `LIST` of **all**
2410 objects created. If given an empty `STRING` or one containing only
2411 separators, `LPARSE` returns an empty `LIST`, whereas `PARSE` gets an
2412 error.
2413
2414 #### 7.6.6.4. UNPARSE \[1\]
2415
2416     <UNPARSE any radix:fix>
2417
2418 `UNPARSE` applies to its argument `PRINT`'s algorithm for converting
2419 Muddle objects to ASCII representations and returns a `STRING` which
2420 contains the `CHARACTER`s `PRINT` would have typed out. \[However,
2421 this `STRING` will **not** contain any of the gratuitous
2422 carriage-returns `PRINT` adds to accommodate a `CHANNEL`'s finite
2423 line-width (section 11.2.8).\] *radix* (optional, ten by default) is
2424 used for converting any `FIX`es that occur.
2425
2426 ### 7.6.7. BYTES
2427
2428 A (`PRIMTYPE`) `BYTES` is a string of uniformly-sized bytes. The bytes
2429 can be any size between 1 and 36 bits inclusive. A `BYTES` is similar
2430 in some ways to a `UVECTOR` of `FIX`es and in some ways to a `STRING`
2431 of non-seven-bit bytes. The elements of a `BYTES` are always of `TYPE`
2432 `FIX`.
2433
2434 The `SUBR`s `BYTES` and `IBYTES` are similar to `STRING` and
2435 `ISTRING`, respectively, except that each of the former takes a first
2436 argument giving the size of the bytes in the generated `BYTES`.
2437 `BYTES` takes one required argument which is a `FIX` specifying a byte
2438 size and any number of `PRIMTYPE` `WORD`s. It returns an object of
2439 `TYPE` `BYTES` with that byte size containing the objects as elements.
2440 These objects will be `ANDB`ed with the appropriate mask of 1-bits to
2441 fit in the byte size. `IBYTES` takes two required `FIX`es and one
2442 optional argument. It uses the first `FIX` to specify the byte size
2443 and the second to specify the number of elements. The third argument
2444 is repeatedly evaluated to generate `FIX`es that become elements of
2445 the `BYTES` (if it is omitted, bytes filled with zeros are generated).
2446 The analog to `UTYPE` is `BYTE-SIZE`. Examples:
2447
2448     <BYTES 3 <+ 2 2> 9 -1>$
2449     #3 {4 1 7}
2450     <SET A 0>$
2451     0
2452     <IBYTES 3 9 '<SET A <+ .A 1>>>$
2453     #3 {1 2 3 4 5 6 7 0 1}
2454     <IBYTES 3 4>$
2455     #3 {0 0 0 0}
2456     <BYTE-SIZE <BYTES 1>>$
2457     1
2458
2459 ### 7.6.8. TEMPLATE
2460
2461 A `TEMPLATE` is similar to a PL/I "structure" of one level: the
2462 elements are packed together and reduced in size to save storage
2463 space, while an auxiliary internal data structure describes the
2464 packing format and the elements' real `TYPE`s (appendix 1). The
2465 interpreter is not able to create objects of `PRIMTYPE` `TEMPLATE`
2466 (Lebling, 1979); however, it can apply the standard built-in
2467 Subroutines to them, with the same effects as with other "arrays".
2468
2469 7.7. SEGMENTs \[1\]
2470 -------------------
2471
2472 Objects of `TYPE` `SEGMENT` (whose `TYPEPRIM` is `LIST`) look very
2473 much like `FORM`s. `SEGMENT`s, however, undergo a non-standard
2474 evaluation designed to ease the construction of structured objects
2475 from elements of other structured objects.
2476
2477 ### 7.7.1. Representation \[1\]
2478
2479 The representation of an object of `TYPE` `SEGMENT` is the following:
2480
2481     !< func arg-1 arg-2 ... arg-N !>
2482
2483 where the second `!` (exclamation-point) is optional, and *fun* and
2484 *arg-1* through *arg-N* are any legal constituents of a `FORM` (that
2485 is, anything). The pointed brackets can be implicit, as in the period
2486 and comma notation for `LVAL` and `GVAL`.
2487
2488 All of the following are `SEGMENT`s:
2489
2490     !<3 .FOO>    !.FOO    !,FOO
2491
2492 ### 7.7.2. Evaluation \[1\]
2493
2494 A `SEGMENT` is evaluated in exactly the same manner as a `FORM`, with
2495 the following three exceptions:
2496
2497 1.  It had better be done inside an `EVAL` of a structure; otherwise
2498     an error occurs. (See special case of `FORM`s in section 7.7.5.)
2499 2.  It had better `EVAL` to a structured object; otherwise an error
2500     occurs.
2501 3.  What actually gets inserted into the structure being built are the
2502     elements of the structure returned by the `FORM`-like evaluation.
2503
2504 ### 7.7.3 Examples \[1\]
2505
2506     <SET ZOP '![2 3 4]>$
2507     ![2 3 4!]
2508     <SET ARF (B 3 4)>$
2509     (B 3 4)
2510     (.ARF !.ZOP)$
2511     ((B 3 4) 2 3 4)
2512     ![!.ZOP !<REST .ARF>!]$
2513     ![2 3 4 3 4!]
2514
2515     <SET S "STRUNG.">$
2516     "STRUNG."
2517     (!.S)$
2518     (!\S !\T !\R !\U !\N !\G !\.)
2519
2520     <SET NIL ()>$
2521     ()
2522     [!.NIL]$
2523     []
2524
2525 ### 7.7.4. Note on Efficiency \[1\]
2526
2527 Most of the cases in which is is possible to use `SEGMENT`s require
2528 `EVAL` to generate an entire new object. Naturally, this uses up both
2529 storage and time. However, there is one case which it is possible to
2530 handle without copying, and `EVAL` uses it. When the structure being
2531 built is a `PRIMTYPE` `LIST`, and the segment value of a `PRIMTYPE`
2532 `LIST` is the last (rightmost) element being concatenated, that last
2533 `PRIMTYPE` `LIST` is not copied. This case is similar to `CONS` and is
2534 the principle reason why `PRIMTYPE` `LIST`s have their structures more
2535 easily varied than `PRIMTYPE` `VECTOR` or `UVECTOR`.
2536
2537 Examples:
2538
2539     .ARF$
2540     (B 3 4)
2541
2542 This does not copy ARF:
2543
2544     (1 2 !.ARF)$
2545     (1 2 B 3 4)
2546
2547 These do:
2548
2549     (1 !.ARF 2)              ;"not last element"$
2550     (1 B 3 4 2)
2551     [1 2 !.ARF]              ;"not PRIMTYPE LIST"$
2552     [1 2 B 3 4]
2553     (1 2 !.ARF !<REST '(1)>) ;"still not last element"$
2554     (1 2 B 3 4)
2555
2556 Note the following, which occurs because copying does **not** take
2557 place:
2558
2559     <SET DOG (A !.ARF)>$
2560     (A B 3 4)
2561     <PUT .ARF 1 "BOWOW">$
2562     ("BOWOW" 3 4)
2563     .DOG$
2564     (A "BOWOW" 3 4)
2565     <PUT .DOG 3 "WOOF">$
2566     (A "BOWOW" "WOOF" 4)
2567     .ARF$
2568     ("BOWOW" "WOOF" 4)
2569
2570 Since `ARF` was not copied, it was literally part of `DOG`. Hence,
2571 when an element of `ARF` was changed, `DOG` was changed. Similarly,
2572 when an element of `DOG` which `ARF` shared was changed, `ARF` was
2573 changed too.
2574
2575 ### 7.7.5. SEGMENTs in FORMs \[1\]
2576
2577 When a `SEGMENT` appears as an element of a `FORM`, the effect is
2578 approximately the same as if the elements of the `EVAL` of the
2579 `SEGMENT` were in the `FORM`. Example:
2580
2581     <SET A '![1 2 3 4]>$
2582     ![1 2 3 4!]
2583     <+ !.A 5>$
2584     15
2585
2586 Note: the elements of the structure segment-evaluated in a `FORM` are
2587 **not** re-evaluated if the thing being applied is a `SUBR`. Thus if
2588 `.A` were `(1 2 <+ 3 4> 5)`, the above example would produce an error:
2589 you can't add up `FORM`s.
2590
2591 You could perform the same summation of `5` and the elements of `A` by
2592 using
2593
2594     <EVAL <CHTYPE (+ !.A 5) FORM>>
2595
2596 (Note that `EVAL` must be explicitly called as a `SUBR`; if it were
2597 not so called, you would just get the `FORM` `<+ 1 2 3 4 5>` -- not
2598 its "value".) However, the latter is more expensive both in time and
2599 in storage: when you use the `SEGMENT` directly in the `FORM`, a new
2600 `FORM` is, in fact, **not** generated as it is in the latter case.
2601 (The elements are put on "the control stack" with the other
2602 arguments.)
2603
2604 7.8. Self-referencing Structures
2605 --------------------------------
2606
2607 It is possible for a structured object to "contain" itself, either as
2608 a subset or as an element, as an element of a structured element, etc.
2609 Such an object cannot be `PRINT`ed, because recursion begins and never
2610 terminates. Warning: if you try the examples in this section with a
2611 live Muddle, be sure you know how to use `^S` (section 1.2) to save
2612 `PRINT` from endless agony. (Certain constructs with `ATOM`s can give
2613 `PRINT` similar trouble: see chapters 12 and 15.)
2614
2615 ### 7.8.1. Self-subset
2616
2617     <PUTREST head:primtype-list tail:primtype-list>
2618
2619 If *head* is a subset of *tail*, that is, if `<REST tail fix>` is the
2620 same object as `<REST head 0>` for some *fix*, then both *head* and
2621 *tail* will be "circular" (and this self-referencing) after the
2622 `PUTREST`. Example:
2623
2624     <SET WALTZ (1 2 3)>$
2625     (1 2 3)
2626     <PUTREST <REST .WALTZ 2> .WALTZ>$
2627     (3 1 2 3 1 2 3 1 2 3 1 2 3 ...
2628
2629 ### 7.8.2. Self-element
2630
2631     <PUT s1:structured fix s2:structured>
2632
2633 If *s1* is the same object as *s2*, then it will "contain" itself (and
2634 thus be self-referencing) after the `PUT`. Examples:
2635
2636     <SET S <LIST 1 2 3>>        ;"or VECTOR"$
2637     (1 2 3)
2638     <PUT .S 3 .S>$
2639     (1 2 (1 2 (1 2 (1 2 ...
2640     <SET U ![![]]>$
2641     ![![!]!]
2642     <PUT .U 1 .U>$
2643     ![![![![![![...
2644
2645 Test your reaction time or your terminal's bracket-maker. Amaze your
2646 friends.
2647
2648 Chapter 8. Truth
2649 ================
2650
2651 8.1. Truth Values \[1\]
2652 -----------------------
2653
2654 Muddle represents "false" with an object of a particular `TYPE`:
2655 `TYPE` `FALSE` (unsurprisingly). `TYPE` `FALSE` is structured: its
2656 `PRIMTYPE` is `LIST`. Thus, you can give reasons or excuses by making
2657 them elements of a `FALSE`. (Again, `EVAL`ing a `FALSE` neither copies
2658 it nor `EVAL`s its elements, so it is not necessary to `QUOTE` a
2659 `FALSE` appearing in a program.) Objects of `TYPE` `FALSE` are
2660 represented in "\# notation":
2661
2662     #FALSE list-of-its-elements
2663
2664 The empty `FORM` evaluates to the empty `FALSE`:
2665
2666     <>$
2667     #FALSE ()
2668
2669 Anything which is not `FALSE`, is, reasonably enough, true. In this
2670 document the "data type" *false-or-any* in metasyntactic variables
2671 means that the only significant attribute of the object in that
2672 context is whether its `TYPE` is `FALSE` or not.
2673
2674 8.2. Predicates \[1\]
2675 ---------------------
2676
2677 There are numerous Muddle F/SUBRs which can return a `FALSE` or a
2678 true. See appendix 2 to find them all. Most return either `#FALSE ()`
2679 or the `ATOM` with `PNAME` `T`. (The latter is for historical reasons,
2680 namely Lisp (Moon, 1974).) Some predicates which are meaningful now
2681 are described next.
2682
2683 ### 8.2.1. Arithmetic \[1\]
2684
2685     <0? fix-or-float>
2686
2687 evaluates to `T` only if its argument is identically equal to `0` or
2688 `0.0`.
2689
2690     <1? fix-or-float>
2691
2692 evaluates to `T` only if its argument is identically equal to `1` or
2693 `1.0`.
2694
2695     <G? n:fix-or-float m:fix-or-float>
2696
2697 evaluates to `T` only if *n* is algebraically greater than *m*. `L=?`
2698 is the Boolean complement of `G?`; that is, it is `T` only if *n* is
2699 not algebraically greater than *m*.
2700
2701     <L? n:fix-or-float m:fix-or-float>
2702
2703 evaluates to `T` only if *n* is algebraically less than *m*. `G=?` is
2704 the Boolean complement of `L?`.
2705
2706 ### 8.2.2. Equality and Membership \[1\]
2707
2708     <==? e1:any e2:any>
2709
2710 evaluates to `T` only if *e1* is the **same object** as *e2* (appendix
2711 1). Two objects that look the same when `PRINT`ed may not be `==?`.
2712 Two `FIX`es of the same "value" are "the same object"; so are two
2713 `FLOAT`s of **exactly** the same "value". Empty objects of `PRIMTYPE`
2714 `LIST` (and no other structured `PRIMTYPE`) are `==?` if their `TYPE`s
2715 are the same. Example:
2716
2717     <==? <SET X "RANDOM STRING"> <TOP <REST .X 6>>>$
2718     T
2719     <==? .X "RANDOM STRING">$
2720     #FALSE ()
2721
2722 `N==?` is the Boolean complement of `==?`.
2723
2724     <=? e1:any e2:any>
2725
2726 evaluates to `T` if *e1* and *e2* have the same `TYPE` and are
2727 structurally equal -- that is, they "look the same", their printed
2728 representations are the same. `=?` is much slower than `==?`. `=?`
2729 should be used only when its characteristics are necessary: they are
2730 not in any comparisons of unstructured objects. `==?` and `=?` always
2731 return the same value for `FIX`es, `FLOAT`s, `ATOM`s, etc.
2732 (Mnemonically, `==?` tests for "more equality" than `=?`; in fact, it
2733 tests for actual physical identity.)
2734
2735 Example, illustrating non-copying of a `SEGMENT` in Direct
2736 Representation of a `LIST`:
2737
2738     <SET A '(1 2 3)>$
2739     (1 2 3)
2740     <==? .A (!.A)>$
2741     T
2742     <==? .A <SET B <LIST !.A>>>$
2743     #FALSE ()
2744     <=? .A .B>$
2745     T
2746
2747 `N=?` is the Boolean complement of `=?`.
2748
2749     <MEMBER object:any structured>
2750
2751 runs down *structured* from first to last element, comparing each
2752 element of *structured* with *object*. If it finds an element of
2753 *structured* which is `=?` to *object*, it returns
2754 `<REST structured i>` (which is of `TYPE` `<PRIMTYPE structured>`),
2755 where the (*i*+1)th element of *structured* is `=?` to *object*. That
2756 is, the first element of what it returns is the **first** element of
2757 *structured* that is `=?` to *object*.
2758
2759 If no element of *structured* is `=?` to *object*, `MEMBER` returns
2760 `#FALSE ()`.
2761
2762 The search is more efficient if *structured* is of `PRIMTYPE` `VECTOR`
2763 (or `UVECTOR`, if possible) than if it is of `PRIMTYPE` `LIST`. As
2764 usual, if *structured* is constant, it should be `QUOTE`d.
2765
2766 If *object* and *structured* are of `PRIMTYPE` `STRING` \[or
2767 `BYTES`\], `MEMBER` does a substring search. Example:
2768
2769     <MEMBER "PART" "SUM OF PARTS">$
2770     "PARTS"
2771
2772 `<MEMQ object:any structured>` ("member quick") is exactly the same as
2773 `MEMBER`, except that the comparison test is `==?`.
2774
2775     <STRCOMP s1 s2>
2776
2777 ("string comparison") can be given either two `STRING`s or two `ATOM`s
2778 as arguments. In the latter case the `PNAME`s are used. It actually
2779 isn't a predicate, since it can return three possible values: `0` if
2780 *s1* is `=?` to *s2*; `1` if *s1* sorts alphabetically after *s2*; and
2781 `-1` if *s1* sorts alphabetically before *s2*. "Alphabetically" means,
2782 in this case, according to the numeric order of ASCII, with the
2783 standard alphabetizing rules.
2784
2785 \[A predicate suitable for an ascending `SORT` (which see) is
2786 `<G? <STRCOMP .ARG1 .ARG2> 0>`.\]
2787
2788 ### 8.2.3. Boolean Operators \[1\]
2789
2790     <NOT e:false-or-any>
2791
2792 evaluates to `T` only if *e* evaluates to a `FALSE`, and to
2793 `#FALSE ()` otherwise.
2794
2795     <AND e1 e2 ... eN>
2796
2797 `AND` is an `FSUBR`. It evaluates its arguments from first to last as
2798 they appear in the `FORM`. As soon as one of them evaluates to a
2799 `FALSE`, it returns that `FALSE`, ignoring any remaining arguments. If
2800 none of them evaluate to `FALSE`, it returns `EVAL` of its last
2801 argument. `<AND>` returns `T`. `AND?` is the `SUBR` equivalent to
2802 `AND`, that is, all its arguments are evaluated before any of them is
2803 tested.
2804
2805     <OR e1 e2 ... eN>
2806
2807 `OR` is an `FSUBR`. It evaluates its arguments from first to last as
2808 they appear in the `FORM`. As soon as one of them evaluates to a
2809 non-`FALSE`, it returns that non-`FALSE` value, ignoring any remaining
2810 arguments. If this never occurs, it returns the last `FALSE` it saw.
2811 `<OR>` returns `#FALSE ()`. `OR?` is the `SUBR` equivalent to `OR`.
2812
2813 ### 8.2.4. Object Properties \[1\]
2814
2815     <TYPE? any type-1 ... type-N>
2816
2817 evaluates to *type-i* only if `<==? type-i <TYPE any>>` is true. It is
2818 faster and gives more information than `OR`ing tests for each `TYPE`.
2819 If the test fails for all *type-i*'s, `TYPE?` returns `#FALSE ()`.
2820
2821     <APPLICABLE? e>
2822
2823 evaluates to `T` only if *e* is of a `TYPE` that can legally be
2824 applied to arguments in a `FORM`, that is, be (`EVAL` of) the first
2825 element of a `FORM` being evaluated (appendix 3).
2826
2827     <MONAD? e>
2828
2829 evaluates to `#FALSE ()` only if `NTH` and `REST` (with non-zero
2830 second argument) can be performed on its argument without error. An
2831 unstructured or empty structured object will cause `MONAD?` to return
2832 `T`.
2833
2834     <STRUCTURED? e>
2835
2836 evaluates to `T` only if *e* is a structured object. It is **not** the
2837 inverse of `MONAD?`, since each returns `T` if its argument is an
2838 empty structure.
2839
2840     <EMPTY? structured>
2841
2842 evaluates to `T` only if its argument, which must be a structured
2843 object, has no elements.
2844
2845     <LENGTH? structured fix>
2846
2847 evaluates to `<LENGTH structured>` only if that is less than or equal
2848 to *fix*; otherwise, it evaluates to `#FALSE ()`. Mnemonically, you
2849 can think of the first two letters of `LENGTH?` as signifying the
2850 "less than or equal to" sense of the test.
2851
2852 This `SUBR` was invented to use on lists, because Muddle can determine
2853 their lengths only by stepping along the list, counting the elements.
2854 If a program needs to know only how the length compares with a given
2855 number, `LENGTH?` will tell without necessarily stepping all the way
2856 to the end of the list, in contrast to `LENGTH`.
2857
2858 \[If *structured* is a circular `PRIMTYPE` `LIST`, `LENGTH?` will
2859 return a value, whereas `LENGTH` will execute forever. To see if you
2860 can do `<REST structured <+ 1 fix>>` without error, do the test
2861 `<NOT <LENGTH? structured fix>>`.\]
2862
2863 8.3. COND \[1\]
2864 ---------------
2865
2866 The Muddle Subroutine which is most used for varying evaluation
2867 depending on a truth value is the `FSUBR` `COND` ("conditional"). A
2868 call to `COND` has this format:
2869
2870     <COND clause-1:list ... clause-N:list>
2871
2872 where *N* is at least one.
2873
2874 `COND` always returns the result of the **last** evaluation it
2875 performs. The following rules determine the order of evaluations
2876 performed.
2877
2878 1.  Evaluate the first element of each clause (from first to last)
2879     until either a non-`FALSE` object results or the clauses are
2880     exhausted.
2881 2.  If a non-`FALSE` object is found in (1), immediately evaluate the
2882     remaining elements (if any) of that clause and ignore any
2883     remaining clauses.
2884
2885 In other words, `COND` goes walking down its clauses, `EVAL`ing the
2886 first element of each clause, looking for a non-`FALSE` result. As
2887 soon as it finds a non-`FALSE`, it forgets about all the other clauses
2888 and evaluates, in order, the other elements of the current clause and
2889 returns the last thing it evaluates. If it can't find a non-`FALSE`,
2890 it returns the last `FALSE` it saw.
2891
2892 ### 8.3.1. Examples
2893
2894     <SET F '(1)>$
2895     (1)
2896     <COND (<EMPTY? .F> EMP) (<1? <LENGTH .F>> ONE)>$
2897     ONE
2898     <SET F ()>$
2899     ()
2900     <COND (<EMPTY? .F> EMP) (<1? <LENGTH .F>> ONE)>$
2901     EMP
2902     <SET F '(1 2 3)>$
2903     (1 2 3)
2904     <COND (<EMPTY? .F> EMP) (<1? <LENGTH .F>> ONE)>$
2905     #FALSE ()
2906     <COND (<LENGTH? .F 2> SMALL) (BIG)>$
2907     BIG
2908
2909     <DEFINE FACT (N)        ;"the standard recursive factorial"
2910             <COND (<0? .N> 1)
2911                   (ELSE <* .N <FACT <- .N 1>>>)>>$
2912     FACT
2913     <FACT 5>$
2914     120
2915
2916 8.4. Shortcuts with Conditionals
2917 --------------------------------
2918
2919 ### 8.4.1. AND and OR as Short CONDs
2920
2921 Since `AND` and `OR` are `FSUBR`s, they can be used as miniature
2922 `COND`s. A construct of the form
2923
2924     <AND pre-conditions action(s)>
2925
2926 or
2927
2928     <OR pre-exclusions action(s)>
2929
2930 will allow *action(s)* to be evaluated only if all the
2931 *pre-conditions* are true or only if all the *pre-exclusions* are
2932 false, respectively. By nesting and using both `AND` and `OR`, fairly
2933 powerful constructs can be made. Of course, if *action(s)* are more
2934 than one thing, you must be careful that none but the last returns
2935 false or true, respectively. Watch out especially for `TERPRI`
2936 (chapter 11). Examples:
2937
2938     <AND <ASSIGNED? FLAG> .FLAG <FCN .ARG>>
2939
2940 applies `FCN` only if someone else has `SET` `FLAG` to true.
2941 (`ASSIGNED?` is true if its argument `ATOM` has an `LVAL`.) No error
2942 can occur in the testing of `FLAG` because of the order of evaluation.
2943
2944     <AND <SET C <OPEN "READ" "A FILE">> <LOAD .C> <CLOSE .C>>
2945
2946 effectively `FLOAD`s the file (chapter 11) without the possibility of
2947 getting an error if the file cannot be opened.
2948
2949 ### 8.4.2. Embedded Unconditionals
2950
2951 One of the disadvantages of `COND` is that there is no straightforward
2952 way to do things unconditionally in between tests. One way around this
2953 problem is to insert a dummy clause that never succeeds, because its
2954 only `LIST` element is an `AND` that returns a `FALSE` for the test.
2955 Example:
2956
2957     <COND   (<0? .N> <F0 .N>)
2958             (<1? .N> <F1 .N>)
2959             (<AND <SET N <* 2 <FIX </ .N 2>>>>
2960                             ;"Round .N down to even number."
2961                   <>>)
2962             (<LENGTH? .VEC .N> '[])
2963             (T <REST .VEC <+ 1 .N>>)>
2964
2965 A variation is to make the last `AND` argument into the test for the
2966 `COND` clause. (That is, the third and fourth clauses in the above
2967 example can be combined.) Of course, you must be careful that no other
2968 `AND` argument evaluates to a `FALSE`; most Subroutines do not return
2969 a `FALSE` without a very good reason for it. (A notable exception is
2970 `TERPRI` (which see).) Even safer is to use `PROG` (section 10.1)
2971 instead of `AND`.
2972
2973 Another variation is to increase the nesting with a new `COND` after
2974 the unconditional part. At least this method does not make the code
2975 appear to a human reader as though it does something other than what
2976 it really does. The above example could be done this way:
2977
2978     <COND   (<0? .N> <F0 .N>)
2979             (<1? .N> <F1 .N>)
2980             (T
2981              <SET N <* 2 <FIX </ .N 2>>>>
2982              <COND  (<LENGTH? .VEC .N> '[])
2983                     (T <REST .VEC <+ 1 .N>>)>)>
2984
2985 Chapter 9. Functions
2986 ====================
2987
2988 This chapter could be named "fun and games with argument `LIST`s". Its
2989 purpose is to explain the more complicated things which can be done
2990 with `FUNCTION`s, and this involves, basically, explaining all the
2991 various tokens which can appear in the argument `LIST` of a
2992 `FUNCTION`. Topics are covered in what is approximately an order of
2993 increasing complexity. This order has little to do with the order in
2994 which tokens can actually appear in an argument `LIST`, so what an
2995 argument `LIST` "looks like" overall gets rather lost in the shuffle.
2996 To alleviate this problem, section 9.9 is a summary of everything that
2997 can go into an argument `LIST`, in the correct order. If you find
2998 yourself getting lost, please refer to that summary.
2999
3000 9.1. "OPTIONAL" \[1\]
3001 ---------------------
3002
3003 Muddle provides very convenient means for allowing optional arguments.
3004 The `STRING` `"OPTIONAL"` (or `"OPT"` -- they're totally equivalent)
3005 in the argument `LIST` allows the specification of optional arguments
3006 with values to be assigned by default. The syntax of the `"OPTIONAL"`
3007 part of the argument `LIST` is as follows:
3008
3009     "OPTIONAL" al-1 al-2 ... al-N
3010
3011 First, there is the `STRING` `"OPTIONAL"`. Then there is any number of
3012 either `ATOM`s or two-element `LIST`s, intermixed, one per optional
3013 argument. The first element of each two-element `LIST` must be an
3014 `ATOM`; this is the dummy variable. The second element is an arbitrary
3015 Muddle expression. If there are required arguments, they must come
3016 before the `"OPTIONAL"`.
3017
3018 When `EVAL` is binding the variables of a `FUNCTION` and sees
3019 `"OPTIONAL"`, the following happens:
3020
3021 -   If an explicit argument was given in the position of an optional
3022     one, the explicit argument is bound to the corresponding dummy
3023     `ATOM`.
3024 -   If there is no explicit argument and the `ATOM` stands alone, that
3025     is, it is not the first element of a two-element `LIST`, that
3026     `ATOM` becomes "bound", but no local value is assigned to it \[see
3027     below\]. A local value can be assigned to it by using `SET`.
3028 -   If there is no explicit argument and the `ATOM` is the first
3029     element of a two-element `LIST`, the Muddle expression in the
3030     `LIST` with the `ATOM` is evaluated and bound to the `ATOM`.
3031
3032 \[Until an `ATOM` is assigned, any attempt to reference its `LVAL`
3033 will produce an error. The predicate `SUBR`s `BOUND?` and `ASSIGNED?`
3034 can be used to check for such situations. `BOUND?` returns `T` if its
3035 argument is currently bound via an argument `LIST` or has ever been
3036 `SET` while not bound via an argument `LIST`. The latter kind of
3037 binding is called "top-level binding", because it is done outside all
3038 active argument-`LIST` binding. `ASSIGNED?` will return `#FALSE ()` if
3039 its argument is **either** unassigned **or** unbound. By the way,
3040 there are two predicates for global values similar to `BOUND?` and
3041 `ASSIGNED?`, namely `GBOUND?` and `GASSIGNED?`. Each returns `T` only
3042 if its argument, which (as in `BOUND?` and `ASSIGNED?`) must be an
3043 `ATOM`, has a global value "slot" (chapter 22) or a global value,
3044 respectively.\]
3045
3046 Example:
3047
3048     <DEFINE INC1 (A "OPTIONAL" (N 1)) <SET .A <+ ..A .N>>>$
3049     INC1
3050     <SET B 0>$
3051     0
3052     <INC1 B>$
3053     1
3054     <INC1 B 5>$
3055     0
3056
3057 Here we defined another (not quite working) increment `FUNCTION`. It
3058 now takes an optional argument specifying how much to increment the
3059 `ATOM` it is given. If not given, the increment is `1`. Now, `1` is a
3060 pretty simple Muddle expression: there is no reason why the optional
3061 argument cannot be complicated -- for example, a call to a `FUNCTION`
3062 which reads a file on an I/O device.
3063
3064 9.2. TUPLEs
3065 -----------
3066
3067 ### 9.2.1. "TUPLE" and TUPLE (the TYPE) \[1\]
3068
3069 There are also times when you want to be able to have an arbitrary
3070 number of arguments. You can always do this by defining the `FUNCTION`
3071 as having a structure as its argument, with the arbitrary number of
3072 arguments as elements of the structure. This can, however, lead to
3073 inelegant-looking `FORM`s and extra garbage to be collected. The
3074 `STRING` `"TUPLE"` appearing in the argument `LIST` allows you to
3075 avoid that. It must follow explicit and optional dummy arguments (if
3076 there are any of either) and must be followed by an `ATOM`.
3077
3078 The effect of `"TUPLE"` appearing in an argument `LIST` is the
3079 following: any arguments left in the `FORM`, after satisfying explicit
3080 and optional arguments, are `EVAL`ed and made sequential elements of
3081 an object of `TYPE` and `PRIMTYPE` `TUPLE`. The `TUPLE` is the bound
3082 to the `ATOM` following `"TUPLE"` in the argument `LIST`. If there
3083 were no arguments left by the time the `"TUPLE"` was reached, an empty
3084 `TUPLE` is bound to the `ATOM`.
3085
3086 An object of `TYPE` `TUPLE` is exactly the same as a `VECTOR` except
3087 that a `TUPLE` is not held in garbage-collected storage. It is instead
3088 held with `ATOM` bindings in a control stack. This does not affect
3089 manipulation of the `TUPLE` within the function generating it or any
3090 function called within that one: it can be treated just like a
3091 `VECTOR`. Note, however, that a `TUPLE` ceases to exist when the
3092 function which generated it returns. Returning a `TUPLE` as a value is
3093 a good way to generate an error. (A copy of a `TUPLE` can easily be
3094 generated by segment-evaluating the `TUPLE` into something; that copy
3095 can be returned.) The predicate `LEGAL?` returns `#FALSE ()` if it is
3096 given a `TUPLE` generated by an `APPLICABLE` object which has already
3097 returned, and `T` if it is given a `TUPLE` which is still "good".
3098
3099 Example:
3100
3101     <DEFINE NTHARG (N "TUPLE" T)
3102                     ;"Get all but first argument into T."
3103         <COND (<==? 1 .N> 1)
3104                     ;"If N is 1, return 1st arg, i.e., .N,
3105                       i.e., 1.  Note that <1? .N> would be
3106                       true even if .N were 1.0."
3107               (<L? <LENGTH .T> <SET N <- .N 1>>>
3108                #FALSE ("DUMMY"))
3109                     ;"Check to see if there is an Nth arg,
3110                       and make N a good index into T while
3111                       you're at it.
3112                       If there isn't an Nth arg, complain."
3113               (ELSE <NTH .T .N>)>>
3114
3115 `NTHARG`, above, takes any number of arguments. Its first argument
3116 must be of `TYPE` `FIX`. It returns `EVAL` of its Nth argument, if it
3117 has an Nth argument. If it doesn't, it returns `#FALSE ("DUMMY")`.
3118 (The `ELSE` is not absolutely necessary in the last clause. If the Nth
3119 argument is a `FALSE`, the `COND` will return that `FALSE`.) Exercise
3120 for the reader: `NTHARG` will generate an error if its first argument
3121 is not `FIX`. Where and why? (How about `<NTHARG 1.5 2 3>`?) Fix it.
3122
3123 ### 9.2.2. TUPLE (the SUBR) and ITUPLE
3124
3125 These `SUBR`s are the same as `VECTOR` and `IVECTOR`, except that they
3126 build `TUPLE`s (that is, vectors on the control stack). They can be
3127 used only at top level in an `"OPTIONAL"` list or `"AUX"` list (see
3128 below). The clear advantage of `TUPLE` and `ITUPLE` ("implicit tuple")
3129 is in storage-management efficiency. They produce no garbage, since
3130 they are flushed automatically upon function return.
3131
3132 Examples:
3133
3134     <DEFINE F (A B "AUX" (C <ITUPLE 10 3>)) ...>
3135
3136 creates a 10-element `TUPLE` and `SET`s `C` to it.
3137
3138     <DEFINE H ("OPTIONAL" (A <ITUPLE 10 '<I>>)
3139                     "AUX" (B <TUPLE !.A 1 2 3>))
3140                     ...>
3141
3142 These are valid uses of `TUPLE` and `ITUPLE`. However, the following
3143 is **not** a valid use of `TUPLE`, because it is not called at top
3144 level of the `"AUX"`:
3145
3146     <DEFINE NO (A B "AUX" (C <REST <TUPLE !.A>>)) ...>
3147
3148 However, the desired effect could be achieved by
3149
3150     <DEFINE OK (A B "AUX" (D <TUPLE !.A>) (C <REST .D>)) ...>
3151
3152 9.3 "AUX" \[1\]
3153 ---------------
3154
3155 `"AUX"` (or `"EXTRA"` -- they're totally equivalent) are `STRING`s
3156 which, placed in an argument `LIST`, serve to dynamically allocate
3157 temporary variables for the use of a Function.
3158
3159 `"AUX"` must appear in the argument `LIST` after any information about
3160 explicit arguments. It is followed by `ATOM`s or two-element `LIST`s
3161 as if it were `"OPTIONAL"`. `ATOM`s in the two-element `LIST`s are
3162 bound to `EVAL` of the second element in the `LIST`. Atoms not in such
3163 `LIST`s are initially **unassigned**: they are explicitly given "no"
3164 `LVAL`.
3165
3166 All binding specified in an argument `LIST` is done sequentially from
3167 first to last, so initialization expressions for `"AUX"` (or
3168 `"OPTIONAL"`) can refer to objects which have just been bound. For
3169 example, this works:
3170
3171     <DEFINE AUXEX ("TUPLE" T
3172                      "AUX" (A <LENGTH .T>) (B <* 2 .A>))
3173             ![.A .B]>$
3174     AUXEX
3175     <AUXEX 1 2 "FOO">$
3176     ![3 6!]
3177
3178 9.4. QUOTEd arguments
3179 ---------------------
3180
3181 If an `ATOM` in an argument `LIST` which is to be bound to a required
3182 or optional argument is surrounded by a call to `QUOTE`, that `ATOM`
3183 is bound to the **unevaluated** argument. Example:
3184
3185     <DEFINE Q2 (A 'B) (.A .B)>$
3186     Q2
3187     <Q2 <+ 1 2> <+ 1 2>>$
3188     (3 <+ 1 2>)
3189
3190 It is not often appropriate for a function to take its arguments
3191 unevaluated, because such a practice makes it less modular and harder
3192 to maintain: it and the programs that call it tend to need to know
3193 more about each other, and a change in its argument structure would
3194 tend to require more changes in the programs that call it. And, since
3195 few functions, in practice, do take unevaluated arguments, users tend
3196 to assume that no functions do (except `FSUBR`s of course), and
3197 confusion inevitably results.
3198
3199 9.5. "ARGS"
3200 -----------
3201
3202 The indicator `"ARGS"` can appear in an argument `LIST` with precisely
3203 the same syntax as `"TUPLE"`. However, `"ARGS"` causes the `ATOM`
3204 following it to be bound to a `LIST` of the remaining **unevaluated**
3205 arguments.
3206
3207 `"ARGS"` does not cause any copying to take place. It simply gives you
3208
3209     <REST application:form fix>
3210
3211 with an appropriate *fix*. The `TYPE` change to `LIST` is a result of
3212 the `REST`. Since the `LIST` shares all its elements with the original
3213 `FORM`, `PUT`s into the `LIST` will change the calling program,
3214 however dangerous that may be.
3215
3216 Examples:
3217
3218     <DEFINE QIT (N "ARGS" L) <.N .L>>$
3219     QIT
3220     <QIT 2 <+ 3 4 <LENGTH ,QALL> FOO>$
3221     <LENGTH ,QALL>
3222
3223     <DEFINE FUNCT1 ("ARGS" ARGL-AND-BODY)
3224             <CHTYPE .ARGL-AND-BODY FUNCTION>>$
3225     FUNCT1
3226     <FUNCT1 (A B) <+ .A .B>>$
3227     #FUNCTION ((A B) <+ .A .B>)
3228
3229 The last example is a perfectly valid equivalent of the `FSUBR`
3230 `FUNCTION`.
3231
3232 9.6. "CALL"
3233 -----------
3234
3235 The indicator `"CALL"` is an ultimate `"ARGS"`. If it appears in an
3236 argument `LIST`, it must be followed by an `ATOM` and must be the only
3237 thing used to gather arguments. `"CALL"` causes the `ATOM` which
3238 follows it to become bound to the actual `FORM` that is being
3239 evaluated -- that is, you get the "function call" itself. Since
3240 `"CALL"` binds to the `FORM` itself, and not a copy, `PUT`s into that
3241 `FORM` will change the calling code.
3242
3243 `"CALL"` exists as a Catch-22 for argument manipulation. If you can't
3244 do it with `"CALL"`, it can't be done.
3245
3246 9.7. EVAL and "BIND"
3247 --------------------
3248
3249 Obtaining unevaluated arguments, for example, for `QUOTE` and
3250 `"ARGS"`, very often implies that you wish to evaluate them at some
3251 point. You can do this by explicitly calling `EVAL`, which is a
3252 `SUBR`. Example:
3253
3254     <SET F '<+ 1 2>>$
3255     <+ 1 2>
3256     <EVAL .F>$
3257     3
3258
3259 `EVAL` can take a second argument, of `TYPE` `ENVIRONMENT` (or others,
3260 see section 20.8). An `ENVIRONMENT` consists basically of a state of
3261 `ATOM` bindings; it is the "world" mentioned in chapter 5. Now, since
3262 binding changes the `ENVIRONMENT`, if you wish to use `EVAL` within a
3263 `FUNCTION`, you probably want to get hold of the environment which
3264 existed **before** that `FUNCTION`'s binding took place. The indicator
3265 `"BIND"`, which must, if it is used, be the first thing in an argument
3266 `LIST`, provides this information. It binds the `ATOM` immediately
3267 following it to the `ENVIRONMENT` existing "at call time" -- that is,
3268 just before any binding is done for its `FUNCTION`. Example:
3269
3270     <SET A 0>$
3271     0
3272     <DEFINE WRONG ('B "AUX" (A 1)) <EVAL .B>>$
3273     WRONG
3274     <WRONG .A>
3275     1
3276     <DEFINE RIGHT ("BIND" E 'B "AUX" (A 1)) <EVAL .B .E>>$
3277     RIGHT
3278     <RIGHT .A>$
3279     0
3280
3281 ### 9.7.1. Local Values versus ENVIRONMENTs
3282
3283 `SET`, `LVAL`, `VALUE`, `BOUND?`, `ASSIGNED?`, and `UNASSIGN` all take
3284 a final optional argument which has not previously been mentioned: an
3285 `ENVIRONMENT` (or other `TYPE`s, see section 20.8). If this argument
3286 is given, the `SET` or `LVAL` is done in the `ENVIRONMENT` specified.
3287 `LVAL` cannot be abbreviated by `.` (period) if it is given an
3288 explicit second argument.
3289
3290 This feature is just what is needed to cure the `INC` bug mentioned in
3291 chapter 5. A "correct" `INC` can be defined as follows:
3292
3293     <DEFINE INC ("BIND" OUTER ATM)
3294             <SET .ATM <+ 1 <LVAL .ATM .OUTER>> .OUTER>>
3295
3296 9.8. ACTIVATION, "NAME", "ACT", "AGAIN", and RETURN \[1\]
3297 ---------------------------------------------------------
3298
3299 `EVAL`uation of a `FUNCTION`, after the argument `LIST` has been taken
3300 care of, normally consists of `EVAL`uating each of the objects in the
3301 body in the order given, and returning the value of the last thing
3302 `EVAL`ed. If you want to vary this sequence, you need to know, at
3303 least, where the `FUNCTION` begins. Actually, `EVAL` normally hasn't
3304 the foggiest idea of where its current `FUNCTION` began. "Where'd I
3305 start" information is bundled up with a `TYPE` called `ACTIVATION`. In
3306 "normal" `FUNCTION` `EVAL`uation, `ACTIVATION`s are not generated: one
3307 can be generated, and bound to an `ATOM`, in either of the two
3308 following ways:
3309
3310 1.  Put an `ATOM` immediately before the argument `LIST`. The
3311     `ACTIVATION` of the Function will be bound to that `ATOM`.
3312 2.  As the last thing in the argument `LIST`, insert either of the
3313     `STRING`s `"NAME"` or `"ACT"` and follow it with an `ATOM`. The
3314     `ATOM` will be bound to the `ACTIVATION` of the Function.
3315
3316 In this document "Function" (capitalized) will designate anything that
3317 can generate an `ACTIVATION`; besides `TYPE` `FUNCTION`, this class
3318 includes the `FSUBR`s `PROG`, `BIND`, and `REPEAT`, yet to be
3319 discussed.
3320
3321 Each `ACTIVATION` refers explicitly to a particular evaluation of a
3322 Function. For example, if a recursive `FUNCTION` generates an
3323 `ACTIVATION`, a new `ACTIVATION` referring explicitly to each
3324 recursion step is generated on every recursion.
3325
3326 Like `TUPLE`s, `ACTIVATION`s are held in a control stack. Unlike
3327 `TUPLE`s, there is **no way** to get a copy of an `ACTIVATION` which
3328 can usefully be returned as a value. (This is a consequence of the
3329 fact that `ACTIVATION`s refer to evaluations; when the evaluation is
3330 finished, the `ACTIVATION` no longer exists.) `ACTIVATION`s can be
3331 tested, like `TUPLE`s, by `LEGAL?` for legality. They are used by the
3332 `SUBR`s `AGAIN` and `RETURN`.
3333
3334 `AGAIN` can take one argument: an `ACTIVATION`. It means "start doing
3335 this again", where "this" is specified by the `ACTIVATION`.
3336 Specifically, `AGAIN` causes `EVAL` to return to where it started
3337 working on the **body** of the Function in the evaluation specified by
3338 the `ACTIVATION`. The evaluation is not redone completely: in
3339 particular, no re-binding (of arguments, `"AUX"` variables, etc.) is
3340 done.
3341
3342 `RETURN` can take two arguments: an arbitrary expression and an
3343 `ACTIVATION`, in that order. It causes the Function evaluation whose
3344 `ACTIVATION` it is given to terminate and return `EVAL` of `RETURN`'s
3345 first argument. That is, `RETURN` means "quit doing this and return
3346 that", where "this" is the `ACTIVATION` -- its second argument -- and
3347 "that" is the expression -- its first argument. Example:
3348
3349     <DEFINE MY+ ("TUPLE" T "AUX" (M 0) "NAME" NM)
3350             <COND (<EMPTY? .T> <RETURN .M .NM>)>
3351             <SET M <+ .M <1 .T>>>
3352             <SET T <REST .T>>
3353             <AGAIN .NM>>$
3354     MY+
3355     <MY+ 1 3 <LENGTH "FOO">>$
3356     7
3357     <MY+>$
3358     0
3359
3360 Note: suppose an `ACTIVATION` of one Function (call it `F1`) is passed
3361 to another Function (call it `F2`) -- for example, via an application
3362 of `F2` within `F1` with `F1`'s `ACTIVATION` as an argument. If `F2`
3363 `RETURN`s to `F1`'s `ACTIVATION`, `F2` **and** `F1` terminate
3364 immediately, and **`F1`** returns the `RETURN`'s first argument. This
3365 technique is suitable for error exits. `AGAIN` can clearly pull a
3366 similar trick. In the following example, `F1` computes the sum of `F2`
3367 applied to each of its arguments; `F2` computes the product of the
3368 elements of its structured argument, but it aborts if it finds an
3369 element that is not a number.
3370
3371     <DEFINE F1 ACT ("TUPLE" T "AUX" (T1 .T))
3372             <COND (<NOT <EMPTY? .T1>>
3373                    <PUT .T1 1 <F2 <1 .T1> .ACT>>
3374                    <SET T1 <REST .T1>>
3375                    <AGAIN .ACT>)
3376                   (ELSE <+ !.T>)>>$
3377     F1
3378     <DEFINE F2 (S A "AUX" (S1 .S))
3379             <REPEAT MY-ACT ((PRD 1))
3380                <COND (<NOT <EMPTY? .S1>>
3381                       <COND (<NOT <TYPE? 1 .S1> FIX FLOAT>>
3382                              <RETURN #FALSE ("NON-NUMBER") .A>)
3383                             (ELSE <SET PRD <* .PRD <1 .S1>>>)>
3384                       <SET S1 <REST .S1>>)
3385                      (ELSE <RETURN .PRD>)>>>$
3386     F2
3387
3388     <F1 '(1 2) '(3 4)>$
3389     14
3390     <F1 '(T 2) '(3 4)>$
3391     #FALSE ("NON-NUMBER")
3392
3393 9.9. Argument List Summary
3394 --------------------------
3395
3396 The following is a listing of all the various tokens which can appear
3397 in the argument `LIST` of a `FUNCTION`, in the order in which they can
3398 occur. Short descriptions of their effects are included. **All** of
3399 them are **optional** -- that is, any of them (in any position) can be
3400 left out or included -- but the order in which they appear **must** be
3401 that of this list. "`QUOTE`d `ATOM`", "matching object", and "2-list"
3402 are defined below.
3403
3404 (1) `"BIND"`
3405
3406 must be followed by an `ATOM`. It binds that `ATOM` to the
3407 `ENVIRONMENT` which existed when the `FUNCTION` was applied.
3408
3409 (2) `ATOM`s and `QUOTE`d `ATOM`s (any number)
3410
3411 are required arguments. `QUOTE`d `ATOM`s are bound to the matching
3412 object. `ATOM`s are bound to `EVAL` of the matching object in the
3413 `ENVIRONMENT` existing when the `FUNCTION` was applied.
3414
3415 (3) `"OPTIONAL"` or `"OPT"` (they're equivalent)
3416
3417 is followed by any number of `ATOM`s, `QUOTE`d `ATOM`s, or 2-lists.
3418 These are optional arguments. If a matching object exists, an `ATOM`
3419 -- either standing alone or the first element of a 2-list -- is bound
3420 to `EVAL` of the object, performed in the `ENVIRONMENT` existing when
3421 the `FUNCTION` was applied. A `QUOTE`d `ATOM` -- alone or in a 2-list
3422 -- is bound to the matching object itself. If no such object exists,
3423 `ATOM`s and `QUOTE`d `ATOM`s are left unbound, and the first element
3424 of each 2-list is bound to `EVAL` of the corresponding second element.
3425 (This `EVAL` is done in the new `ENVIRONMENT` of the Function as it is
3426 being constructed.)
3427
3428 (4) `"ARGS"` (and **not** `"TUPLE"`)
3429
3430 must be followed by an `ATOM`. The `ATOM` is bound to a `LIST` of
3431 **all** the remaining arguments, **unevaluated**. (If there are no
3432 more arguments, the `LIST` is empty.) This `LIST` is actually a `REST`
3433 of the `FORM` applying the `FUNCTION`. If `"ARGS"` appears in the
3434 argument `LIST`, `"TUPLE"` should not appear.
3435
3436 (4) `"TUPLE"` (and **not** `"ARGS"`)
3437
3438 must be followed by an `ATOM`. The `ATOM` is bound to a `TUPLE`
3439 ("`VECTOR` on the control stack") of all the remaining arguments,
3440 **evaluated** in the environment existing when the `FUNCTION` was
3441 applied. (If no arguments remain, the `TUPLE` is empty.) If `"TUPLE"`
3442 appears in the argument `LIST`, `"ARGS"` should not appear.
3443
3444 (5) `"AUX"` or `"EXTRA"` (they're equivalent)
3445
3446 is followed by any number of `ATOM`s or 2-lists. These are auxiliary
3447 variables, bound away from the previous environment for the use of
3448 this Function. `ATOM`s are bound in the `ENVIRONMENT` of the Function,
3449 but they are unassigned; the first element of each 2-list is both
3450 bound and assigned to `EVAL` of the corresponding second element.
3451 (This `EVAL` is done in the new `ENVIRONMENT` of the Function as it is
3452 being constructed.)
3453
3454 (6) `"NAME"` or `"ACT"` (they're equivalent)
3455
3456 must be followed by an `ATOM`. The `ATOM` is bound to the `ACTIVATION`
3457 of the current evaluation of the Function.
3458
3459 **ALSO** -- in place of sections (2) (3) **and** (4), you can have
3460
3461 (2-3-4) `"CALL"`
3462
3463 which must be followed by an `ATOM`. The `ATOM` is bound to the `FORM`
3464 which caused application of this `FUNCTION`.
3465
3466 The special terms used above mean this:
3467
3468 "`QUOTE`d `ATOM`" -- a two-element `FORM` whose first element is the
3469 `ATOM` `QUOTE`, and whose second element is any `ATOM`. (Can be typed
3470 -- and will be `PRINT`ed -- as `'atom`.)
3471
3472 "Matching object" -- that element of a `FORM` whose position in the
3473 `FORM` matches the position of a required or optional argument in an
3474 argument `LIST`.
3475
3476 "2-list" -- a two-element `LIST` whose first element is an `ATOM` (or
3477 `QUOTE`d `ATOM`: see below) and whose second element can be anything
3478 but a `SEGMENT`. `EVAL` of the second element is assigned to a new
3479 binding of the first element (the `ATOM`) as the "value by default" in
3480 `"OPTIONAL"` or the "initial value" in `"AUX"`. In the case of
3481 `"OPTIONAL"`, the first element of a 2-list can be a `QUOTE`d `ATOM`;
3482 in this case, an argument which is supplied is not `EVAL`ed, but if it
3483 is not supplied the second element of the `LIST` **is** `EVAL`ed and
3484 assigned to the `ATOM`.
3485
3486 9.10. APPLY \[1\]
3487 -----------------
3488
3489 Occasionally there is a valid reason for the first element of a `FORM`
3490 not to be an `ATOM`. For example, the object to be applied to
3491 arguments may be chosen at run time, or it may depend on the arguments
3492 in some way. While `EVAL` is perfectly happy in this case to
3493 `EVAL`uate the first element and go on from there, the compiler
3494 (Lebling, 1979) can generate more efficient code if it knows whether
3495 the result of the evaluation will (1) always be of `TYPE` `FIX`, (2)
3496 always be an applicable non-`FIX` object that evaluates all its
3497 arguments, or (3) neither. The easiest way to tell the compiler if (1)
3498 or (2) is true is to use the `ATOM` `NTH` (section 7.1.2) or `PUT`
3499 (section 7.1.4) in case (1) or `APPLY` in case (2) as the first
3500 element of the `FORM`. (Note: case (1) can compile into in-line code,
3501 but case (2) compiles into a fully mediated call into the
3502 interpreter.)
3503
3504     <APPLY object arg-1 ... arg-N>
3505
3506 evaluates *object* and all the *arg-i*'s and then applies the former
3507 to all the latter. An error occurs if *object* evaluates to something
3508 not applicable, or to an `FSUBR`, or to a `FUNCTION` (or user
3509 Subroutine -- chapter 19) with `"ARGS"` or `"CALL"` or `QUOTE`d
3510 arguments.
3511
3512 Example:
3513
3514     <APPLY <NTH .ANALYZERS
3515                 <LENGTH <MEMQ <TYPE .ARG> .ARGTYPES>>>
3516            .ARG>
3517
3518 calls a function to analyze `.ARG`. Which function is called depends
3519 on the `TYPE` of the argument; this represents the idea of a dispatch
3520 table.
3521
3522 9.11. CLOSURE
3523 -------------
3524
3525     <CLOSURE function a1 ... aN>
3526
3527 where *function* is a `FUNCTION`, and *a1* through *aN* are any number
3528 of `ATOM`s, returns an object of `TYPE` `CLOSURE`. This can be applied
3529 like any other function, but, whenever it is applied, the `ATOM`s
3530 given in the call to `CLOSURE` are **first** bound to the `VALUE`s
3531 they had when the `CLOSURE` was generated, then the *function* is
3532 applied as normal. This is a "poor man's `funarg`".
3533
3534 A `CLOSURE` is useful when a `FUNCTION` must have state information
3535 remembered between calls to it, especially in these two cases: when
3536 the `LVAL`s of external state `ATOM`s might be compromised by other
3537 programs, or when more than one distinct sequence of calls are active
3538 concurrently. Example of the latter: each object of a structured
3539 `NEWTYPE` might have an associated `CLOSURE` that coughs up one
3540 element at a time, with a value in the `CLOSURE` that is a structure
3541 containing all the relevant information.
3542
3543 Chapter 10. Looping
3544 ===================
3545
3546 10.1. PROG and REPEAT \[1\]
3547 ---------------------------
3548
3549 `PROG` and `REPEAT` are almost identical `FSUBR`s which make it
3550 possible to vary the order of `EVAL`uation arbitrarily -- that is, to
3551 have "jumps". The syntax of `PROG` ("program") is
3552
3553     <PROG act:atom aux:list body>
3554
3555 where
3556
3557 -   *act* is an optional `ATOM`, which is bound to the `ACTIVATION` of
3558     the `PROG`.
3559 -   *aux* is a `LIST` which looks exactly like that part of a
3560     `FUNCTION`'s argument `LIST` which follows an `"AUX"`, and serves
3561     exactly the same purpose. It is not optional. If you need no
3562     temporary variables of `"ACT"`, make it `()`.
3563 -   *body* is a non-zero number of arbitrary Muddle expressions.
3564
3565 The syntax of `REPEAT` is identical, except that, of course, `REPEAT`
3566 is the first element of the `FORM`, not `PROG`.
3567
3568 ### 10.1.1. Basic EVALuation \[1\]
3569
3570 Upon entering a `PROG`, an `ACTIVATION` is **always** generated. If
3571 there is an `ATOM` in the right place, the `ACTIVATION` is also bound
3572 to that `ATOM`. The variables in the *aux* (if any) are then bound as
3573 indicated in the *aux*. All of the expressions in *body* are then
3574 `EVAL`uated in their order of occurrence. If nothing untoward happens,
3575 you leave the `PROG` upon evaluating the last expression in *body*,
3576 returning the value of that last expression.
3577
3578 `PROG` thus provides a way to package together a group of things you
3579 wish to do, in a somewhat more limited way than can be done with a
3580 `FUNCTION`. But `PROG`s are generally used for their other properties.
3581
3582 `REPEAT` acts in all ways **exactly** like a `PROG` whose last
3583 expression is `<AGAIN>`. The only way to leave a `REPEAT` is to
3584 explicitly use `RETURN` (or `GO` with a `TAG` -- section 10.4).
3585
3586 ### 10.1.2. AGAIN and RETURN in PROG and REPEAT \[1\]
3587
3588 Within a `PROG` or `REPEAT`, you always have a defined `ACTIVATION`,
3589 whether you bind it to an `ATOM` or not. \[In fact the interpreter
3590 binds it to the `ATOM` `LPROG\ !-INTERRUPTS` ("last PROG"). The
3591 `FSUBR` `BIND` is identical to `PROG` except that `BIND` does not bind
3592 that `ATOM`, so that `AGAIN` and `RETURN` with no `ACTIVATION`
3593 argument will not refer to it. This feature could be useful within
3594 `MACRO`s.\]
3595
3596 If `AGAIN` is used with no arguments, it uses the `ACTIVATION` of the
3597 closest surrounding `PROG` or `REPEAT` **within the current function**
3598 (an error occurs if there is none) and re-starts the `PROG` or
3599 `REPEAT` without rebinding the *aux* variables, just the way it works
3600 in a `FUNCTION`. With an argument, it can of course re-start any
3601 Function (`PROG` or `REPEAT` or `FUNCTION`) within which it is
3602 embedded at run time.
3603
3604 As with `AGAIN`, if `RETURN` is given no `ACTIVATION` argument, it
3605 uses the `ACTIVATION` of the closest surrounding `PROG` or `REPEAT`
3606 within the current function and causes that `PROG` or `REPEAT` to
3607 terminate and return `RETURN`'s first argument. If `RETURN` is given
3608 **no** arguments, it causes the closest surrounding `PROG` or `REPEAT`
3609 to return the `ATOM` `T`. Also like `AGAIN`, it can, with an
3610 `ACTIVATION` argument, terminate any Function within which it is
3611 embedded at run time.
3612
3613 ### 10.1.3. Examples \[1\]
3614
3615 Examples of the use of `PROG` are difficult to find, since it is
3616 almost never necessary, and it slows down the interpreter (chapter
3617 24). `PROG` can be useful as a point of return from the middle of a
3618 computation, or inside a `COND` (which see), but we won't exemplify
3619 those uses. Instead, what follows is an example of a typically poor
3620 use of `PROG` which has been observed among Lisp (Moon, 1974)
3621 programmers using Muddle. Then, the same thing is done using `REPEAT`.
3622 In both cases, the example `FUNCTION` just adds up all its arguments
3623 and returns the sum. (The `SUBR` `GO` is discussed in section 10.4.)
3624
3625     ;"Lisp style"
3626         <DEFINE MY+ ("TUPLE" TUP)
3627                 <PROG (SUM)
3628                         <SET SUM 0>
3629                   LP    <COND (<EMPTY? .TUP> <RETURN .SUM>)>
3630                         <SET SUM <+ .SUM <1 .TUP>>>
3631                         <SET TUP <REST .TUP>>
3632                         <GO LP>>>
3633
3634     ;"Muddle style"
3635         <DEFINE MY+ ("TUPLE" TUP)
3636                 <REPEAT ((SUM 0))
3637                         <COND (<EMPTY? .TUP> <RETURN .SUM>)>
3638                         <SET SUM <+ .SUM <1 .TUP>>
3639                         <SET TUP <REST .TUP>>>>
3640
3641 Of course, neither of the above is optimal Muddle code for this
3642 problem, since `MY+` can be written using `SEGMENT` evaluation as
3643
3644     <DEFINE MY+ ("TUPLE" TUP) <+ !.TUP>>
3645
3646 There are, of course, lots of problems which can't be handled so
3647 simply, and lots of uses for `REPEAT`.
3648
3649 10.2. MAPF and MAPR: Basics \[1\]
3650 ---------------------------------
3651
3652 `MAPF` ("map first") and `MAPR` ("map rest") are two `SUBR`s which
3653 take care of a majority of cases which require loops over data. The
3654 basic idea is the following:
3655
3656 Suppose you have a `LIST` (or other structure) of data, and you want
3657 to apply a particular function to each element. That is exactly what
3658 `MAPF` does: you give it the function and the structure, and it
3659 applies the function to each element of the structure, starting with
3660 the first.
3661
3662 On the other hand, suppose you want to **change** each element of a
3663 structure according to a particular algorithm. This can be done only
3664 with great pain using `MAPF`, since you don't have easy access to the
3665 **structure** inside the function: you have only the structure's
3666 elements. `MAPR` solves the problem by applying a function to `REST`s
3667 of a structure: first to `<REST structure 0>`, then to
3668 `<REST structure 1>`, etc. Thus, the function can change the structure
3669 by changing its argument, for example, by a
3670 `<PUT argument 1 something>`. It can even `PUT` a new element farther
3671 down the structure, which will be seen by the function on subsequent
3672 applications.
3673
3674 Now suppose, in addition to applying a function to a structure, you
3675 want to record the results -- the values returned by the function --
3676 in another structure. Both `MAPF` and `MAPR` can do this: they both
3677 take an additional function as an argument, and, when the looping is
3678 over, apply the additional function to **all** the results, and then
3679 return the results of that application. Thus, if the additional
3680 function is `,LIST`, you get a `LIST` of the previous results; if it
3681 is `.VECTOR`, you get a `VECTOR` of results; etc.
3682
3683 Finally, it might be the case that you really want to loop a function
3684 over more than one structure simultaneously. For instance, consider
3685 creating a `LIST` whose elements are the element-by-element sum of the
3686 contents of two other `LIST`s. Both `MAPF` and `MAPR` allow this; you
3687 can, in fact, give each of them any number of structures full of
3688 arguments for your looping function.
3689
3690 This was all mentioned because `MAPF` and `MAPR` appear to be complex
3691 when seen baldly, due to the fact that the argument descriptions must
3692 take into account the general case. Simpler, degenerate cases are
3693 usually the ones used.
3694
3695 ### 10.2.1. MAPF \[1\]
3696
3697     <MAPF finalf loopf s1 s2 ... sN>
3698
3699 where (after argument evaluation)
3700
3701 -   *finalf* is something applicable that evaluates all its arguments,
3702     or a `FALSE`;
3703 -   *loopf* is something applicable to *N* arguments that evaluates
3704     all its arguments; and
3705 -   *s1* through *sN* are structured objects (any `TYPE`)
3706
3707 does the following:
3708
3709 1.  First, it applies *loopf* to *N* arguments: the first element of
3710     each of the structures. Then it `REST`s each of the structures,
3711     and does the application again, looping until **any** of the
3712     structures runs out of elements. Each of the values returned by
3713     *loopf* is recorded in a `TUPLE`.
3714 2.  Then, it applies *finalf* to all the recorded values
3715     simultaneously, and returns the result of that application. If
3716     *finalf* is a `FALSE`, the recorded values are "thrown away"
3717     (actually never recorded in the first place) and the `MAPF`
3718     returns only the last value returned by *loopf*. If any of the
3719     *si* structures is empty, to that *loopf* is never invoked,
3720     *finalf* is applied to **no** arguments; if *finalf* is a `FALSE`,
3721     `MAPF` returns `#FALSE ()`.
3722
3723 ### 10.2.2 MAPR \[1\]
3724
3725     <MAPR finalf loopf s1 s2 ... sN>
3726
3727 acts just like `MAPF`, but, instead of applying *loopf* to `NTH`s of
3728 the structures -- that is, `<NTH si 1>`, `<NTH si 2>`, etc. -- it
3729 applies it to `REST`s of the structures -- that is, `<REST si 0>`,
3730 `<REST si 1>`, etc.
3731
3732 ### 10.2.3. Examples \[1\]
3733
3734 Make the element-wise sum of two `LIST`s:
3735
3736     <MAPF .LIST .+ '(1 2 3 4) '(10 11 12 13)>$
3737     (11 13 15 17)
3738
3739 Change a `UVECTOR` to contain double its values:
3740
3741     <SET UV '![5 6 7 8 9]>$
3742     ![5 6 7 8 9!]
3743     <MAPR <>
3744            #FUNCTION ((L) <PUT .L 1 <* <1 .L> 2>>)
3745            .UV>$
3746     ![18!]
3747     .UV$
3748     ![10 12 14 16 18!]
3749
3750 Create a `STRING` from `CHARACTER`s:
3751
3752     <MAPF ,STRING 1 '["MODELING" "DEVELOPMENT" "LIBRARY"]>$
3753     "Muddle"
3754
3755 Sum the squares of the elements of a `UVECTOR`:
3756
3757     <MAPF ,+ #FUNCTION ((N) <* .N .N>) '![3 4]>$
3758     25
3759
3760 A parallel assignment `FUNCTION` (Note that the arguments to `MAPF`
3761 are of different lengths.):
3762
3763     <DEFINE PSET ("TUPLE" TUP)
3764             <MAPF <>
3765                   ,SET
3766                   .TUP
3767                   <REST .TUP </ <LENGTH .TUP> 2>>>>$
3768     PSET
3769     <PSET A B C 1 2 3>$
3770     3
3771     .A$
3772     1
3773     .B$
3774     2
3775     .C$
3776     3
3777
3778 Note: it is easy to forget that *finalf* **must** evaluate its
3779 arguments, which precludes the use of an `FSUBR`. It is primarily for
3780 this reason that the `SUBR`s `AND?` and `OR?` were invented. As an
3781 example, the predicate `=?` could have been defined this way:
3782
3783     <DEFINE =? (A B)
3784             <COND (<MONAD? .A> <==? .A .B>)
3785                   (<AND <NOT <MONAD? .B>>
3786                         <==? <TYPE .A> <TYPE .B>>
3787                         <==? <LENGTH .A> <LENGTH .B>>>
3788                    <MAPF ,AND? ,=? .A .B>)>>
3789
3790 \[By the way, the following shows how to construct a value that has
3791 the same `TYPE` as an argument.
3792
3793     <DEFINE MAP-NOT (S)
3794      <COND (<MEMQ <PRIMTYPE .S> '![LIST VECTOR UVECTOR STRING]>
3795             <CHTYPE <MAPF ,<PRIMTYPE .S> ,NOT .S>
3796                     <TYPE .S>>)>>
3797
3798 It works because the `ATOM`s that name the common `STRUCTURED`
3799 `PRIMTYPS`s (`LIST`, `VECTOR`, `UVECTOR` and `STRING`) have as `GVAL`s
3800 the corresponding `SUBR`s to build objects of those `TYPE`s.\]
3801
3802 10.3. More on MAPF and MAPR
3803 ---------------------------
3804
3805 ### 10.3.1. MAPRET
3806
3807 `MAPRET` is a `SUBR` that enables the *loopf* being used in a `MAPR`
3808 or `MAPF` (and lexically within it, that is, not separated from it by
3809 a function call) to return from zero to any number of values as
3810 opposed to just one. For example, suppose a `MAPF` of the following
3811 form is used:
3812
3813     <MAPF ,LIST <FUNCTION (E) ...> ...>
3814
3815 Now suppose that the programmer wants to add no elements to the final
3816 `LIST` on some calls to the `FUNCTION` and add many on other calls to
3817 the `FUNCTION`. To accomplish this, the `FUNCTION` simply calls
3818 `MAPRET` with the elements it wants added to the `LIST`. More
3819 generally, `MAPRET` causes its arguments to be added to the final
3820 `TUPLE` of arguments to which the *finalf* will be applied.
3821
3822 Warning: `MAPRET` is guaranteed to work only if it is called from an
3823 explicit `FUNCTION` which is the second argument to a `MAPF` or
3824 `MAPR`. In other words, the second argument to `MAPF` or `MAPR` must
3825 be `#FUNCTION (...)` or `<FUNCTION ...>` if `MAPRET` is to be used.
3826
3827 Example: the following returns a `LIST` of all the `ATOM`s in an
3828 `OBLIST` (chapter 15):
3829
3830     <DEFINE ATOMS (OB)
3831             <MAPF .LIST
3832                   <FUNCTION (BKT) <MAPRET !.BKT>>
3833                   .OB>>
3834
3835 ### 10.3.2. MAPSTOP
3836
3837 `MAPSTOP` is the same as `MAPRET`, except that, after adding its
3838 arguments, if any, to the final `TUPLE`, it forces the application of
3839 *finalf* to occur, whether or not the structured objects have run out
3840 of objects. Example: the following copies the first ten (or all)
3841 elements of its argument into a `LIST`:
3842
3843     <DEFINE FIRST-TEN (STRUC "AUX" (I 10))
3844      <MAPF ,LIST
3845           <FUNCTION (E)
3846               <COND (<0? <SET I <- .I 1>>> <MAPSTOP .E>)>
3847               .E>
3848           .STRUC>>
3849
3850 ### 10.3.3. MAPLEAVE
3851
3852 `MAPLEAVE` is analogous to `RETURN`, except that it works in
3853 (lexically within) `MAPF` or `MAPR` instead of `PROG` or `REPEAT`. It
3854 flushes the accumulated `TUPLE` of results and returns its argument
3855 (optional, `T` by default) as the value of the `MAPF` or `MAPR`. (It
3856 finds the MAPF/R that should returns in the current binding of the
3857 `ATOM` `LMAP\ !-INTERRUPTS` ("last map").) Example: the following
3858 finds and returns the first non-zero element of its argument, or
3859 `#FALSE ()` if there is none:
3860
3861     <DEFINE FIRST-N0 (STRUC)
3862             <MAPF <>
3863                   <FUNCTION (X)
3864                     <COND (<N==? .X 0> <MAPLEAVE .X>)>>
3865                   .STRUC>>
3866
3867 ### 10.3.4. Only two arguments
3868
3869 If `MAPF` or `MAPR` is given only two arguments, the iteration
3870 function *loopf* is applied to no arguments each time, and the looping
3871 continues indefinitely until a `MAPLEAVE` or `MAPSTOP` is invoked.
3872 Example: the following returns a `LIST` of the integers from one less
3873 than its argument to zero.
3874
3875     <DEFINE LNUM (N)
3876             <MAPF ,LIST
3877                   <FUNCTION ()
3878                     <COND (<=? <SET N <- .N 1>>> <MAPSTOP 0>)
3879                           (ELSE .N)>>>>
3880
3881 One principle use of this form of MAPF/R involves processing input
3882 characters, in cases where you don't know how many characters are
3883 going to arrive. The example below demonstrates this, using `SUBR`s
3884 which are more fully explained in chapter 11. Another example can be
3885 found in chapter 13.
3886
3887 Example: the following `FUNCTION` reads characters from the current
3888 input channel until an `$` (`ESC`) is read, and then returns what was
3889 read as one `STRING`. (The `SUBR` `READCHR` reads one character from
3890 the input channel and returns it. `NEXTCHR` returns the next
3891 `CHARACTER` which `READCHR` will return -- chapter 11.)
3892
3893     <DEFINE RDSTR ()
3894       <MAPF .STRING
3895             <FUNCTION () <COND (<NOT <==? <NEXTCHR> <ASCII 27>>>
3896                                 <READCHR>)
3897                                (T
3898                                 <MAPSTOP>)>>>>$
3899     RDSTR
3900
3901     <PROG () <READCHR> ;"Flush the ESC ending this input."
3902                  <RDSTR>>$
3903     ABC123<+ 3 4>$"ABC123<+ 3 4>"
3904
3905 ### 10.3.5. STACKFORM
3906
3907 The `FSUBR` `STACKFORM` is archaic, due to improvements in the
3908 implementation of MAPF/R, and it should not be used in new programs.
3909
3910     <STACKFORM function arg pred>
3911
3912 is exactly equivalent to
3913
3914     <MAPF function
3915           <FUNCTION () <COND (pred arg) (T <MAPSTOP>)>>>
3916
3917 In fact MAPF/R is more powerful, because `MAPRET`, `MAPSTOP`, and
3918 `MAPLEAVE` provide flexibility not available with `STACKFORM`.
3919
3920 10.4. GO and TAG
3921 ----------------
3922
3923 `GO` is provided in Muddle for people who can't recover from a
3924 youthful experience with Basic, Fortran, PL/I, etc. The `SUBR`s
3925 previously described in this chapter are much more tasteful for making
3926 good, clean, "structured" programs. `GO` just bollixes things.
3927
3928 `GO` is a `SUBR` which allows you to break the normal order of
3929 evaluation and re-start just before any top-level expression in a
3930 `PROG` or `REPEAT`. It can take two `TYPE`s of arguments: `ATOM` or
3931 `TAG`.
3932
3933 Given an `ATOM`, `GO` searches the *body* of the immediately
3934 surrounding `PROG` or `REPEAT` within the current Function, starting
3935 after *aux*, for an occurrence of that `ATOM` at the top level of
3936 *body*. (This search is effectively a `MEMQ`.) If it doesn't find the
3937 `ATOM`, an error occurs. If it does, evaluation is resumed at the
3938 expression following the `ATOM`.
3939
3940 The `SUBR` `TAG` generates and returns objects of `TYPE` `TAG`. This
3941 `SUBR` takes one argument: an `ATOM` which would be a legal argument
3942 for a `GO`. An object of `TYPE` `TAG` contains sufficient information
3943 to allow you to `GO` to any top-level position in a `PROG` or `REPEAT`
3944 from within any function called inside the `PROG` or `REPEAT`. `GO`
3945 with a `TAG` is vaguely like `AGAIN` with an `ACTIVATION`; it allows
3946 you to "go back" to the middle of any `PROG` or `REPEAT` which called
3947 you. Also like `ACTIVATION`s, `TAG`s into a `PROG` or `REPEAT` can no
3948 longer be used after the `PROG` or `REPEAT` has returned. `LEGAL?` can
3949 be used to see if a `TAG` is still valid.
3950
3951 10.5. Looping versus Recursion
3952 ------------------------------
3953
3954 Since any program in Muddle can be called recursively, champions of
3955 "pure Lisp" (Moon, 1974) or somesuch may be tempted to implement any
3956 repetitive algorithm using recursion. The advantage of the looping
3957 techniques described in this chapter over recursion is that the
3958 overhead of calls is eliminated. However, a long program (say, bigger
3959 than half a printed page) may be more difficult to write iteratively
3960 than recursively and hence more difficult to maintain. A program whose
3961 repetition is controlled by a structured object (for example, "walking
3962 a tree" to visit each monad in the object) often should use looping
3963 for covering one "level" of the structure and recursion to change
3964 "levels".
3965
3966 Chapter 11. Input/Output
3967 ========================
3968
3969 The Muddle interpreter can transmit information between an object in
3970 Muddle and an external device in three ways. Historically, the first
3971 way was to **convert** an object into a string of characters, or vice
3972 versa. The transformation is nearly one-to-one (although some Muddle
3973 objects, for example `TUPLE`s, cannot be input in this way) and is
3974 similar in style to Fortran's formatted I/O. It is what `READ` and
3975 `PRINT` do, and it is the normal method for terminal I/O.
3976
3977 The second way is used for the contents of Muddle objects rather than
3978 the objects themselves. Here an **image** of numbers or characters
3979 within an object is transmitted, similar in style to Fortran's
3980 unformatted I/O.
3981
3982 The third way is to **dump** an object in a clever format so that it
3983 can be reproduced exactly when input the next time. Exact reproduction
3984 means that any sharing between structures or self-reference is
3985 preserved: only the garbage collector itself can do I/O in this way.
3986
3987 11.1. Conversion I/O
3988 --------------------
3989
3990 All conversion-I/O `SUBR`s in Muddle take an optional argument which
3991 directs their attention to a specific I/O channel. This section will
3992 describe `SUBR`s without their optional arguments. In this situation,
3993 they all refer to a particular channel by default, initially the
3994 terminal running the Muddle. When given an optional argument, that
3995 argument follows any arguments indicated here. Some of these `SUBR`s
3996 also have additional optional arguments, relevant to conversion,
3997 discussion of which will be deferred until later.
3998
3999 ### 11.1.1. Input
4000
4001 All of the following input Subroutines, when directed at a terminal,
4002 hang until `$` (`ESC`) is typed and allow normal use of `rubout`,
4003 `^D`, `^L` and `^@`.
4004
4005 #### 11.1.1.1. READ
4006
4007     <READ>
4008
4009 This returns the entire Muddle object whose character representation
4010 is next in the input stream. Successive `<READ>`s return successive
4011 objects. This is precisely the `SUBR` `READ` mentioned in chapter 2.
4012 See also sections 11.3, 15.7.1, and 17.1.3 for optional arguments.
4013
4014 #### 11.1.1.2. READCHR
4015
4016     <READCHR>
4017
4018 ("read character") returns the next `CHARACTER` in the input stream.
4019 Successive `<READCHR>`s return successive `CHARACTER`s.
4020
4021 #### 11.1.1.3. NEXTCHR
4022
4023     <NEXTCHR>
4024
4025 ("next character") returns the `CHARACTER` which `READCHR` will return
4026 the next time `READCHR` is called. Multiple `<NEXTCHR>`s, with no
4027 input operations between them, all return the same thing.
4028
4029 ### 11.1.2. Output
4030
4031 If an object to be output requires (or can tolerate) separators within
4032 it (for example, between the elements in a structured object or after
4033 the `TYPE` name in "\# notation"), these conversion-output `SUBR`s
4034 will use a carriage-return/line-feed separator to prevent overflowing
4035 a line. Overflow is detected in advance from elements of the `CHANNEL`
4036 in use (section 11.2.8).
4037
4038 #### 11.1.2.1. PRINT
4039
4040     <PRINT any>
4041
4042 This outputs, in order,
4043
4044 1.  a carriage-return line-feed,
4045 2.  the character representation of `EVAL` of its argument (`PRINT` is
4046     a `SUBR`), and
4047 3.  a space
4048
4049 and then returns `EVAL` of its argument. This is precisely the `SUBR`
4050 `PRINT` mentioned in chapter 2.
4051
4052 #### 11.1.2.2. PRIN1
4053
4054     <PRIN1 any>
4055
4056 outputs just the representation of, and returns, `EVAL` of *any*.
4057
4058 #### 11.1.2.3. PRINC
4059
4060     <PRINC any>
4061
4062 ("print characters") acts exactly like `PRIN1`, except that
4063
4064 1.  if its argument is a `STRING` or a `CHARACTER`, it suppresses the
4065     surrounding `"`s or initial `!\` respectively; or
4066 2.  if its argument is an `ATOM`, it suppresses any `\`s or `OBLIST`
4067     trailers (chapter 15) which would otherwise be necessary.
4068
4069 If `PRINC`'s argument is a structure containing `STRING`s,
4070 `CHARACTER`s, or `ATOM`s, the service mentioned will be done for all
4071 of them. Ditto for the `ATOM` used to name the `TYPE` in "\#
4072 notation".
4073
4074 #### 11.1.2.4. TERPRI
4075
4076     <TERPRI>
4077
4078 ("terminate printing") outputs a carriage-return line-feed and then
4079 returns `# FALSE ()`!
4080
4081 #### 11.1.2.5. CRLF
4082
4083 ("carriage-return line-feed") outputs a carriage-return line-feed and
4084 then returns `T`.
4085
4086 #### 11.1.2.6. FLATSIZE
4087
4088     <FLATSIZE any max:fix radix:fix>
4089
4090 does not actually cause any output to occur and does not take a
4091 `CHANNEL` argument. Instead, or compares *max* with the number of
4092 characters `PRIN1` would take to print *any*. If *max* is less than
4093 the number of characters needed (including the case where *any* is
4094 self-referencing, `FLATSIZE` returns `#FALSE ()`; otherwise, it
4095 returns the number of characters needed by `PRIN1` *any*. *radix*
4096 (optional, ten by default) is used for converting any `FIX`es that
4097 occur.
4098
4099 This `SUBR` is especially useful in conjunction with (section 11.2.8)
4100 those elements of a `CHANNEL` which specify the number of characters
4101 per output line and the current position on an input line.
4102
4103 CHANNEL (the TYPE)
4104 ------------------
4105
4106 I/O channels are dynamically assigned in Muddle, and are represented
4107 by an object of `TYPE` `CHANNEL`, which is of `PRIMTYPE` `VECTOR`. The
4108 format of a `CHANNEL` will be explained later, in section 11.2.8.
4109 First, how to generate and use them.
4110
4111 ### 11.2.1. OPEN
4112
4113     <OPEN mode file-spec>
4114
4115 or
4116
4117     <OPEN mode name1 name2 device dir>
4118
4119 `OPEN` is a `SUBR` which creates and returns a `CHANNEL`. All its
4120 arguments must be of `TYPE` `STRING`, and **all** are optional. The
4121 preceding statement is false when the *device* is `"INT"` or `"NET"`;
4122 see sections 11.9 and 11.10. If the attempted opening of an
4123 operating-system I/O channel fails, `OPEN` returns
4124 `#FALSE (reason:string file-spec:string status:fix)`, where the
4125 *reason* and the *status* are supplied by the operating system, and
4126 the `file-spec` is the standard name of the file (after any name
4127 transformations by the operating system) that Muddle was trying to
4128 open.
4129
4130 The choice of *mode* is usually determined by which `SUBR`s will be
4131 used on the `CHANNEL`, and whether or not the *device* is a terminal.
4132 The following table tells which `SUBR`s can be used with which modes,
4133 where `OK` indicates an allowed use:
4134
4135   -------------------------------------------------------------------------------------------------------------------------------------------------
4136   "READ"               "PRINT"               "READB"               "PRINTB", "PRINTO"                           mode / SUBRs
4137   -------------------- --------------------- --------------------- -------------------------------------------- -----------------------------------
4138   OK                                         OK                                                                 `READ` `READCHR` `NEXTCHR`
4139                                                                                                                 `READSTRING` `FILECOPY`
4140                                                                                                                 `FILE-LENGTH LOAD`
4141
4142                        OK                                          OK\*                                         `PRINT` `PRIN1` `PRINC` `IMAGE`
4143                                                                                                                 `CRLF` `TERPRI` `FILECOPY`
4144                                                                                                                 `PRINTSTRING` `BUFOUT` `NETS`
4145                                                                                                                 `RENAME`
4146
4147                                              OK                                                                 `READB` `GC-READ`
4148
4149                                                                    OK                                           `PRINTB` `GC-DUMP`
4150
4151   OK                                         OK                    OK                                           `ACCESS`
4152
4153   OK                   OK                    OK                    OK                                           `RESET`
4154
4155   OK                   OK                                                                                       `ECHOPAIR`
4156
4157   OK                                                                                                            `TTYECHO` `TYI`
4158   -------------------------------------------------------------------------------------------------------------------------------------------------
4159
4160 `*` PRINTing (or `PRIN1`ing) an `RSUBR` (chapter 19) on a `"PRINTB"`
4161 or `"PRINTO"` `CHANNEL` has special effects.
4162
4163 `"PRINTB"` differs from `"PRINTO"` in that the latter mode is used to
4164 update a `"DSK"` file without copying it. `"READB"` and `"PRINTB"` are
4165 not used with terminals. `"READ"` is the mode used by default.
4166
4167 The next one to four arguments to `OPEN` specify the file involved. If
4168 only one `STRING` is used, it can contain the entire specification,
4169 according to standard operating-system syntax. Otherwise, the
4170 string(s) are interpreted as follows:
4171
4172 *name1* is the first file name, that part to the left of the space (in
4173 the ITS version) or period (in the Tenex and Tops-20 versions). The
4174 name used by default is `<VALUE NM1>`, if any, otherwise `"INPUT"`.
4175
4176 *name2* is the second fail name, that part to the right of the space
4177 (ITS) or period (Tenex and Tops-20). The name used by default is
4178 `<VALUE NM2>`, if any, otherwise `">"` or `"MUD"` and highest version
4179 number (Tenex) or generation number (Tops-20).
4180
4181 *device* is the device name. The name used by default is
4182 `<VALUE DEV>`, if any, otherwise `"DSK"`. (Devices about which Muddle
4183 has no special knowledge are assumed to behave like `"DSK"`.)
4184
4185 *dir* is the disk-directory name. The name used by default is
4186 `<VALUE SNM>`, if any, otherwise the "working-directory" name as
4187 defined by her operating system.
4188
4189 Examples:
4190
4191 `<OPEN "PRINT" "TPL:">` opens a conversion-output channel to the TPL
4192 device.
4193
4194 `<OPEN "PRINT" "DUMMY" "NAMES" "IPL">` does the same.
4195
4196 `<OPEN "PRINT" "TPL">` opens a `CHANNEL` to the file `DSK:TPL >` (ITS
4197 version) or `DSK:TPL.MUD` (Tenex and Tops-20 versions).
4198
4199 `<OPEN "READ" "FOO" ">" "DSK" "GUEST">` opens up a conversion-input
4200 `CHANNEL` to the given file.
4201
4202 `<OPEN "READ" "GUEST;FOO">` does the same in the ITS version.
4203
4204 ### 11.2.2. OPEN-NR
4205
4206 `OPEN-NR` is the same as `OPEN`, except that the date and time of last
4207 reference of the opened file are not changes.
4208
4209 ### 11.2.3. CHANNEL (the SUBR)
4210
4211 `CHANNEL` is called exactly like `OPEN`, but it **always** return an
4212 unopened `CHANNEL`, which can later be opened by `RESET` (below) just
4213 as if it had once been open.
4214
4215 ### 11.2.4. FILE-EXISTS?
4216
4217 `FILE-EXISTS?` tests for the existence of a file without creating a
4218 `CHANNEL`, which occupies about a hundred machine words of storage. It
4219 takes file-name arguments just like `OPEN` (but no *mode* argument)
4220 and returns either T, \`\#FALSE (reason:string status:fix),
4221
4222 ### 11.2.5. CLOSE
4223
4224     <CLOSE channel>
4225
4226 closes *channel* and returns its argument, with its "state" changed to
4227 "closed". If *channel* is for output, all buffered output is written
4228 out first. No harm is done if *channel* is already `CLOSE`d.
4229
4230 ### 11.2.6. CHANLIST
4231
4232     <CHANLIST>
4233
4234 returns a `LIST` whose elements are all the currently open `CHANNEL`s.
4235 The first two elements are usually `.INCHAN` and `.OUTCHAN` (see
4236 below). A `CHANNEL` not referenced by anything except `<CHANLIST>`
4237 will be `CLOSEd` during garbage collection.
4238
4239 ### 11.2.7. INCHAN and OUTCHAN
4240
4241 The channel used by default for input `SUBR`s is the local value of
4242 the `ATOM` `INCHAN`. The channel used by default for output SUBRs is
4243 the local value of the `ATOM` `OUTCHAN`.
4244
4245 You can direct I/O to a `CHANNEL` by `SET`ting `INCHAN` or `OUTCHAN`
4246 (remembering their old values somewhere), or by giving the `SUBR` you
4247 with to use an argument of `TYPE` `CHANNEL`. (These actually have the
4248 same effect, because `READ` binds `INCHAN` to an explicit argument,
4249 and `PRINT` binds `OUTCHAN` similarly. Thus the `CHANNEL` being used
4250 is available for `READ` macros (section 17.1), or by giving the `SUBR`
4251 you wish to use an argument of `TYPE` `CHANNEL`. Thus the `CHANNEL`
4252 being used is available for `READ` macros (section 17.1) and
4253 `PRINTTYPE`s (section 6.4.4).)
4254
4255 By the way, a good trick for playing with `INCHAN` and `OUTCHAN`
4256 values within a function is to use the `ATOM`s `INCHAN` and `OUTCHAN`
4257 as `"AUX"` variables, re-binding their local values to the `CHANNEL`
4258 you want. When you leave , of course, the old `LVAL`s are expanded
4259 (which is the whole point). The `ATOM`s must be declared `SPECIAL`
4260 (chapter 14) for this trick to compile correctly.
4261
4262 `INCHAN` and `OUTCHAN` also have global values, initially the
4263 `CHANNEL`s directed at the terminal running `Muddle`. Initially,
4264 `INCHAN`'s and `OUTCHAN`s local and global values are the same.
4265
4266 ### 11.2.8. Contents of CHANNELs
4267
4268 The contents of an object of `TYPE` `CHANNEL` are referred to by the
4269 I/O `SUBR`s each time such a `SUBR` is used. If you change the
4270 contents of a `CHANNEL` (for example, with `PUT`), the next use of
4271 that `CHANNEL` will be changed accordingly. Some elements of
4272 `CHANNEL`s, however, should be played with seldom, if ever, and only
4273 at your own peril. These are marked below with an `*` (asterisk).
4274 Caveat user.
4275
4276 There follows a table of the contents of a `CHANNEL`, the `TYPE` of
4277 each element, and an interpretation. The format used is the following:
4278
4279 *element-number: type interpretation*
4280
4281   ----------------------------------------------------------------------------------------------------
4282   element-number             type               interpretation
4283   -------------------------- ------------------ ------------------------------------------------------
4284   -1                         `LIST`             transcript channel(s) (see below)
4285
4286   \* 0                       varies             device-dependent information
4287
4288   \* 1                       `FIX`              channel number (ITS) or JFN (Tenex and Tops-20), `0`
4289                                                 for internal or closed
4290
4291   \* 2                       `STRING`           mode
4292
4293   \* 3                       `STRING`           first file name argument
4294
4295   \* 4                       `STRING`           second file name argument
4296
4297   \* 5                       `STRING`           device name argument
4298
4299   \* 6                       `STRING`           directory name argument
4300
4301   \* 7                       `STRING`           real first file name
4302
4303   \* 8                       `STRING`           real second file name
4304
4305   \* 9                       `STRING`           real device name
4306
4307   \* 10                      `STRING`           real directory name
4308
4309   \* 11                      `FIX`              various status bits
4310
4311   \* 12                      `FIX`              PDP-10 instruction used to do one I/O operation
4312
4313   13                         `FIX`              number of characters per line of output
4314
4315   14                         `FIX`              current character position on a line
4316
4317   15                         `FIX`              number of lines per page
4318
4319   16                         `FIX`              current line number on a page
4320
4321   17                         `FIX`              access pointer for file-oriented devices
4322
4323   18                         `FIX`              radix for `FIX` conversion
4324
4325   19                         `FIX`              sink for an internal `CHANNEL`
4326   ----------------------------------------------------------------------------------------------------
4327
4328 N.B.: The elements of a `CHANNEL` below number 1 are usually invisible
4329 but are obtainable via `<NTH <TOP channel> fix>`, for some appropriate
4330 *fix*.
4331
4332 The transcript-channels slot has this meaning: if this slot contains a
4333 `LIST` of `CHANNEL`s, then anything input or output on the original
4334 `CHANNEL` is output on these `CHANNEL`s. Caution: do not use a
4335 `CHANNEL` as its own transcript channel; you probably won't live to
4336 tell about it.
4337
4338 #### 11.2.8.2. Input CHANNELs
4339
4340 The contents of the elements up to number 12 of a `CHANNEL` used for
4341 input are the same as that for output. The remaining elements are as
4342 follows ((same) indicates that the use is the same as that for
4343 output):
4344
4345   element-number   type       interpretation
4346   ---------------- ---------- ---------------------------------------------------
4347   13               varies     object evaluated when end of file is reached
4348   \* 14            `FIX`      one "look-ahead" character, used by `READ`
4349   \* 15            `FIX`      PDP-10 instruction executed waiting for input
4350   16               `LIST`     queue of buffers for input from a terminal
4351   17               `FIX`      access pointer for file-oriented devices (same)
4352   18               `FIX`      radix for `FIX` conversion (same)
4353   19               `STRING`   buffer for input or source for internal `CHANNEL`
4354
4355 11.3. End-of-File "Routine"
4356 ---------------------------
4357
4358 As mentioned above, an explicit `CHANNEL` is the first optional
4359 argument of all `SUBR`s used for conversion I/O. The second optional
4360 argument for conversion-**input** `SUBR`s is an "end-of-file routine"
4361 -- that is, something for the input `SUBR` to `EVAL` and return, if it
4362 reaches the end of the file it is reading. A typical end-of-file
4363 argument is a `QUOTE`d `FORM` which applies a function of yours. The
4364 value of this argument used by default is a call to `ERROR`. Note: the
4365 `CHANNEL` has been `CLOSE`d by the time this argument is evaluated.
4366
4367 Example: the following `FUNCTION` counts the occurrences of a
4368 character in a file, according to its arguments. The file names,
4369 device, and directory are optional, with the usual names used by
4370 default.
4371
4372     <DEFINE COUNT-CHAR
4373             (CHAR "TUPLE" FILE "AUX" (CNT 0) (CHN <OPEN "READ" !.FILE>))
4374         <COND (.CHN                 ;"If CHN is FALSE, bad OPEN: return the FALSE
4375                                     so result can be tested by another FUNCTION."
4376                <REPEAT ()
4377                     <AND <==? .CHAR <READCHR .CHN '<RETURN>>>
4378                          <SET CNT <+ 1 .CNT>>>>
4379                     ;"Until EOF, keep reading and testing a character at a time."
4380                 .CNT                ;"Then return the count.")>>
4381
4382 11.4. Imaged I/O
4383 ----------------
4384
4385 ### 11.4.1. Input
4386
4387 #### 11.4.1.1. READB
4388
4389     <READB buffer:uvector-or-storage channel eof:any>
4390
4391 The *channel* must be open in `"READB"` mode. `READB` will read as
4392 many 36-bit binary words as necessary to fill the *buffer* (whose
4393 `UTYPE` must be of `PRIMTYPE` `WORD`), unless it hits the end of the
4394 file. `READB` returns the number of words actually read, as a
4395 `FIX`ed-point number. This will normally be the length of the
4396 *buffer*, unless the end of file was read, in which case it will be
4397 less, and only the beginning of *buffer* will have been filled
4398 (`SUBSTRUC` may help). An attempt to `READB` again, after *buffer* is
4399 not filled, will evaluate the end-of-file routine *eof*, which is
4400 optional, a call to `ERROR` by default.
4401
4402 #### 11.4.1.2. READSTRING
4403
4404     <READSTRING buffer:string channel stop:fix-or-string eof>
4405
4406 is the `STRING` analog to `READB`, where *buffer* and *eof* are as in
4407 `READB`, and *channel* is any input `CHANNEL` (`.INCHAN` by default).
4408 *stop* tells when to stop inputting: if a `FIX`, read this many
4409 `CHARACTER`s (fill up *buffer* by default); if a `STRING`, stop
4410 reading if any `CHARACTER` in this `STRING` is read (don't include
4411 this `CHARACTER` in final `STRING`).
4412
4413 ### 11.4.2. Output
4414
4415 #### 11.4.2.1. PRINTB
4416
4417     <PRINTB buffer:uvector-or-storage channel>
4418
4419 This call writes the entire contents of the *buffer* into the
4420 specified channel open in `"PRINTB"` or `"PRINTO"` mode. It returns
4421 *buffer*.
4422
4423 #### 11.4.2.2. PRINTSTRING
4424
4425     <PRINTSTRING buffer:string channel count:fix>
4426
4427 is analogous to `READSTRING`. It outputs *buffer* on *channel*, either
4428 the whole thing or the first *count* characters, and returns the
4429 number of characters output.
4430
4431 #### 11.4.2.3. IMAGE
4432
4433     <IMAGE fix channel>
4434
4435 is a rather special-purpose `SUBR`. When any conversion-output routine
4436 outputs an ASCII control character (with special exceptions like
4437 carriage-returns, line-feeds, etc.), it actually outputs two
4438 characters: `^` (circumflex), followed by the upper-case character
4439 which has been control-shifted. `IMAGE`, on the other hand, always
4440 outputs the real thing: that ASCII character whose ASCII 7-bit code is
4441 *fix*. It is guaranteed not to give any gratuitous linefeeds or such.
4442 *channel* is optional, `.OUTCHAN` by default, and its slots for
4443 current character position (number 14) and current line number (16)
4444 are not updated. `IMAGE` returns *fix*.
4445
4446 11.5 Dumped I/O
4447 ---------------
4448
4449 ### 11.5.1. Output: GC-DUMP
4450
4451     <GC-DUMP any printb:channel-or-false>
4452
4453 dumps *any* on *printb* in a clever format so that `GC-READ` (below)
4454 can reproduce *any* exactly, including sharing. *any* cannot live on
4455 the control stack, not can it be of `PRIMTYPE` `PROCESS` or `LOCD` or
4456 `ASOC` (which see). *any* is returned as a value.
4457
4458 If *printb* is a `CHANNEL`, it must be open in `"PRINTB"` or
4459 `"PRINTO"` mode. If *printb* is a `FALSE`, `GC-DUMP` instead returns a
4460 `UVECTOR` (of `UTYPE` `PRIMTYPE` `WORD`) that contains what it would
4461 have output on a `CHANNEL`. This `UVECTOR` can be `PRINTB`ed anywhere
4462 you desire, but, if it is changed **in any way**, `GC-READ` will not
4463 be able to input it. Probably the only reason to get it is to check
4464 its length before output.
4465
4466 Except for the miniature garbage collection required, `GC-DUMP` is
4467 about twice as fast as `PRINT`, but the amount of external storage
4468 used is two or three times as much.
4469
4470 ### 11.5.2. Input: GC-READ
4471
4472     <GC-READ readb:channel eof:any>
4473
4474 returns one object from the *channel*, which must be open in `"READB"`
4475 mode. The file must have been produced by `GC-DUMP`. *eof* is
4476 optional. `GC-READ` is about ten times faster than `READ`.
4477
4478 11.6. SAVE Files
4479 ----------------
4480
4481 The entire state of Muddle can be saved away in a file for later
4482 restoration: this is done with the `SUBR`s `SAVE` and `RESTORE`. This
4483 is a very different form of I/O from any mentioned up to now; the file
4484 used contains an actual image of your Muddle address space and is not,
4485 in general, "legible" to other Muddle routines. `RESTORE`ing a `SAVE`
4486 file is **much** faster than re-`READ`ing the objects it contains.
4487
4488 Since a `SAVE` file does not contain all extant Muddle objects, only
4489 the impure and `PURIFY`ed (section 22.9.2) ones, a change to the
4490 interpreter has the result of making all previous `SAVE` files
4491 unusable. To prevent errors from arising from this, the interpreter
4492 has a release number, which is incremented whenever changes are
4493 installed. The current release number is printed out on initially
4494 starting up the program and is available as the `GVAL` of the `ATOM`
4495 `MUDDLE`. This release number is written out as the very first part of
4496 each `SAVE` file. If `RESTORE` attempts to re-load a `SAVE` file whose
4497 release number is not the same as the interpreter being used, an error
4498 is produced. If desired, the release number of a `SAVE` file can be
4499 obtained by doing a `READ` of that file. Only that initial `READ` will
4500 work; the rest of the file is not ASCII.
4501
4502 ### 11.6.1. SAVE
4503
4504     <SAVE file-spec:string gc?:false-or-any>
4505
4506 or
4507
4508     <SAVE name1 name2 device dir gc?:false-or-any>
4509
4510 saves the entire state of your Muddle away in the file specified by
4511 its arguments, and then returns `"SAVED"`. All `STRING` arguments are
4512 optional, with `"MUDDLE"`, `"SAVE"`, `"DSK"`, and `<VALUE SNM>` used
4513 by default. *gc?* is optional and, if supplied and of `TYPE` `FALSE`,
4514 causes no garbage collection to occur before `SAVE`ing. (`FSAVE` is an
4515 alias for `SAVE` that may be seen in old programs.)
4516
4517 If, after restoring, `RESTORE` finds that `<VALUE SNM>` is the null
4518 `STRING` (`""`), it will ask the operating system for the name of the
4519 "working directory" and call `SNAME` with the result. This mechanism
4520 is handy for "public" `SAVE` files, which should not point the user at
4521 a particular disk directory.
4522
4523 In the ITS version, the file is actually written with the name
4524 `_MUDS_ >` and renamed to the argument(s) only when complete, to
4525 prevent losing a previous `SAVE` file if a crash occurs. In the Tenex
4526 and Tops-20 versions, version/generation numbers provide the same
4527 safety.
4528
4529 Example:
4530
4531     <DEFINE SAVE-IT ("OPTIONAL"
4532                      (FILE '("PUBLIC" "SAVE" "DSK" "GUEST"))
4533                      "AUX" (SNM ""))
4534             <SETUP>
4535             <COND (<=? "SAVED" <SAVE !.FILE>>   ;"See below."
4536                    <CLEANUP>
4537                    "Saved.")
4538                   (T
4539                    <CRLF>
4540                    <PRINC "Amazing program at your service.">
4541                    <CRLF>
4542                    <START-RUNNING>)>>
4543
4544 ### 11.6.2. RESTORE
4545
4546     <RESTORE file-spec>
4547
4548 or
4549
4550     <RESTORE name1 name2 device dir>
4551
4552 **replaces** the entire current state of your Muddle with that `SAVE`d
4553 in the file specified. All arguments are optional, with the same
4554 values used by default as by `SAVE`.
4555
4556 `RESTORE` completely replaces the contents of the Muddle, including
4557 the state of execution existing when the `SAVE` was done and the state
4558 of all open I/O `CHANNEL`s. If a file which was open when the `SAVE`
4559 was done does not exist when the `RESTORE` is done, a message to that
4560 effect will appear on the terminal.
4561
4562 A `RESTORE` **never** returns (unless it gets an error): it causes a
4563 `SAVE` done some time ago to return **again** (this time with the
4564 value `"RESTORED"`), even if the `SAVE` was done in the midst of
4565 running a program. In the latter case, the program will continue its
4566 execution upon `RESTORE`ation.
4567
4568 11.7. Other I/O Functions
4569 -------------------------
4570
4571 ### 11.7.1. LOAD
4572
4573     <LOAD input:channel look-up>
4574
4575 eventually returns `"DONE"`. First, however, it `READ`s and `EVAL`s
4576 every Muddle object in the file pointed to by *input*, and then
4577 `CLOSE`s *input*. Any occurrences of `rubout`, `^@`, `^D`, `^L`, etc.,
4578 in the file are given no special meaning; they are simply `ATOM`
4579 constituents.
4580
4581 *look-up* is optional, used to specify a `LIST` of `OBLIST`s for the
4582 `READ`. `.OBLIST` is used by default (chapter 15).
4583
4584 ### 11.7.2. FLOAD
4585
4586     <FLOAD file-spec look-up>
4587
4588 or
4589
4590     <FLOAD name1 name2 device dir look-up>
4591
4592 ("file load") acts just like `LOAD`, except that it takes arguments
4593 (with values used by default) like `OPEN`, `OPEN`s the `CHANNEL`
4594 itself for reading, and `CLOSE`s the `CHANNEL` when done. *look-up* is
4595 optional, as in `LOAD`. If the `OPEN` fails, an error occurs, giving
4596 the reason for failure.
4597
4598 ### 11.7.3. SNAME
4599
4600 `<SNAME string>` ("system name", a hangover from ITS) is identical in
4601 effect with `<SETG SNM string>`, that is, it causes *string* to become
4602 the *dir* argument used by default by all `SUBR`s which want file
4603 specifications (in the absence of a local value for `SNM`). `SNAME`
4604 returns its argument.
4605
4606 `<SNAME>` is identical in effect with `<GVAL SNM>`, that is, it
4607 returns the current *dir* used by default.
4608
4609 ### 11.7.4. ACCESS
4610
4611     <ACCESS channel fix>
4612
4613 returns *channel*, after making the next character or binary word
4614 (depending on the mode of *channel*, which should not be `"PRINT"`)
4615 which will be input from or output to *channel* the (*fix*+1)st one
4616 from the beginning of the file. *channel* must be open to a randomly
4617 accessible device (`"DSK"`, `"USR"`, etc.). A *fix* of `0` positions
4618 *channel* at the beginning of the file.
4619
4620 ### 11.7.5. FILE-LENGTH
4621
4622     <FILE-LENGTH input:channel>
4623
4624 returns a `FIX`, the length of the file open on *input*. This
4625 information is supplied by the operating system, and it may not be
4626 available, for example, with the `"NET"` device (section 11.10). If
4627 *input*'s mode is `"READ"`, the length is in characters (rounded up to
4628 a multiple of five); if `"READB"`, in binary words. If `ACCESS` is
4629 applied to *input* and this length or more, then the next input
4630 operation will detect the end of file.
4631
4632 ### 11.7.6. FILECOPY
4633
4634     <FILECOPY input:channel output:channel>
4635
4636 copies characters from *input* to *output* until the end of file on
4637 *input* (thus closing *input*) and returns the number of characters
4638 copied. Both arguments are optional, with `.INCHAN` and `.OUTCHAN`
4639 used by default, respectively. The operation is essentially a
4640 `READSTRING` -- `PRINTSTRING` loop. Neither `CHANNEL` need be freshly
4641 `OPEN`ed, and *output* need not be immediately `CLOSE`d. Restriction:
4642 internally a `<FILE-LENGTH input>` is done, which must succeed; thus
4643 `FILECOPY` might lose if *input* is a `"NET"` `CHANNEL`.
4644
4645 ### 11.7.7. RESET
4646
4647     <RESET channel>
4648
4649 returns *channel*, after "resetting" it. Resetting a `CHANNEL` is like
4650 `OPEN`ing it afresh, with only the file-name slots preserved. For an
4651 input `CHANNEL`, this means emptying all input buffers and, if it is a
4652 `CHANNEL` to a file, doing an `ACCESS` to `0` on it. For an output
4653 `CHANNEL`, this means returning to the beginning of the file -- which
4654 implies, if the mode is not `"PRINTO"`, destroying any output done to
4655 it so far. If the opening fails (for example, if the mode slot of
4656 *channel* says input, and if the file specified in its real-name slots
4657 does not exist), `RESET` (like `OPEN`) returns
4658 `#FALSE (reason:string file-spec:string status:fix)`.
4659
4660 ### 11.7.8. BUFOUT
4661
4662     <BUFOUT output:channel>
4663
4664 causes all internal Muddle buffers for *output* to be written out and
4665 returns its argument. This is helpful if the operating system or
4666 Muddle is flaky and you want to attempt to minimize your losses. The
4667 output may be padded with up to four extra spaces, if *output*'s mode
4668 is `"PRINT"`.
4669
4670 ### 11.7.9. RENAME
4671
4672 `RENAME` is for renaming and deleting files. It takes three kinds of
4673 arguments:
4674
4675 -   (a) two file names, in either single- or multi-`STRING` format,
4676         separated by the `ATOM` `TO`,
4677
4678 -   (b) one file name in either format, or
4679
4680 -   (c) a `CHANNEL` and a file name in either format (only in the ITS
4681         version).
4682
4683 Omitted file-name parts use the same values by default as does `OPEN`.
4684 If the operation is successful, `RENAME` returns `T`, otherwise
4685 `#FALSE (reason:string status:fix)`.
4686
4687 In case (a) the file specified by the first argument is renamed to the
4688 second argument. For example:
4689
4690     <RENAME "FOO 3" TO "BAR">       ;"Rename FOO 3 to BAR >."
4691
4692 In case (b) the single file name specifies a file to be deleted. For
4693 example:
4694
4695     <RENAME "FOO FOO DSK:HARRY;">  ;"Rename FOO 3 to BAR >."
4696
4697 In case (c) the `CHANNEL` must be open in either `"PRINT"` or
4698 `"PRINTB"` mode, and a rename while open for writing is attempted. The
4699 real-name slots in the `CHANNEL` are updated to reflect any successful
4700 change.
4701
4702 11.8. Terminal CHANNELs
4703 -----------------------
4704
4705 Muddle behaves like the ITS version of the text editor Teco with
4706 respect to typing in carriage-return, in that it automatically adds a
4707 line-feed. In order to type in a lone carriage-return, a
4708 carriage-return followed by a rubout must be typed. Also `PRINT`,
4709 `PRINT1` and `PRINC` do not automatically add a line-feed when a
4710 carriage-return is output. This enables overstriking on a terminal
4711 that lacks backspacing capability. It also means that what goes on a
4712 terminal and what goes in a file are more likely to look the same.
4713
4714 In the ITS version, Muddle's primary terminal output channel (usually
4715 `,OUTCHAN`) is normally not in "display" mode, except when `PRINC`ing
4716 a `STRING`. Thus errors will rarely occur when a user is typing in
4717 text containing display-mode control codes.
4718
4719 In the ITS version, Muddle can start up without a terminal, give
4720 control of the terminal away to an inferior operating-system process
4721 or get it back while running. Doing a `RESET` on either of the
4722 terminal channels causes Muddle to find out if it now has the
4723 terminal; if it does, the terminal is reopened and the current screen
4724 size and device parameters are updated. If it doesn't have the
4725 terminal, an internal flag is set, causing output to the terminal to
4726 be ignored and attempted input from the terminal to make the
4727 operating-system process go to sleep.
4728
4729 In the ITS version, there are some peculiarities associated with
4730 pseudo-terminals (`"STY"` and `"STn"` devices). If the `CHANNEL` given
4731 to `READCHR` is open in `"READ"` mode to a pseudo-terminal, and if no
4732 input is available, `READCHR` returns `-1`, `TYPE` `FIX`. If the
4733 `CHANNEL` given to `READSTRING` is open in `"READ"` mode to a
4734 pseudo-terminal, reading also stops if and when no more characters are
4735 available, that is, when `READCHR` would return `-1`.
4736
4737 11.8.1. ECHOPAIR
4738 ----------------
4739
4740     <ECHOPAIR terminal-in:channel terminal-out:channel>
4741
4742 returns its first argument, after making the two `CHANNEL`s "know
4743 about each other" so that `rubout`, `^@`, `^D` and `^L` on
4744 *terminal-in* will cause the appropriate output on *terminal-out*.
4745
4746 ### 11.8.2. TTYECHO
4747
4748     <TTYECHO terminal-input:channel pred>
4749
4750 turns the echoing of typed characters on *channel* off or on,
4751 according to whether or not *pred* is `TYPE` `FALSE`, and returns
4752 *channel*. It is useful in conjunction with `TYI` (below) for a
4753 program that wants to do character input and echoing in its own
4754 fashion.
4755
4756 ### 11.8.3. TYI
4757
4758     <TYI terminal-input:channel>
4759
4760 returns one `CHARACTER` from *channel* (optional, `.INCHAN` by
4761 default) when it is typed, rather than after `$` (`ESC`) is typed, as
4762 is the case with `READCHR`. The following example echos input
4763 characters as their ASCII values, until a carriage-return is typed:
4764
4765     <REPEAT ((FOO <TTYECHO .INCHAN <>>))
4766        <AND <==? 13 <PRINC <ASCII <TYI .INCHAN>>>>
4767             <RETURN <TTYECHO .INCHAN T>>>>
4768
4769 11.9. Internal CHANNELs
4770 -----------------------
4771
4772 If the *device* specified in an `OPEN` is `"INT"`, a `CHANNEL` is
4773 created which does not refer to any I/O device outside Muddle. In this
4774 case, the mode must be `"READ"` or `"PRINT"`, and there is another
4775 argument, which must be a function.
4776
4777 For a `"READ"` `CHANNEL`, the function must take no arguments.
4778 Whenever a `CHARACTER` is desired from this `CHANNEL`, the function
4779 will be applied to no arguments and must return a `CHARACTER`. This
4780 will occur once per call to `READCHR` using this `CHANNEL`, and
4781 several times per call to `READ`. In the ITS version, the function can
4782 signal that its "end-of-file" has been reached by returning
4783 `<CHTYPE *777777000003* CHARACTER>` (-1 in left half, control-C in
4784 right), which is the standard ITS end-of-file signal. In the Tenex and
4785 Tops-20 versions, the function should return either that or
4786 `<CHTYPE *777777000032* CHARACTER>` (-1 and control-Z), the latter
4787 being their standard end-of-file signal.
4788
4789 For a `"PRINT"` `CHANNEL`, the function must take one argument, which
4790 will be a `CHARACTER`. It can dispose of its argument in any way it
4791 pleases. The value returned by the function is ignored.
4792
4793 Example: `<OPEN "PRINT" "INT:" ,FCN>` opens an internal output
4794 `CHANNEL` with `,FCN` as its character-gobbler.
4795
4796 11.10. The "NET" Device: the ARPA Network
4797 -----------------------------------------
4798
4799 The `"NET"` device is different in many ways from conventional
4800 devices. In the ITS version, it is the only device besides `"INT"`
4801 that does not take all strings as its arguments to `OPEN`, and it must
4802 take an additional optional argument to specify the byte size of the
4803 socket. The format of a call to open a network socket is
4804
4805     <OPEN mode:string local-socket:fix "NET" foreign-host:fix byte-size:fix>
4806
4807 where:
4808
4809 -   *mode* is the mode of the desired `CHANNEL`. This must be either
4810     `"READ"`, `"PRINT"`, `"READB"` or `"PRINTB"`.
4811 -   *local-socket* is the local socket number. If it is `-1`, the
4812     operating system will generate a unique local socket number. If it
4813     is not, in the Tenex and Tops-20 versions, the socket number is
4814     "fork-relative".
4815 -   *foreign-socket* is the foreign socket number. If it is `-1`, this
4816     is an `OPEN` for "listening".
4817 -   *foreign-host* is the foreign host number. If it is an `OPEN` for
4818     listening, this argument is ignored.
4819 -   *byte-size* is the optional byte size. For `"READ"` or `"PRINT"`
4820     this must be either `7` (used by default) or `8`. For `"READB"` or
4821     `"PRINTB"`, it can be any integer from `1` to `36` (used by
4822     default).
4823
4824 In the Tenex and Tops-20 versions, `OPEN` can instead be given a
4825 `STRING` argument of the form `"NET:..."`. In this case the local
4826 socket number can be "directory-relative".
4827
4828 Like any other `OPEN`, either a `CHANNEL` or a `FALSE` is returned.
4829 Once open, a network `CHANNEL` can be used like any other `CHANNEL`,
4830 except that `FILE-LENGTH`, `ACCESS`, `RENAME`, etc., cannot be done.
4831 The "argument" first-name, second-name, and directory-name slots in
4832 the `CHANNEL` are used for local socket, foreign socket, and foreign
4833 host (as specified in the call to `OPEN`), respectively. The
4834 corresponding "real" slots are used somewhat differently. If a channel
4835 is `OPEN`ed with local socket `-1`, the "real" first-name slot will
4836 contain the unique socket number generated by the operating system. If
4837 a listening socket is `OPEN`ed, the foreign socket and host numbers of
4838 the answering host are stored in the "real" second-name and
4839 directory-name slots of the `CHANNEL` when the Request For Connection
4840 is received.
4841
4842 An interrupt (chapter 21) can be associated with a `"NET"`-device
4843 `CHANNEL`, so that a program will know that the `CHANNEL` has or needs
4844 data, according to its *mode*.
4845
4846 There also exist several special-purpose `SUBR`s for the `"NET"`
4847 device. These are described next.
4848
4849 ### 11.10.1. NETSTATE
4850
4851     <NETSTATE network:channel>
4852
4853 returns a `UVECTOR` of three `FIX`es. The first is the state of the
4854 connection, the second is a code specifying why a connection was
4855 closed, and the last is the number of bits available on the connection
4856 for input. The meaning of the state and close codes are
4857 installation-dependent and so are not included here.
4858
4859 ### 11.10.2. NETACC
4860
4861     <NETACC network:channel>
4862
4863 accepts a connection to a socket that is open for listening and
4864 returns its argument. It will return a `FALSE` if the connection is in
4865 the wrong state.
4866
4867 ### 11.10.3. NETS
4868
4869     <NETS network:channel>
4870
4871 returns its argument, after forcing any system-buffered network output
4872 to be sent. ITS normally does this every half second anyway. Tenex and
4873 Tops-20 do not do it unless and until `NETS` is called. `NETS` is
4874 similar to `BUFOUT` for normal `CHANNEL`s, except that even
4875 operating-system buffers are emptied **now**.
4876
4877 Chapter 12. Locatives
4878 =====================
4879
4880 There is in Muddle a facility for obtaining and working directly with
4881 objects which roughly correspond to "pointers" in assembly language or
4882 "lvals" in BCPL or PAL. In Muddle, these are generically known as
4883 **locatives** (from "location") and are of several `TYPE`s, as
4884 mentioned below. Locatives exist to provide efficient means for
4885 altering structures: direct replacement as opposed to re-copying.
4886
4887 Locatives **always** refer to elements in structures. It is not
4888 possible to obtain a locative to something (for example, an `ATOM`)
4889 which is not part of any structured. It is possible to obtain a
4890 locative to any element in any structured object in Muddle -- even to
4891 associations (chapter 13) and to the values of `ATOM`s, structurings
4892 which are normally "hidden".
4893
4894 In the following, the object occupying the structured position to
4895 which you have obtained a locative will be referred to as the object
4896 **pointed to** by the locative.
4897
4898 12.1. Obtaining Locatives
4899 -------------------------
4900
4901 ### 12.1.1. LLOC
4902
4903     <LLOC atom env>
4904
4905 returns a locative (`TYPE` `LOCD`, "locative to iDentifier") to the
4906 `LVAL` of *atom* in *env*. If *atom* is not bound in *env*, an error
4907 occurs. *env* is optional, with the current `ENVIRONMENT` used by
4908 default. The locative returned by `LLOC` is **independent of future
4909 re-bindings** of *atom*. That is, `IN` (see below) of that locative
4910 will return the same thing even if *atom* is re-bound to something
4911 else; `SETLOC` (see below) will affect only that particular binding of
4912 *atom*.
4913
4914 Since bindings are kept on a stack (tra la), any attempt to use a
4915 locative to an `LVAL` which has become unbound will fetch up an error.
4916 (It breaks just like a `TUPLE`....) `LEGAL?` can, once again, be used
4917 to see if a `LOCD` is valid. Caution: `<SET A <LLOC A>>` creates a
4918 self-reference and can make `PRINT` very unhappy.
4919
4920 ### 12.1.2. GLOC
4921
4922     <GLOC atom pred>
4923
4924 returns a locative (`TYPE` `LOCD`) to the `GVAL` of *atom*. If *atom*
4925 has no `GVAL` **slot**, an error occurs, unless *pred* (optional) is
4926 given and not `FALSE`, in which case a slot is created (chapter 22).
4927 Caution: `<SETG A <GLOC A>>` creates a self-reference and can make
4928 `PRINT` very unhappy.
4929
4930 ### 12.1.3. AT
4931
4932     <AT structured N:fix-or-offset>
4933
4934 returns a locative to the <em>N</em>th element in *structured*. *N* is
4935 optional, `1` by default. The exact `TYPE` of the locative returned
4936 depends on the `PRIMTYPE` of *structured*: `LOCL` for `LIST`, `LOCV`
4937 for `VECTOR`, `LOCU` for `UVECTOR`, `LOCS` for `STRING`, `LOCB` for
4938 `BYTES`, `LOCT` for `TEMPLATE`, and `LOCA` for `TUPLE`. If *N* is
4939 greater than `<LENGTH structured>` or less than `1`, or an `OFFSET`
4940 with a Pattern that doesn't match *structured*, an error occurs. The
4941 locative is unaffected by applications of `REST`, `BACK`, `TOP`,
4942 `GROW`, etc. to *structured*.
4943
4944 ### 12.1.4. GETPL and GETL
4945
4946     <GETPL item:any indicator:any default:any>
4947
4948 returns a locative (`TYPE` `LOCAS`) to the association of *item* under
4949 *indicator*. (See chapter 13 for information about associations.) If
4950 no such association exists, `GETPL` returns `EVAL` of *default*.
4951 *default* is optional, `#FALSE ()` by default.
4952
4953 `GETPL` corresponds to `GETPROP` amongst the association machinery.
4954 There also exists `GETL`, which corresponds to `GET`, returning either
4955 a `LOCAS` or a locative to the *indicator*th element of a structured
4956 *item*. `GETL` is like `AT` if *item* is a structure and *indicator*
4957 is a `FIX` or `OFFSET`, and like `GETPL` if not.
4958
4959 12.2. LOCATIVE?
4960 ---------------
4961
4962 This `SUBR` is a predicate that tells whether or not is argument is a
4963 locative. It is cheaper than
4964 `<MEMQ <PRIMTYPE arg> '![LOCD LOCL ...]>`.
4965
4966 12.3. Using Locatives
4967 ---------------------
4968
4969 The following two `SUBR`s provide the means for working with
4970 locatives. They are independent of the specific `TYPE` of the
4971 locative. The notation *locative* indicates anything which could be
4972 returned by `LLOC`, `GLOC`, `AT`, `GETPL` or `GETL`.
4973
4974 ### 12.3.1. IN
4975
4976     <IN locative>
4977
4978 returns the object to which *locative* points. The only way you can
4979 get an error using `IN` is when *locative* points to an `LVAL` which
4980 has become unbound from an `ATOM`. This is the same as the problem in
4981 referencing `TUPLE`s as mentioned in section 9.2, and it can be
4982 avoided by first testing `<LEGAL? locd>`.
4983
4984 Example:
4985
4986     <SET A 1>$
4987     1
4988     <IN <LLOC A>>$
4989     1
4990
4991 ### 12.3.2. SETLOC
4992
4993     <SETLOC locative any>
4994
4995 returns *any*, after having made *any* the contents of that position
4996 in a structure pointed to by *locative*. The structure itself is not
4997 otherwise disturbed. An error occurs if *locative* is to a
4998 non-`LEGAL?` `LVAL` or if you try to put an object of the wrong `TYPE`
4999 into a `PRIMTYPE` `UVECTOR`, `STRING`, `BYTES`, or `TEMPLATE`.
5000
5001 Example:
5002
5003     <SET A (1 2 3)>$
5004     (1 2 3)
5005     <SETLOC <AT .A 2> HI>$
5006     HI
5007     .A$
5008     (1 HI 3)
5009
5010 12.4. Note on Locatives
5011 -----------------------
5012
5013 You may have noticed that locatives are, strictly speaking,
5014 unnecessary; you can do everything locatives allow by appropriate use
5015 of, for example, `SET`, `LVAL`, `PUT`, `NTH`, etc. What locatives
5016 provide is generality.
5017
5018 Basically, how you obtained a locative is irrelevant to `SETLOC` and
5019 `IN`; thus the same program can play with `GVAL`s, `LVAL`s, object in
5020 explicit structures, etc., without being bothered by what function it
5021 should use to do so. This is particularly true with respect to
5022 locatives to `LVAL`s; the fact that they are independent of changes in
5023 binding can save a lot of fooling around with `EVAL` and
5024 `ENVIRONMENT`s.
5025
5026 Chapter 13. Association (Properties)
5027 ====================================
5028
5029 There is an "associative" data storage and retrieval system embedded
5030 in Muddle which allows the construction of data structures with
5031 arbitrary selectors. It is used via the `SUBR`s described in this
5032 chapter.
5033
5034 13.1. Associative Storage
5035 -------------------------
5036
5037 ### 13.1.1. PUTPROP
5038
5039     <PUTPROP item:any indicator:any value:any>
5040
5041 ("put property") returns *item*, having associated *value* with *item*
5042 under the indicator *indicator*.
5043
5044 ### 13.1.2. PUT
5045
5046     <PUT item:any indicator:any value:any>
5047
5048 is identical to `PUTPROP`, except that, if *item* is structured
5049 **and** *indicator* is of `TYPE` `FIX` or `OFFSET`, it does
5050 `<SETLOC <AT item indicator> value>`. In other words, an element with
5051 an integral selector is stored in the structure itself, instead of in
5052 association space. `PUT` (like `AT`) will get an error if *indicator*
5053 is out of range; `PUTPROP` will not.
5054
5055 ### 13.1.3. Removing Associations
5056
5057 If `PUTPROP` is used **without** its *value* argument, it removes any
5058 association existing between its *item* argument and its *indicator*
5059 argument. If an association did exist, using `PUTPROP` in this way
5060 returns the *value* which was associated. If no association existed,
5061 it returns `#FALSE ()`.
5062
5063 `PUT`, with arguments which refer to association, can be used in the
5064 same way.
5065
5066 If either *item* or *indicator* cease to exist (that is, no one was
5067 pointing to them, so they were garbage-collected), and no locatives to
5068 the association exist, then the association between them ceases to
5069 exist (is garbage-collected).
5070
5071 13.2. Associative Retrieval
5072 ---------------------------
5073
5074 ### 13.2.1. GETPROP
5075
5076     <GETPROP item:any indicator:any exp:any>
5077
5078 ("get property") returns the *value* associated with *item* under
5079 *indicator*, if any. If there is no such association, `GETPROP`
5080 returns `EVAL` of *exp* (that is, *exp* gets `EVAL`ed both at call
5081 time and later).
5082
5083 *exp* is optional. If not given, `GETPROP` returns `#FALSE ()` if it
5084 cannot return a *value*.
5085
5086 Note: *item* and *indicator* in `GETPROP` must be the **same Muddle
5087 objects** used to establish the association; that is, they must be
5088 `==?` to the objects used by `PUTPROP` or `PUT`.
5089
5090 ### 13.2.2. GET
5091
5092     <GET item:any indicator:any exp:any>
5093
5094 is the inverse of `PUT`, using `NTH` or `GETPROP` depending on the
5095 test outlined in section 13.1.2. *exp* is optional and used as in
5096 `GETPROP`.
5097
5098 13.3. Examples of Association
5099 -----------------------------
5100
5101     <SET L '(1 2 3 4)>$
5102     (1 2 3 4)
5103     <PUT .L FOO "L is a list.">$
5104     (1 2 3 4)
5105     <GET .L FOO>$
5106     "L is a list."
5107     <PUTPROP .L 3 '![4]>$
5108     (1 2 3 4)
5109     <GETPROP .L 3>$
5110     ![4!]
5111     <GET .L 3>$
5112     3
5113     <SET N 0>$
5114     0
5115     <PUT .N .L "list on a zero">$
5116     0
5117     <GET .N '(1 2 3 4)>$
5118     #FALSE ()
5119
5120 The last example failed because `READ` generated a new `LIST` -- not
5121 the one which is `L`'s `LVAL`. However,
5122
5123     <GET 0 .L>$
5124     "list on a zero"
5125
5126 works because `<==? .N 0>` is true.
5127
5128 To associate something with the Nth **position** in a structure, as
5129 opposed to its Nth **element**, associate it with
5130 `<REST structure N-1>`, as in the following:
5131
5132     <PUT <REST .L 3> PERCENT 0.3>$
5133     (3 4)
5134     <GET <2 .L> PERCENT>$
5135     #FALSE ()
5136     <GET <REST .L 2> PERCENT>$
5137     0.30000000
5138
5139 Remember comments?
5140
5141     <SET N '![A B C ;"third element" D E]>$
5142     ![A B C D E!]
5143     <GET <REST .N 2> COMMENT>$
5144     "third element"
5145
5146 The `'` in the `<SET N ... >` is to keep `EVAL` from generating a new
5147 `UVECTOR` ("Direct Representation"), which would not have the comment
5148 on it (and which would be a needless duplicate). A "top-level" comment
5149 -- one attached to the entire object returned by `READ` -- is `PUT` on
5150 the `CHANNEL` in use, since there is no position in any structure for
5151 it. If no top-level comment follows the object, `READ` removes the
5152 value (`<PUT channel COMMENT>`); so anybody that wants to see a
5153 top-level comment must look for it after each `READ`.
5154
5155 If you need to have a structure with selectors in more than one
5156 dimension (for example, a sparse matrix that does not deserve to be
5157 linearized), associations can be cascaded to achieve the desired
5158 result. In effect an extra level of indirection maps two indicators
5159 into one. For example, to associate *value* with *item* under
5160 *indicator-1* and *indicator-2* simultaneously:
5161
5162     <PUTPROP indicator-1 indicator-2 T>
5163     <PUTPROP item <GETPL indicator-1 indicator-2> value>
5164
5165 13.4. Examining Associations
5166 ----------------------------
5167
5168 Associations (created by `PUT` and `PUTPROP`) are chained together in
5169 a doubly-linked list, internal to Muddle. The order of associations in
5170 the chain is their order of creation, newest first. There are several
5171 `SUBR`s for examining the chain of associations. `ASSOCIATIONS`
5172 returns the first association in the chain, or `#FALSE ()` if there
5173 are none. `NEXT` takes an association as an argument and returns the
5174 next association in the chain, or `#FALSE ()` if there are no more.
5175 `ITEM`, `INDICATOR` and `AVALUE` all take an association as an
5176 argument and return the item, indicator and value, respectively.
5177 Associations print as:
5178
5179     #ASOC (item indicator value)
5180
5181 (sic: only one `S`). Example: the following gathers all the existing
5182 associations into a `LIST`.
5183
5184     <PROG ((A <ASSOCIATIONS>))
5185      <COND (<NOT .A> '())
5186            (T (.A !<MAPF ,LIST
5187                     <FUNCTION () <COND (<SET A <NEXT .A>> .A)
5188                                        (T <MAPSTOP>)>>>))>>
5189
5190 Chapter 14. Data-type Declarations
5191 ==================================
5192
5193 In Muddle, it is possible to declare the permissible range of "types"
5194 and/or structures that an `ATOM`'s values or a function's arguments or
5195 value may have. This is done using a special `TYPE`, the `DECL`
5196 ("declaration"). A `DECL` is of `PRIMTYPE` `LIST` but has a
5197 complicated internal structure. `DECL`s are used by the interpreter to
5198 find `TYPE` errors in function calling and by the compiler to generate
5199 more efficient code.
5200
5201 There are two kinds of `DECL`s. The first kind of `DECL` is the most
5202 common. It is called the `ATOM` `DECL` and is used most commonly to
5203 specify the type/structure of the `LVAL`s of the `ATOM`s in the
5204 argument `LIST` of a `FUNCTION` or *aux* `LIST` of a `PROG` or
5205 `REPEAT`. This `DECL` has the form:
5206
5207     #DECL (atoms:list Pattern ...)
5208
5209 where the pairing of a `LIST` of `ATOM`s and a "Pattern" can be
5210 repeated indefinitely. This declares the `ATOM`s in a *list* to be of
5211 the type/structure specified in the following *Pattern*. The special
5212 `ATOM` `VALUE`, if it appears, declares the result of a `FUNCTION`
5213 call or `PROG` or `REPEAT` evaluation to satisfy the Pattern
5214 specified. An `ATOM` `DECL` is useful in only one place: immediately
5215 following the argument `LIST` of a `FUNCTION`, `PROG`, or `REPEAT`. It
5216 normally includes `ATOM`s in the argument `LIST` and `ATOM`s whose
5217 `LVAL`s are otherwise used in the Function body.
5218
5219 The second kind of `DECL` is rarely seen by the casual Muddle user,
5220 except in appendix 2. It is called the `RSUBR` `DECL`. It is used to
5221 specify the type/structure of the arguments and result of an `RSUBR`
5222 or `RSUBR-ENTRY` (chapter 19). It is of the following form:
5223
5224     #DECL ("VALUE" Pattern Pattern ...)
5225
5226 where the `STRING` `"VALUE"` precedes the specification of the
5227 type/structure of the value of the call to the `RSUBR`, and the
5228 remaining *Patterns* specify the arguments to the `RSUBR` in order.
5229 The full specification of the `RSUBR` `DECL` will be given in section
5230 14.9. The `RSUBR` `DECL` is useful in only one place: as an element of
5231 an `RSUBR` or `RSUBR-ENTRY`.
5232
5233 14.1. Patterns
5234 --------------
5235
5236 The simplest possible Pattern is to say that a value is exactly some
5237 other object, by giving that object, `QUOTE`d. For example, to declare
5238 that a variable is a particular `ATOM`:
5239
5240     #DECL ((X) 'T)
5241
5242 declares that `.X` is always the `ATOM` `T`. When variables are
5243 `DECL`ed as "being" some other object in this way, the test used is
5244 `=?`, not `==?`. The distinction is usually not important, since
5245 `ATOM`s, which are most commonly used in this construction, are `==?`
5246 to each other is `=?` anyway.
5247
5248 It is more common to want to specify that a value must be of a given
5249 `TYPE`. This is done with the simplest non-specific Pattern, a `TYPE`
5250 name. For example,
5251
5252     #DECL ((X) FIX (Y) FLOAT)
5253
5254 declares `.X` to be of `TYPE` `FIX`, and `.Y` of `TYPE` `FLOAT`. In
5255 addition to the names of all of the built-in and created `TYPE`s, such
5256 as `FIX`, `FLOAT` and `LIST`, a few "compound" type names are allowed:
5257
5258 -   `ANY` allows any `TYPE`.
5259 -   `STRUCTURED` allows any structured `TYPE`, such as `LIST`,
5260     `VECTOR`, `FALSE`, `CHANNEL`, etc. (appendix 3).
5261 -   `LOCATIVE` allows any locative `TYPE`, such as are returned by
5262     `LLOC`, `GLOC`, `AT`, and so on (chapter 12).
5263 -   `APPLICABLE` allows any applicable `TYPE`, such as `FUNCTION`,
5264     `SUBR`, `FIX` (!), etc. (appendix 3).
5265 -   Any other `ATOM` can be used to stand for a more complex
5266     construct, if an association is established on that `ATOM` and the
5267     `ATOM` `DECL`. A common example is to
5268     `<PUT NUMBER DECL '<OR FIX FLOAT>>` (see below), so that `NUMBER`
5269     can be used as a "compound type name".
5270
5271 The single `TYPE` name can be generalized slightly, allowing anything
5272 of a given `PRIMTYPE`, using the following construction:
5273
5274     #DECL ((X) <PRIMTYPE WORD> (Y) <PRIMTYPE LIST>)
5275
5276 This construction consists of a two-element `FORM`, where the first
5277 element is the `ATOM` `PRIMTYPE`, and the second the name of a
5278 primitive type.
5279
5280 The next step is to specify the elements of a structure. This is done
5281 in the simplest way as follows:
5282
5283     < structured:type Pattern Pattern ...>
5284
5285 where there is a one-to-one correspondence between the *Pattern* and
5286 the elements of the structure. For example:
5287
5288     #DECL ((X) <VECTOR FIX FLOAT>)
5289
5290 declares `.X` to be a `VECTOR` having **at least** two elements, the
5291 first of which is a `FIX` and the second a `FLOAT`. It is often
5292 convenient to allow additional elements, so that only the elements
5293 being used in the local neighborhood of the `DECL` need to be
5294 declared. To disallow additional elements, a `SEGMENT` is used instead
5295 of a `FORM` (the "excl-ed" brackets make it look more emphatic). For
5296 example:
5297
5298     #DECL ((X) !<VECTOR FIX FLOAT>)
5299
5300 declares `.X` to be a `VECTOR` having **exactly** two elements, the
5301 first of which is a `FIX` and the second a `FLOAT`. Note that the
5302 *Patterns* given for elements can be any legal Pattern:
5303
5304     #DECL ((X) <VECTOR <VECTOR FIX FLOAT>> (Y) <<PRIMTYPE LIST> LIST>)
5305
5306 declares `.X` to be a `VECTOR` containing another `VECTOR` of at least
5307 two elements, and `.Y` to be of `PRIMTYPE LIST`, containing a `LIST`.
5308 In the case of a `BYTES`, the individual elements cannot be declared
5309 (they must be `FIX`es anyway), only the size and number of the bytes:
5310
5311     #DECL ((B) <BYTES 7 3>)
5312
5313 declares `.B` to be a `BYTES` with `BYTE-SIZE` 7 and at least three
5314 elements.
5315
5316 It is possible to say that some number of elements of a structure
5317 satisfy a given Pattern (or sequence of Patterns). This is called an
5318 "`NTH` construction".
5319
5320     [ number:fix Pattern Pattern ... ]
5321
5322 states that the sequence of *Patterns* which is `REST` of the `VECTOR`
5323 is repeated the *number* of times given. For example:
5324
5325     #DECL ((X) <VECTOR [3 FIX] FLOAT> (Y) <LIST [3 FIX FLOAT]>)
5326
5327 `.X` is declared to contain three `FIX`es and a `FLOAT`, perhaps
5328 followed by other elements. `.Y` is declared to repeat the sequence
5329 `FIX`-`FLOAT` three times. Note that there may be more repetitions of
5330 the sequence in `.Y` (but not in `.X`): the `DECL` specifies only the
5331 first six elements.
5332
5333 For indefinite repetition, the same construction is used, but, instead
5334 of the number of repetitions of the sequence of Patterns, the `ATOM`
5335 `REST` is given. This allows any number of repetitions, from zero on
5336 up. For example:
5337
5338     #DECL ((X) <VECTOR [REST FIX]> (Y) <LIST [3 FIX] [REST FIX]>)
5339
5340 A "`REST` construction" can contain any number of Patterns, just like
5341 an `NTH` construction:
5342
5343     #DECL ((X) <VECTOR [REST FIX FLOAT LIST]>)
5344
5345 declares that `.X` is a `VECTOR` wherein the sequence
5346 `FIX`-`FLOAT`-`LIST` repeats indefinitely. It does not declare that
5347 `<LENGTH .X>` is an even multiple of three: the `VECTOR` can end at
5348 any point.
5349
5350 A variation on `REST` is `OPT` (or `OPTIONAL`), which is similar to
5351 `REST` except that the construction is scanned once at most instead of
5352 indefinitely, and further undeclared elements can follow. For example:
5353
5354     #DECL ((X) <VECTOR [OPT FIX]>)
5355
5356 declares that `.X` is a `VECTOR` which is empty or whose first element
5357 is a `FIX`. Only a `REST` construction can follow an "`OPT`
5358 construction".
5359
5360 Note that the `REST` construction must always be the last element of
5361 the structure declaration, since it gives a Pattern for the rest of
5362 the structure. Thus, the `REST` construction is different from all
5363 others in that it has an unlimited range. No matter how many times the
5364 Pattern it gives is `REST`ed off of the structure, the remainder of
5365 the structure still has that Pattern.
5366
5367 This exhausts the possible single Patterns that can be given in a
5368 declaration. However, there is also a compound Pattern defined. It
5369 allows specification of several possible Patterns for one value:
5370
5371     <OR Pattern Pattern ... >
5372
5373 Any non-compound Pattern can be included as one of the elements of the
5374 compound Pattern. Finally, compound Patterns can be used as Patterns
5375 for elements of structures, and so on.
5376
5377     #DECL ((X) <OR FIX FLOAT>
5378            (Y) <OR FIX <UVECTOR [REST <OR FIX FLOAT>]>>)
5379
5380 The `OR` construction can be extended to any level of ridiculousness,
5381 but the higher the level of complexity and compoundedness the less
5382 likely the compiler will find the `DECL` useful.
5383
5384 At the highest level, any Pattern at top level in an `ATOM` `DECL` can
5385 be enclosed in the construction
5386
5387     < specialty:atom Pattern >
5388
5389 which explicitly declares the specialty of the `ATOM`(s) in the
5390 preceding `LIST`. *specialty* can be either `SPECIAL` or `UNSPECIAL`.
5391 Specialty is important only when the program is to be compiled. The
5392 word comes from the control stack, which is called "special" in Lisp
5393 (Moon, 1974) because the garbage collector finds objects on it and
5394 modifies their internal pointers when storage is compacted. (An
5395 internal stack is used within the interpreter and is not accessible to
5396 programs -- section 22.1) In an interpreted program all local values
5397 are inherently `SPECIAL`, because all bindings are put on the control
5398 stack (but see `SPECIAL-MODE` below). When the program is compiled,
5399 only values declared `SPECIAL` (which may or may not be the
5400 declaration used by default) remain in bindings on the control stack.
5401 All others are taken care of simply by storing objects on the control
5402 stack: the `ATOM`s involved are not needed and are not created on
5403 loading. So, a program that `SET`s an `ATOM`'s local value for another
5404 program to pick up must declare that `ATOM` to be `SPECIAL`. If it
5405 doesn't, the `ATOM`'s binding will go away during compiling, and the
5406 program that needs to refer to the `ATOM` will either get a no-value
5407 error or refer to an erroneous binding. Usually only `ATOM`s which
5408 have the opposite specialty from that of the current `SPECIAL-MODE`
5409 are explicitly declared. The usual `SPECIAL-MODE` is `UNSPECIAL`, so
5410 typically only `SPECIAL` declarations use this construction:
5411
5412     #DECL ((ACT)) <SPECIAL ACTIVATION>)
5413
5414 explicitly declares `ACT` to be `SPECIAL`.
5415
5416 Most well-written, modular programs get all their information from
5417 their arguments and from `GVAL`s, and thus they rarely use `SPECIAL`
5418 `ATOM`s, except perhaps for `ACTIVATION`s and the `ATOM`s whose
5419 `LVAL`s Muddle uses by default: `INCHAN`, `OUTCHAN`, `OBLIST`, `DEV`,
5420 `SNM`, `NM1`, `NM2`. `OUTCHAN` is a special case: the compiler thinks
5421 that all conversion-output `SUBR`s are called with an explicit
5422 `CHANNEL` argument, whether or not the program being compiled thinks
5423 so. For example, `<CRLF>` is compiled as though it were
5424 `<CRLF .OUTCHAN>`. So you may use (or see) the binding
5425 `(OUTCHAN .OUTCHAN)` in an argument `LIST`, however odd that may
5426 appear, because that -- coupled with the usual `UNSPECIAL` declaration
5427 by default -- makes only one reference to the current binding of
5428 `OUTCHAN` and stuffs the result in a slot on the stack for use within
5429 the Function.
5430
5431 14.2. Examples
5432 --------------
5433
5434     #DECL ((Q) <OR VECTOR CHANNEL>)
5435
5436 declares .Q to be either a `VECTOR` or a `CHANNEL`.
5437
5438     #DECL ((P Q R S) <PRIMTYPE LIST>)
5439
5440 declares `.P`, `.Q`, `.R`, and `.S` all to be of `PRIMTYPE` `LIST`.
5441
5442     #DECL ((F) <FORM [3 ANY]>)
5443
5444 declares `.F` to be a `FORM` whose length is at least three,
5445 containing objects of any old `TYPE`.
5446
5447     #DECL ((LL) <<PRIMTYPE LIST> [4 <LIST [REST FIX]>]>)
5448
5449 declares `.LL` to be of `PRIMTYPE` `LIST`, and to have at least four
5450 elements, each of which are `LIST`s of unspecified length (possibly
5451 empty) containing `FIX`es.
5452
5453     #DECL ((VV) <VECTOR FIX ATOM CHARACTER>)
5454
5455 declares `.VV` to be a `VECTOR` with at least three elements. Those
5456 elements are, in order, of `TYPE` `FIX`, `ATOM`, and `CHARACTER`.
5457
5458     #DECL ((EH) <LIST ATOM [REST FLOAT]>)
5459
5460 declares `.EH` to be a `LIST` whose first element is an `ATOM` and the
5461 rest of whose elements are `FLOAT`s. It also says that `.EH` is at
5462 least one element long.
5463
5464     #DECL ((FOO) <LIST [REST 'T FIX]>)
5465
5466 declares `.FOO` to be a `LIST` whose odd-positioned elements are the
5467 `ATOM` `T` and whose even-positioned elements are `FIX`es.
5468
5469     <MAPR <>
5470           <FUNCTION (X)
5471             #DECL ((X) <VECTOR [1 FIX]>)
5472             <PUT .X 1 0>>
5473           .FOO>
5474
5475 declares `.X` to be a `VECTOR` containing at least one `FIX`. The more
5476 restrictive `[REST FIX]` would take excessive checking time by the
5477 interpreter, because the `REST` of the `VECTOR` would be checked on
5478 each iteration of the `MAPR`. In this case both `DECL`s are equally
5479 powerful, because checking the first element of all the `REST`s of a
5480 structure eventually checks all the elements. Also, since the
5481 `FUNCTION` refers only to the first element of `X`, this is as much
5482 declaration as the compiler can effectively use. (If this `VECTOR`
5483 always contains only `FIX`es, it should be a `UVECTOR` instead, for
5484 space efficiency. Then a `[REST FIX]` `DECL` would make the
5485 interpreter check only the `UTYPE`. If the `FIX`es cover a small
5486 non-negative range, then a `BYTES` might be even better, with a `DECL`
5487 of `<BYTES n 0>`.)
5488
5489     <DEFINE FACT (N)
5490             #DECL ((N) <UNSPECIAL FIX>)
5491             <COND (<0? .N> 1) (ELSE <* .N <FACT <- .N 1>>>)>>
5492
5493 declares `.N` to be of `TYPE` `FIX` and `UNSPECIAL`. This specialty
5494 declaration ensures that, independent of `SPECIAL-MODE` during
5495 compiling, `.N` gets compiled into a fast control-stack reference.
5496
5497     <PROG ((L (0))
5498             #DECL ((L VALUE) <UNSPECIAL <LIST [REST FIX]>>
5499                    (N <UNSPECIAL FIX>))
5500             <COND (<0? .N> <RETURN .L>)>
5501             <SET L (<+ .N <1 .L>> !.L)>
5502             <SET N <- .N 1>>>
5503
5504 The above declares `L` and `N` to be `UNSPECIAL`, says that `.N` is a
5505 `FIX`, and says that `.L`, along with the value returned, is a `LIST`
5506 of any length composed entirely of `FIX`es.
5507
5508 14.3. The DECL Syntax
5509 ---------------------
5510
5511 This section gives quasi-BNF productions for the Muddle `DECL` syntax.
5512 In the following table Muddle type-specifiers are distinguished *in
5513 this way*.
5514
5515     decl    ::=     #DECL (declprs)
5516
5517     declprs ::=     (atlist) pattern | declprs declprs
5518
5519     atlist  ::=     atom | atom atlist
5520
5521     pattern ::=     pat | <UNSPECIAL pat> | <SPECIAL pat>
5522
5523     pat     ::=     unit | <OR unit ... unit>
5524
5525     unit    ::=     type | <PRIMTYPE type> | atom | 'any
5526                     | ANY | STRUCTURED | LOCATIVE |APPLICABLE
5527                     | <struc elts> | <<OR struc ... struc> elts>
5528                     | !<struc elts> | !<<OR struc ... struc> elts>
5529                     | <bstruc fix> | <bstruc fix fix>
5530                     | !<bstruc fix fix>
5531
5532     struc   ::=     structured-type | <PRIMTYPE structured-type>
5533
5534     bstruc  ::=     BYTES | <PRIMTYPE BYTES>
5535
5536     elts    ::=     pat | pat elts
5537                     | [fix pat ... pat]
5538                     | [fix pat ... pat] elts
5539                     | [opt pat ... pat] | [REST pat ... pat]
5540                     | [opt pat ... pat] [REST pat ... pat]
5541
5542     opt     ::=     OPT | OPTIONAL
5543
5544 14.4. Good DECLs
5545 ----------------
5546
5547 There are some rules of thumb concerning "good" `DECL`s. A "good"
5548 `DECL` is one that is minimally offensive to the `DECL`-checking
5549 mechanism as the compiler, but that gives the maximum amount of
5550 information. It is simple to state what gives offense to the compiler
5551 and `DECL`-checking mechanism: complexity. For example, a large
5552 compound `DECL` like:
5553
5554     #DECL ((X) <OR FIX LIST UVECTOR FALSE>)
5555
5556 is a `DECL` that the compiler will find totally useless. It might as
5557 well be `ANY`. The more involved the `OR`, the less information the
5558 compiler will find useful in it. For example, if the function takes
5559 `<OR LIST VECTOR UVECTOR>`, maybe you should really say `STRUCTURED`.
5560 Also, a very general `DECL` indicates a very general program, which is
5561 not likely to be efficient when compiled (of course there is a
5562 trade-off here). Narrowing the `DECL` to one `PRIMTYPE` gives a great
5563 gain in compiled efficiency, to one `TYPE` still more.
5564
5565 Another situation to be avoided is the ordinary large `DECL`, even if
5566 it is perfectly straightforward. If you have created a structure which
5567 has a very specific `DECL` and is used all over your code, it might be
5568 better as a `NEWTYPE` (see below). The advantage of a `NEWTYPE` over a
5569 large explicit `DECL` is twofold. First, the entire structure must be
5570 checked only when it is created, that is, `CHTYPE`d from its
5571 `PRIMTYPE`. As a full `DECL`, it is checked completely on entering
5572 each function and on each reassignment of `ATOM`s `DECL`ed to be it.
5573 Second, the amount of storage saved in the `DECL`s of `FUNCTION`s and
5574 so on is large, not to mention the effort of typing in and keeping up
5575 to date several instances of the full `DECL`.
5576
5577 14.5. Global DECLs
5578 ------------------
5579
5580 ### 15.4.1. GDECL and MANIFEST
5581
5582 There are two ways to declare `GVAL`s for the `DECL`-checking
5583 mechanism. These are through the `FSUBR` `GDECL` ("global
5584 declaration") and the `SUBR` `MANIFEST`.
5585
5586     <GDECL atoms:list Pattern ...>
5587
5588 `GDECL` allows the type/structure of global values to be declared in
5589 much the same way as local values. Example:
5590
5591     <GDECL (X) FIX (Y) <LIST FIX>>
5592
5593 declares `,X` to be a `FIX`, and `,Y` to be a `LIST` containing at
5594 least one `FIX`.
5595
5596     <MANIFEST atom atom ...>
5597
5598 `MANIFEST` takes as arguments `ATOM`s whose `GVAL`s are declared to be
5599 constants. It is used most commonly to indicate that certain `ATOM`s
5600 are the names of offsets in structures. For example:
5601
5602     <SETG X 1>
5603     <MANIFEST X>
5604
5605 allows the compiler to confidently open-compile applications of `X`
5606 (getting the first element of a structure), knowing that `,X` will not
5607 change. Any sort of object can be a `MANIFEST` value: if it does not
5608 get embedded in the compiled code, it is included in the `RSUBR`'s
5609 "reference vector", for fast access. However, as a general rule,
5610 structured objects should not be made `MANIFEST`: the `SETG` will
5611 instead refer to a **distinct** copy of the object in **each** `RSUBR`
5612 that does a `GVAL`. A structured object should instead be `GDECL`ed.
5613
5614 An attempt to `SETG` a `MANIFEST` atom will cause an error, unless
5615 either:
5616
5617 1.  the `ATOM` was previously globally unassigned;
5618 2.  the old value is `==?` to the new value; or
5619 3.  `.REDEFINE` is not `FALSE`.
5620
5621 ### 14.5.2. MANIFEST? and UNMANIFEST
5622
5623     <MANIFEST? atom>
5624
5625 returns `T` if *atom* is `MANIFEST`, `#FALSE ()` otherwise.
5626
5627     <UNMANIFEST atom atom ...>
5628
5629 removes the `MANIFEST` of the global value of each of its arguments so
5630 that the value can be changed.
5631
5632 ### 14.5.3. GBOUND?
5633
5634     <GBOUND? atom>
5635
5636 ("globally bound") returns `T` if *atom* has a global value slot (that
5637 is, if it has ever been `SETG`ed, `MANIFEST`, `GDECL`ed, or `GLOC`ed
5638 (chapter 12) with a true second argument), `#FALSE ()` otherwise.
5639
5640 14.6. NEWTYPE (again)
5641 ---------------------
5642
5643 `NEWTYPE` gives the programmer another way to `DECL` objects. The
5644 third (and optional) argument of `NEWTYPE` is a `QUOTE`d Pattern. If
5645 given, it will be saved as the value of an association (chapter 13)
5646 using the name of the `NEWTYPE` as the item and the `ATOM` `DECL` as
5647 the indicator, and it will be used to check any object that is about
5648 to be `CHTYPE`d to the `NEWTYPE`. For example:
5649
5650     <NEWTYPE COMPLEX-NUMBER VECTOR '<<PRIMTYPE VECTOR> FLOAT FLOAT>>
5651
5652 creates a new `TYPE`, with its first two elements declared to be
5653 `FLOAT`s. If later someone types:
5654
5655     #COMPLEX-NUMBER [1.0 2]
5656
5657 an error will result (the second element is not a `FLOAT`). The
5658 Pattern can be replaced by doing another `NEWTYPE` for the same
5659 `TYPE`, or by putting a new value in the association. Further
5660 examples:
5661
5662     <NEWTYPE FOO LIST '<<PRIMTYPE LIST> FIX FLOAT [REST ATOM]>>
5663
5664 causes `FOO`s to contain a `FIX` and a `FLOAT` and any number of
5665 `ATOM`s.
5666
5667     <NEWTYPE BAR LIST>
5668
5669     <SET A #BAR (#BAR () 1 1.2 GRITCH)>
5670
5671     <NEWTYPE BAR LIST '<<PRIMTYPE LIST> BAR [REST FIX FLOAT ATOM]>>
5672
5673 This is an example of a recursively `DECL`ed `TYPE`. Note that
5674 `<1 .A>` does not satisfy the `DECL`, because it is empty, but it was
5675 `CHTYPE`d before the `DECL` was associated with `BAR`. Now, even
5676 `<CHTYPE <1 .A> <TYPE <1 .A>>>` will cause an error.
5677
5678 In each of these examples, the `<<PRIMTYPE ...> ...>` construction was
5679 used, in order to permit `CHTYPE`ing an object into itself. See what
5680 happens otherwise:
5681
5682     <NEWTYPE OOPS LIST '<LIST ATOM FLOAT>>$
5683     OOPS
5684     <SET A <CHTYPE (E 2.71828) OOPS>>$
5685     #OOPS (E 2.71828)
5686
5687 Now `<CHTYPE .A OOPS>` will cause an error. Unfortunately, you must
5688
5689     <CHTYPE <CHTYPE .A LIST> OOPS>$
5690     #OOPS (E 2.71828)
5691
5692 14.7. Controlling DECL Checking
5693 -------------------------------
5694
5695 There are several `SUBR`s and `FSUBR`s in Muddle that are used to
5696 control and interact with the `DECL`-checking mechanism.
5697
5698 ### 14.7.1. DECL-CHECK
5699
5700 This entire complex checking mechanism can get in the way during
5701 debugging. As a result, the most commonly used `DECL`-oriented `SUBR`
5702 is `DECL-CHECK`. It is used to enable and disable the entire
5703 `DECL`-checking mechanism.
5704
5705     <DECL-CHECK false-or-any>
5706
5707 If its single argument is non-`FALSE`, `DECL` checking is turned on;
5708 if it is `FALSE`, `DECL` checking is turned off. The previous state is
5709 returned as a value. If no argument is given, `DECL-CHECK` returns the
5710 current state. In an initial Muddle `DECL` checking is on.
5711
5712 When `DECL` checking is on, the `DECL` of an `ATOM` is checked each
5713 time it is `SET`, the arguments and results of calls to `FUNCTION`s,
5714 `RSUBR`s, and `RSUBR-ENTRY`s are checked, and the values returned by
5715 `PROG` and `REPEAT` are checked. The same is done for `SETG`s and, in
5716 particular, attempts to change `MANIFEST` global values. Attempts to
5717 `CHTYPE` an object to a `NEWTYPE` (if the `NEWTYPE` has the optional
5718 `DECL`) are also checked. When `DECL` checking is off, none of these
5719 checks is performed.
5720
5721 ### 14.7.2. SPECIAL-CHECK and SPECIAL-MODE
5722
5723     <SPECIAL-CHECK false-or-any>
5724
5725 controls whether or not `SPECIAL` checking is performed at run time by
5726 the interpreter. It is initially off. Failure to declare an `ATOM` to
5727 be `SPECIAL` when it should be will produce buggy compiled code.
5728
5729     <SPECIAL-MODE specialty:atom>
5730
5731 sets the declaration used by default (for `ATOM`s not declared either
5732 way) and returns the previous such declaration, or the current such
5733 declaration if no argument is given. The initial declaration used by
5734 default is `UNSPECIAL`.
5735
5736 ### 14.7.3. GET-DECL and PUT-DECL
5737
5738 `GET-DECL` and `PUT-DECL` are used to examine and change the current
5739 `DECL` (of either the global or the local value) of an `ATOM`.
5740
5741     <GET-DECL locd>
5742
5743 returns the `DECL` Pattern (if any, otherwise `#FALSE ()`) associated
5744 with the global or local value slot of an `ATOM`. For example:
5745
5746     <PROG (X)
5747           #DECL ((X) <OR FIX FLOAT>)
5748           ...
5749           <GET-DECL <LLOC X>>
5750           ...>
5751
5752 would return `<OR FIX FLOAT>` as the result of the application of
5753 `GET-DECL`. Note that because of the use of `LLOC` (or `GLOC`, for
5754 global values) the `ATOM` being examined must be bound; otherwise you
5755 will get an error! This can be gotten around by testing first with
5756 `BOUND?` (or `GBOUND?`, or by giving `GLOC` a second argument which is
5757 not `FALSE`).
5758
5759 If the slot being examined is the global slot and the value is
5760 `MANIFEST`, then the `ATOM` `MANIFEST` is returned. If the value being
5761 examined is not `DECL`ed, `#FALSE ()` is returned.
5762
5763     <PUT-DECL locd Pattern>
5764
5765 makes *Pattern* be the `DECL` for the value and returns *locd*. If
5766 `<DECL-CHECK>` is true, the current value must satisfy the new
5767 Pattern. `PUT-DECL` is normally used in debugging, to change the
5768 `DECL` of an object to correspond to changes in the program. Note that
5769 it is not legal to `PUT-DECL` a "Pattern" of `MANIFEST` or
5770 `#FALSE ()`.
5771
5772 ### 14.7.4. DECL?
5773
5774     <DECL? any Pattern>
5775
5776 specifically checks *any* against *Pattern*. For example:
5777
5778     <DECL? '[1 2 3] '<VECTOR [REST FIX]>>$
5779     T
5780     <DECL? '[1 2.0 3.0] '<VECTOR [REST FIX]>>$
5781     #FALSE ()
5782
5783 14.8. OFFSET
5784 ------------
5785
5786 An `OFFSET` is essentially a `FIX` with a Pattern attached, considered
5787 as an `APPLICABLE` rather than a number. An `OFFSET` allows a program
5788 to specify the type of structure that its `FIX` applies to. `OFFSET`s,
5789 like `DECL`s -- if used properly -- can make debugging considerably
5790 easier; they will eventually also help the compiler generate more
5791 efficient code.
5792
5793 The `SUBR` `OFFSET` takes two arguments, a `FIX` and a Pattern, and
5794 returns an object of `TYPE` and `PRIMTYPE` `OFFSET`. An `OFFSET`, like
5795 a `FIX`, may be given as an argument to `NTH` or `PUT` and may be
5796 applied to arguments. The only difference is that the `STRUCTURED`
5797 argument must match the Pattern contained in the `OFFSET`, or an error
5798 will result. Thus:
5799
5800     <SETG FOO <OFFSET 1 '<CHANNEL FIX>>>$
5801     %<OFFSET 1 '<CHANNEL FIX>>
5802     <FOO ,INCHAN>$
5803     1
5804     <FOO <ROOT>>$
5805     *ERROR*
5806     ARG-WRONG-TYPE
5807     NTH
5808     LISTENING-AT-LEVEL 2 PROCESS 1
5809
5810 Note: when the compiler gets around to understanding `OFFSET`s, it
5811 will not do the right thing with them unless they are `MANIFEST`.
5812 Since there's no good reason not to `MANIFEST` them, this isn't a
5813 problem.
5814
5815 The `SUBR` `INDEX`, given an `OFFSET`, returns its `FIX`:
5816
5817     <INDEX ,FOO>$
5818     1
5819
5820 `GET-DECL` of an `OFFSET` returns the associated Pattern; `PUT-DECL`
5821 of an `OFFSET` and a Pattern returns a new `OFFSET` with the same
5822 `INDEX` as the argument, but with a new Pattern:
5823
5824     <GET-DECL ,FOO>$
5825     <CHANNEL FIX>
5826     <PUT-DECL ,FOO OBLIST>$
5827     %<OFFSET 1 OBLIST>
5828     ,FOO$
5829     %<OFFSET 1 '<CHANNEL FIX>>
5830
5831 An `OFFSET` is not a structured object, as this example should make
5832 clear.
5833
5834 14.9. The RSUBR DECL
5835 --------------------
5836
5837 The `RSUBR` `DECL` is similar to the `ATOM` `DECL`, except that the
5838 declarations are of argument positions and value rather than of
5839 specific `ATOM`s. Patterns can be preceded by `STRING`s which further
5840 describe the argument (or value).
5841
5842 The simplest `RSUBR` `DECL` is for an `RSUBR` or `RSUBR-ENTRY`
5843 (chapter 19) which has all of its arguments evaluated and returns a
5844 `DECL`ed value. For example:
5845
5846     #DECL ("VALUE" FIX FIX FLOAT)
5847
5848 declares that there are two arguments, a `FIX` and a `FLOAT`, and a
5849 result which is a `FIX`. While the `STRING` `"VALUE"` is not
5850 constrained to appear at the front of the `DECL`, it does appear there
5851 by custom. It need not appear at all, if the result is not to be
5852 declared, but (again by custom) in this case it is usually declared
5853 `ANY`.
5854
5855 If any arguments are optional, the `STRING` `"OPTIONAL"` (or `"OPT"`)
5856 is placed before the Pattern for the first optional argument:
5857
5858     #DECL ("VALUE" FIX FIX "OPTIONAL" FLOAT)
5859
5860 If any of the arguments is not to be evaluated, it is preceded by the
5861 `STRING` `"QUOTE"`:
5862
5863     #DECL ("VALUE" FIX "QUOTE" FORM)
5864
5865 declares one argument, which is not `EVAL`ed.
5866
5867 If the arguments are to be evaluated and gathered into a `TUPLE`, the
5868 Pattern for it is preceded by the `STRING` `"TUPLE"`:
5869
5870     #DECL ("VALUE" FIX "TUPLE" <TUPLE [REST FIX]>)
5871
5872 If the arguments are to be unevaluated and gathered into a `LIST`, or
5873 if the calling `FORM` is the only "argument", the Pattern is preceded
5874 by the appropriate `STRING`:
5875
5876     #DECL ("VALUE" FIX "ARGS" LIST)
5877
5878     #DECL ("VALUE" FIX "CALL" <PRIMTYPE LIST>)
5879
5880 In every case the special indicator `STRING` is followed by a Pattern
5881 which describes the argument, even though it may sometimes produce
5882 fairly ludicrous results, since the pattern for `"TUPLE"` always must
5883 be a `TUPLE`; for `"ARGS"`, a `LIST`; and for `"CALL"`, a `FORM` or
5884 `SEGMENT`.
5885
5886 Chapter 15. Lexical Blocking
5887 ============================
5888
5889 Lexical, or static, blocking is another means of preventing identifier
5890 collisions in Muddle. (The first was dynamic blocking -- binding and
5891 `ENVIRONMENT`s.) By using a subset of the Muddle lexical blocking
5892 facilities, the "block structure" of such languages as Algol, PL/I,
5893 SAIL, etc., can be simulated, should you wish to do so.
5894
5895 15.1. Basic Considerations
5896 --------------------------
5897
5898 Since what follows appears to be rather complex, a short discussion of
5899 the basic problem lexical blocking solves and Muddle's basic solution
5900 will be given first.
5901
5902 `ATOM`s are identifiers. It is thus essential that whenever you type
5903 an `ATOM`, `READ` should respond with the unique identifier you wish
5904 to designate. The problem is that it is unreasonable to expect the
5905 `PNAME`s of all `ATOM`s to be unique. When you use an `ATOM` `A` in a
5906 program, do you mean the `A` you typed two minutes ago, the `A` you
5907 used in another one of your programs, or the `A` used by some library
5908 program?
5909
5910 Dynamic blocking (pushing down of `LVAL`s) solves many such problems.
5911 However, there are some which it does not solve -- such as state
5912 variables (whether they are impure or pure). Major problems with a
5913 system having only dynamic blocking usually arise only when attempts
5914 are made to share large numbers of significant programs among many
5915 people.
5916
5917 The solution used in Muddle is basically as follows: `READ` must
5918 maintain at least one table of `ATOM`s to guarantee any uniqueness.
5919 So, Muddle allows many such tables and makes it easy for the user to
5920 specify which one is wanted. Such a table is an object of `TYPE`
5921 `OBLIST` ("object list"). All the complication which follows arises
5922 out of a desire to provide a powerful, easily used method of working
5923 with `OBLIST`s, with reasonable values used by default.
5924
5925 15.2. OBLISTs
5926 -------------
5927
5928 An `OBLIST` is of `PRIMTYPE` `UVECTOR` with `UTYPE` `LIST`; the `LIST`
5929 holds `ATOM`s. The `ATOM`s are ordered by a hash coding on their
5930 `PNAME`s: each `LIST` is a hashing bucket.) What follows is
5931 information about `OBLIST`s as such.
5932
5933 ### 15.2.1. OBLIST Names
5934
5935 Every normally constituted `OBLIST` has a name. The name of an
5936 `OBLIST` is an `ATOM` associated with the `OBLIST` under the indicator
5937 `OBLIST`. Thus,
5938
5939     <GETPROP oblist OBLIST>
5940
5941 or
5942
5943     <GET oblist OBLIST>
5944
5945 returns the name of *oblist*.
5946
5947 Similarly, every name of an `OBLIST` is associated with its `OBLIST`,
5948 again under the indicator `OBLIST`, so that
5949
5950     <GETPROP oblist-name:atom OBLIST>
5951
5952 or
5953
5954     <GET oblist-name:atom OBLIST>
5955
5956 returns the `OBLIST` whose name is *oblist-name*.
5957
5958 Since there is nothing special about the association of `OBLIST`s and
5959 their names, the name of an `OBLIST` can be changed by the use of
5960 `PUTPROP`, both on the `OBLIST` and its name. It is not wise to change
5961 the `OBLIST` association without changing the name association, since
5962 you are likely to confuse `READ` and `PRINT` terribly.
5963
5964 You can also use `PUT` or `PUTPROP` to remove the association between
5965 an `OBLIST` and its name completely. If you want the `OBLIST` to go
5966 away (be garbage collected), **and** you want to keep its name around,
5967 this must be done: otherwise the association will force it to stay,
5968 even if there are no other references to it. (If you have no
5969 references to either the name or the `OBLIST` (an `ATOM` -- including
5970 a `TYPE` name -- points to its `OBLIST`), both of them -- and their
5971 association -- will go away without your having to remove the
5972 association, of course.) It is not recommended that you remove the
5973 name of an `OBLIST` without having it go away, since then `ATOM`s in
5974 that `OBLIST` will `PRINT` the name as if they were in no `OBLIST` --
5975 which is defeating the purpose of this whole exercise.
5976
5977 ### 15.2.2. MOBLIST
5978
5979     <MOBLIST atom fix>
5980
5981 ("make oblist") creates and returns a new `OBLIST`, containing no
5982 `ATOM`s, whose name is *atom*, unless there already exists an `OBLIST`
5983 of that name, in which case it returns the existing `OBLIST`. *fix* is
5984 the size of the `OBLIST` created -- the number of hashing buckets.
5985 *fix* is optional (ignored if the `OBLIST` already exists), 13 by
5986 default. If specified, *fix* should be a prime number, since that
5987 allows the hashing to work better.
5988
5989 ### 15.2.3. OBLIST?
5990
5991     <OBLIST? atom>
5992
5993 returns `#FALSE ()` if *atom* is not in any `OBLIST`. If *atom* is in
5994 an `OBLIST`, it returns that `OBLIST`.
5995
5996 15.3. READ and OBLISTs
5997 ----------------------
5998
5999 `READ` can be explicitly told to look up an `ATOM` in a particular
6000 `OBLIST` by giving the `ATOM` a **trailer**. A trailer consists of the
6001 characters `!-` (exclamation-point dash) following the `ATOM`,
6002 immediately followed by the name of the `OBLIST`. For example,
6003
6004     A!-OB
6005
6006 specifies the unique `ATOM` of `PNAME` `A` which is in the `OBLIST`
6007 whose name is the `ATOM` `OB`.
6008
6009 Note that the name of the `OBLIST` must follow the `!-` with **no**
6010 separators (like space, tab, carriage-return, etc.). There is a name
6011 used by default (section 15.5) which types out and is typed in as
6012 `!-`*separator*.
6013
6014 Trailers can be used recursively:
6015
6016     B!-A!-OB
6017
6018 specified the unique `ATOM` of `PNAME` `B` which is in the `OBLIST`
6019 whose name is the unique `ATOM` of `PNAME` `A` which is in the
6020 `OBLIST` whose name is `OB`. (Whew!) The repetition is terminated by
6021 the look-up and insertion described below.
6022
6023 If an `ATOM` with a given `PNAME` is not found in the `OBLIST`
6024 specified by a trailer, a new `ATOM` with that `PNAME` is created and
6025 inserted into that `OBLIST`.
6026
6027 If an `OBLIST` whose name is given in a trailer does not exist, `READ`
6028 creates one, of length 13 buckets.
6029
6030 If trailer notation is not used (the "normal" case), and for an `ATOM`
6031 that terminates a trailer, `READ` looks up the `PNAME` of the `ATOM`
6032 in a `LIST` of `OBLIST`s, the `LVAL` of the `ATOM` `OBLIST` by
6033 default. This look-up starts with `<1 .OBLIST>` and continues until
6034 `.OBLIST` is exhausted. If the `ATOM` is not found. `READ` usually
6035 inserts it into `<1 .OBLIST>`. (It is possible to force `READ` to use
6036 a different element of the `LIST` of `OBLIST`s for new insertions. If
6037 the `ATOM` `DEFAULT` is in that `LIST`, the `OBLIST` following that
6038 `ATOM` will be used.)
6039
6040 15.4. PRIN1 and OBLISTs
6041 -----------------------
6042
6043 When `PRINT` is given an `ATOM` to output, it outputs as little of the
6044 trailer as is necessary to specify the `ATOM` uniquely to `READ`. That
6045 is, if the `ATOM` is the **first** `ATOM` of that `PNAME` which `READ`
6046 would find in its normal look-up in the current `.OBLIST`, no trailer
6047 is output. Otherwise, `!-` is output and the name of the `OBLIST` is
6048 recursively `PRIN1`ed.
6049
6050 Warning: there are obscure cases, which do not occur in normal
6051 practice, for which the `PRINT` trailer does not terminate. For
6052 instance, if an `ATOM` must have a trailer printed, and the name of
6053 the `OBLIST` is an `ATOM` in that very same `OBLIST`, death. Any
6054 similar case will also give `PRINT` a hernia.
6055
6056 15.5. Initial State
6057 -------------------
6058
6059 In an initial Muddle, `.OBLIST` contains two `OBLIST`s. `<1 .OBLIST>`
6060 initially contains no `ATOM`s, and `<2 .OBLIST>` contains all the
6061 `ATOM`s whose `GVAL` are `SUBR`s or `FSUBR`s, as well as `OBLIST`,
6062 `DEFAULT`, `T`, etc. It is difficult to lose track of the latter; the
6063 specific trailer `!-`*separator* will **always** cause references to
6064 that `OBLIST`. In addition, the `SUBR` `ROOT`, which takes no
6065 arguments, always returns that `OBLIST`.
6066
6067 The name of `<ROOT>` is `ROOT`; this `ATOM` is in `<ROOT>` and would
6068 cause infinite recursion were it not for the use of `!-`*separator*.
6069 The name of the initial `<1 .OBLIST>` is `INITIAL` (really
6070 `INITIAL!-`).
6071
6072 The `ATOM` `OBLIST` also has a `GVAL`. `,OBLIST` is initially the same
6073 as `.OBLIST`; however, `,OBLIST` is not affected by the `SUBR`s used
6074 to manipulate the `OBLIST` structure. It is instead used only when
6075 errors occur.
6076
6077 In the case of an error, the current `.OBLIST` is checked to see if it
6078 is "reasonable" -- that is, contains nothing of the wrong `TYPE`. (It
6079 is reasonable, but not standard, for `.OBLIST` to be a single `OBLIST`
6080 instead of a `LIST` of them.) If it is reasonable, that value stays
6081 current. Otherwise, `OBLIST` is `SET` to `,OBLIST`. Note that changes
6082 made to the `OBLIST`s on `,OBLIST` -- for example, new `ATOM`s added
6083 -- remain. If even `,OBLIST` is unreasonable, `OBLIST` is `SET` and
6084 `SETG`ed to its initial value. `<ERRET>` (section 16.4) always assumes
6085 that `.OBLIST` is unreasonable.
6086
6087 Three other `OBLIST`s exist in a virgin Muddle: their names and
6088 purposes are as follows:
6089
6090 `ERRORS!-` contains `ATOM`s whose `PNAME`s are used as error messages.
6091 It is returned by `<ERRORS>`.
6092
6093 `INTERRUPTS!-` is used by the interrupt system (section 21.5.1). It is
6094 returned by `<INTERRUPTS>`.
6095
6096 `MUDDLE!-` is used infrequently by the interpreter when loading
6097 compiled programs to fix up references to locations within the
6098 interpreter.
6099
6100 The pre-loading of compiled programs may create other `OBLIST`s in an
6101 initialized Muddle (Lebling, 1979).
6102
6103 15.6. BLOCK and ENDBLOCK
6104 ------------------------
6105
6106 These `SUBR`s are analogous to **begin** and **end** in Algol, etc.,
6107 in the way they manipulate static blocking (and in **no** other way.)
6108
6109     <BLOCK look-up:list-of-oblists>
6110
6111 returns its argument after "pushing" the current `LVAL` of the `ATOM`
6112 `OBLIST` and making its argument the current `LVAL`. You usually want
6113 `<ROOT>` to be an element of *look-up*, normally its last.
6114
6115     <ENDBLOCK>
6116
6117 "pops" the LVAL of the `ATOM` `OBLIST` and returns the resultant
6118 `LIST` of `OBLIST`s.
6119
6120 Note that this "pushing" and "popping" of `.OBLIST` is entirely
6121 independent of functional application, binding, etc.
6122
6123 15.7. SUBRs Associated with Lexical Blocking
6124 --------------------------------------------
6125
6126 ### 15.7.1. READ (again)
6127
6128     <READ channel eof-routine look-up>
6129
6130 This is a fuller call to `READ`. *look-up* is an `OBLIST` or a `LIST`
6131 of them, used as stated in section 15.3 to look up `ATOM`s and insert
6132 them in `OBLIST`s. If not specified, `.OBLIST` is used. See also
6133 section 11.1.1.1, 11.3, and 17.1.3 for other arguments.
6134
6135 ### 15.7.2. PARSE and LPARSE (again)
6136
6137     <PARSE string radix:fix look-up>
6138
6139 as was previously mentioned, applies `READ`'s algorithm to *string*
6140 and returns the first Muddle object resulting. This **includes**
6141 looking up prospective `ATOM`s on *look-up*, if given, or `.OBLIST`.
6142 `LPARSE` can be called in the same way. See also section 7.6.6.2 and
6143 17.1.3 for other arguments.
6144
6145 ### 15.7.3. LOOKUP
6146
6147     <LOOKUP string oblist>
6148
6149 returns the `ATOM` of `PNAME` *string* in the `OBLIST` *oblist*, if
6150 there is such an `ATOM`; otherwise, it returns `#FALSE ()`. If
6151 *string* would `PARSE` into an `ATOM` anyway, `LOOKUP` is faster,
6152 although it looks in only one `OBLIST` instead of a `LIST` of them.
6153
6154 ### 15.7.4. ATOM
6155
6156     <ATOM string>
6157
6158 creates and returns a spanking new `ATOM` of `PNAME` *string* which is
6159 guaranteed not to be on **any** `OBLIST`.
6160
6161 An `ATOM` which is not on any `OBLIST` is `PRINT`ed with a trailer of
6162 `!-#FALSE ()`.
6163
6164 ### 15.7.5. REMOVE
6165
6166     <REMOVE string oblist>
6167
6168 removes the `ATOM` of `PNAME` *string* from *oblist* and returns that
6169 ATOM. If there is no such `ATOM`, `REMOVE` returns `#FALSE ()`. Also,
6170
6171     <REMOVE atom>
6172
6173 removes *atom* from its `OBLIST`, if it is on one. It returns *atom*
6174 if it was on an `OBLIST`; otherwise it returns `#FALSE ()`.
6175
6176 ### 15.7.6 INSERT
6177
6178     <INSERT string-or-atom oblist>
6179
6180 creates an `ATOM` of `PNAME` *string*, inserts it into *oblist* and
6181 returns it. If there is already an `ATOM` with the same `PNAME` as
6182 *atom* in *oblist*, an error occurs. The standard way to avoid the
6183 error and always get your *atom* is
6184
6185     <OR <LOOKUP string oblist> <INSERT string oblist>>
6186
6187 As with `REMOVE`, `INSERT` can also take an `ATOM` as its first
6188 argument; this `ATOM` must not be on any `OBLIST` -- it must have been
6189 `REMOVE`d, or just created by `ATOM` -- else an error occurs. The
6190 `OBLIST` argument is **never** optional. If you would like the new
6191 `ATOM` to live in the `OBLIST` that `READ` would have chosen, you can
6192 `<PARSE string>` instead.
6193
6194 ### 15.7.7. PNAME
6195
6196     <PNAME atom>
6197
6198 returns a `STRING` (newly created) which is *atom*'s `PNAME` ("printed
6199 name"). If trailers are not needed, `PNAME` is much faster than
6200 `UNPARSE` on *atom*. (In fact, `UNPARSE` has to go all the way through
6201 the `PRINT` algorithm **twice**, the first time to see how long a
6202 `STRING` is needed.)
6203
6204 ### 15.7.8. SPNAME
6205
6206 `SPNAME` ("shared printed name") is identical to `PNAME`, except that
6207 the `STRING` it returns shares storage with *atom* (appendix 1), which
6208 is more efficient if the `STRING` will not be modified. `PUT`ting into
6209 such a `STRING` will cause an error.
6210
6211 15.8. Example: Another Solution to the INC Problem
6212 --------------------------------------------------
6213
6214 What follows is an example of the way `OBLIST`s are "normally" used to
6215 provide "externally available" `ATOM`s and "local" `ATOM`s which are
6216 not so readily available externally. Lebling (1979) describes a
6217 systematic way to accomplish the same thing and more.
6218
6219     <MOBLIST INCO 1>
6220             ;"Create an OBLIST to hold your external symbols.
6221             Its name is INCO!-INITIAL!- ."
6222
6223     INC!-INCO
6224             ;"Put your external symbols into that OBLIST.
6225         If you have many, just write them successively."
6226
6227     <BLOCK (<MOBLIST INCI!-INCO 1> <GET INCO OBLIST> <ROOT>)>
6228         ;"Create a local OBLIST, naming it INCI!-INCO, and set up
6229         .OBLIST for reading in your program. The OBLIST INCO is
6230         included in the BLOCK so that as your external symbols are
6231         used, they will be found in the right place. Note that the
6232         ATOM INCO is not in any OBLIST of the BLOCK; therefore,
6233         trailer notation of !-INCO will not work within the current
6234         BLOCK-ENDBLOCK pair."
6235
6236     <DEFINE INC ;"INC is found in the INCO OBLIST."
6237         (A) ;"A is not found and is therefore put into INCI by
6238     READ."
6239         #DECL ((VALUE A) <OR FIX FLOAT>)
6240         <SET .A <+ ..A 1>>> ;"All other ATOMs are found in the
6241     ROOT."
6242     <ENDBLOCK>
6243
6244 This example is rather trivial, but it contains all of the issues, of
6245 which there are three.
6246
6247 The first idea is that you should create two `OBLIST`s, one to hold
6248 `ATOM`s which are to be known to other users (`INCO`), and the other
6249 to hold internal `ATOM`s which are not normally of interest to other
6250 (`INCI`). The case above has one `ATOM` in each category.
6251
6252 Second, `INCO` is explicitly used **without** trailers so that
6253 surrounding `BLOCK` and `ENDBLOCK`s will have an effect on it. Thus
6254 `INCO` will be in the `OBLIST` desired by the user; `INC` will be in
6255 `INCO`, and the user can refer to it by saying `INC!-INCO`; `INCI`
6256 will also be in `INCO`, and can be referred to in the same way;
6257 finally, `A` is really `A!-INCI!-INCO`. The point of all this is to
6258 structure the nesting of `OBLIST`s.
6259
6260 Finally, if for some reason (like saving storage space) you wish to
6261 throw `INCI` away, you can follow the `ENDBLOCK` with
6262
6263     <REMOVE "INCI" <GET INCO OBLIST>>
6264
6265 and thus remove all references to it. The ability to do such pruning
6266 is one reason for structuring `OBLIST` references.
6267
6268 Note that, even after removing `INCI`, you can "get `A` back" -- that
6269 is, be able to type it in -- by saying something of the form
6270
6271     <INSERT <1 <1 ,INC!-INCO>> <1 .OBLIST>>
6272
6273 thereby grabbing `A` out of the structure of `INC` and re-inserting it
6274 into an `OBLIST`. however, this resurrects the name collision caused
6275 by `<INC!-INCO A>`.
6276
6277 Chapter 16. Errors, Frames, etc.
6278 ================================
6279
6280 16.1. LISTEN
6281 ------------
6282
6283 This `SUBR` takes any number of arguments. It first checks the `LVAL`s
6284 of `INCHAN`, `OUTCHAN`, and `OBLIST` for reasonability and terminal
6285 usability. In each case, if the value is unreasonable, the `ATOM` is
6286 rebound to the corresponding `GVAL`, if reasonable, or to an invented
6287 reasonable value. `LISTEN` then does `<TTYECHO .INCHAN T>` and
6288 `<ECHOPAIR .INCHAN .OUTCHAN>`. Next, it `PRINT`s its arguments, then
6289 `PRINT`s
6290
6291     LISTENING-AT-LEVEL i PROCESS p
6292
6293 where *i* is an integer (`FIX`) which is incremented each time
6294 `LISTEN` is called recursively, and *p* is an integer identifying the
6295 `PROCESS` (chapter 20) in which the `LISTEN` was `EVAL`ed. `LISTEN`
6296 then does `<APPLY <VALUE REP>>`, if there is one, and if it is
6297 `APPLICABLE`. If not, it applies the `SUBR` `REP` (without making a
6298 new `FRAME` -- see below). This `SUBR` drops into an infinite
6299 `READ`-`EVAL`-`PRINT` loop, which can be left via `ERRET` (section
6300 16.4).
6301
6302 The standard `LISTEN` loop has two features for getting a handle on
6303 objects that you have typed in and Muddle has typed out. If the `ATOM`
6304 `L-INS` has a local value that is a `LIST`, `LISTEN` will keep recent
6305 inputs (what `READ` returns) in it, most recent first. Similarly, if
6306 the `ATOM` `L-OUTS` has a local value that is a `LIST`, `LISTEN` will
6307 keep recent outputs (what `EVAL` returns) in it, most recent first.
6308 The keeping is done before the `PRINT`ing, so that `^S` does not
6309 defeat its purpose. The user can decide how much to keep around by
6310 setting the length of each `LIST`. Even if `L-OUTS` is not used, the
6311 atom `LAST-OUT` is always `SET` to the last object returned by `EVAL`
6312 in the standard `LISTEN` loop. Example:
6313
6314     <SET L-INS (NEWEST NEWER NEW)>$
6315     (NEWEST NEWER NEW)
6316     .L-INS$
6317     (.L-INS NEWEST NEWER)
6318     <SET FOO 69>$
6319     69
6320     <SET FIXIT <2 .LINS>>   ;"grab the last input"$
6321     <SET FOO 69>
6322     .L-INS$
6323     (.L-INS <SET FIXIT <2 .L-INS>> <SET FOO 69>)
6324     <PUT .FIXIT 3 105>$
6325     <SET FOO 105>
6326     <EVAL .FIXIT>$
6327     105
6328     .L-INS$
6329     (.L-INS <EVAL .FIXIT> <PUT .FIXIT 3 105>)
6330     .FOO$
6331     105
6332
6333 16.2. ERROR
6334 -----------
6335
6336 This `SUBR` is the same as `LISTEN`, except that (1) it generates an
6337 interrupt (chapter 21), if enabled. and (2) it `PRINT`s `*ERROR*`
6338 before `PRINT`ing its arguments.
6339
6340 When any `SUBR` or `FSUBR` detects an anomalous condition (for
6341 example, its arguments are of the wrong `TYPE`), it calls `ERROR` with
6342 at least two arguments, including:
6343
6344 1.  an `ATOM` whose `PNAME` describes the problem, normally from the
6345     `OBLIST` `ERRORS!-` (appendix 4),
6346 2.  the `ATOM` that names the `SUBR` or `FSUBR`, and
6347 3.  any other information of interest, and **then returns whatever the
6348     call to `ERROR` returns**. Exception: a few (for example `DEFINE`)
6349     will take further action that depends on the value returned. This
6350     nonstandard action is specified in the error message (first
6351     `ERROR` argument).
6352
6353 16.3. FRAME (the TYPE)
6354
6355 A `FRAME` is the object placed on a `PROCESS`'s control stack (chapter
6356 20) whenever a `SUBR`, `FSUBR`, `RSUBR`, or `RSUBR-ENTRY` (chapter 19)
6357 is applied. (These objects are herein collectively called
6358 "Subroutines".) It contains information describing what was applied,
6359 plus a `TUPLE` whose elements are the arguments to the Subroutine
6360 applied. If any of the Subroutine's arguments are to be evaluated,
6361 they will have been by the time the `FRAME` is generated.
6362
6363 A `FRAME` is an anomalous `TYPE` in the following ways:
6364
6365 1.  It cannot be typed in. It can be generated only by applying a
6366     Subroutine.
6367 2.  It does not type out in any standard format, but rather as
6368     `#FRAME` followed by the `PNAME`of the Subroutine applied.
6369
6370 16.3.1. ARGS
6371
6372     <ARGS frame>
6373
6374 ("arguments") returns the argument `TUPLE` of *frame*.
6375
6376 16.3.2. FUNCT
6377
6378     <FUNCT frame>
6379
6380 ("function"} returns the `ATOM` whose `G/LVAL` is being applied in
6381 *frame*.
6382
6383 16.3.3. FRAME (the SUBR)
6384
6385     <FRAME frame>
6386
6387 returns the `FRAME` stacked **before** *frame* or, if there is none,
6388 it will generate an error. The oldest (lowest) `FRAME` that can be
6389 returned without error has a `FUNCT` of `TOPLEVEL`. If called with no
6390 arguments, `FRAME` returns the topmost `FRAME` used in an application
6391 of `ERROR` or `LISTEN`, which was bound by the interpreter to the
6392 `ATOM` `LERR\ I-INTERRUPTS` ("last error").
6393
6394 16.3.4. Examples
6395
6396 Say you have gotten an error. You can now type at `ERROR`'s `LISTEN`
6397 loop and get things `EVAL`ed. For example,
6398
6399     <FUNCT <FRAME>>$
6400     ERROR
6401     <FUNCT <FRAME <FRAME>>>$
6402     the-name-of-the-Subroutine-which-called-ERROR:atom
6403     <ARGS <FRAME <FRAME>>>$
6404     the-arguments-to-the-Subroutine-which-called-ERROR:tuple
6405
6406 16.4. ERRET
6407
6408     <ERRET any frame>
6409
6410 This `SUBR` ("error return") (1) causes the control stack to be
6411 stripped down to the level of *frame*, and (2) **then** returns *any*.
6412 The net result is that the application which generated *frame* is
6413 forced to return *any*. Additional side effects that would have
6414 happened in the absence of an error may not have happened.
6415
6416 The second argument to `ERRET` is optional, by default the `FRAME` of
6417 the last invocation of `ERROR` or `LISTEN`.
6418
6419 If `ERRET` is called with **no** arguments, it drops you **all** the
6420 way down to the **bottom** of the control stack -- **before** the
6421 level-1 `LISTEN` loop -- and then calls `LISTEN`. As always, `LISTEN`
6422 first ensures that Muddle is receptive.
6423
6424 Examples:
6425
6426     <* 3 <+ a 1>>$
6427     *ERROR*
6428     ARG-WRONG-TYPE
6429     +
6430     LISTENING-AT-LEVEL 2 PROCESS 1
6431     <ARGS <FRAME <FRAME>>>$
6432     [a 1]
6433     <ERRET 5>$  ;"This causes the + to return 5."
6434     15      ;"finally returned by the *"
6435
6436 Note that when you are in a call to `ERROR`, the most recent set of
6437 bindings is still in effect. This means that you can examine values of
6438 dummy variables while still in the error state. For example,
6439
6440     <DEFINE F (A "AUX" (B "a string"))
6441         #DECL ((VALUE) LIST (A) STRUCTURED (B) STRING)
6442         (.B <REST .A 2>)    ;"Return this LIST.">$
6443     F
6444     <F '(1)>$
6445
6446     *ERROR*
6447     OUT-OF-BOUNDS
6448     REST
6449     LISTENING-AT-LEVEL 2 PROCESS 1
6450     .A$
6451     (1)
6452     .B$
6453     "a string"
6454     <ERRET '(5)>    ; "Make the REST return (5)."$
6455     ("a string" (5))
6456
6457 16.5. RETRY
6458
6459     <RETRY frame>
6460
6461 causes the control stack to be stripped down just beyond *frame*, and
6462 then causes the Subroutine call that generated *frame* to be done
6463 again. *frame* is optional, by default the `FRAME` of the last
6464 invocation of `ERROR` or `LISTEN`. `RETRY` differs from `AGAIN` in
6465 that (1) it is not intended to be used in programs; (2) it can retry
6466 any old *frame* (any Subroutine call), whereas `AGAIN` requires an
6467 `ACTIVATION` (`PROG` or `REPEAT` or `"ACT"`); and (3) if it retries
6468 the `EVAL` of a `FORM` that makes an `ACTIVATION`, it will cause
6469 rebinding in the argument `LIST`, thus duplicating side effects.
6470
6471 16.6. UNWIND
6472
6473 `UNWIND` is an `FSUBR` that takes two arguments, usually `FORM`s. It
6474 `EVAL`s the first one, and, if the `EVAL` returns normally, the value
6475 of the `EVAL` call is the value of `UNWIND`. If, however, during the
6476 `EVAL` a non-local return attempts to return below the `UNWIND`
6477 `FRAME` in the control stack, the second argument is `EVAL`ed, its
6478 value is ignored, and the non-local return is completed. The second
6479 argument is evaluated in the environment that was present when the
6480 call to `UNWIND` was made. This facility is useful for cleaning up
6481 data bases that are in inconsistent states and for closing temporary
6482 `CHANNEL`s that may be left around. `FLOAD` sets up an `UNWIND` to
6483 close its `CHANNEL` if the user attempts to `ERRET` without finishing
6484 the `FLOAD`. Example:
6485
6486     <DEFINE CLEAN ACT ("AUX" (C <OPEN "READ" "A FILE">))
6487         #DECL ((C) <OR CHANNEL FALSE> ...)
6488         <COND (.C
6489             <UNWIND <PROG () ... <CLOSE .C>>
6490                 <CLOSE .C>>)>>
6491
6492 16.7. Control-G (\^G)
6493
6494 Typing control-G (`^G`, `<ASCII 7>`) at Muddle causes it to act just
6495 as if an error had occurred in whatever was currently being done. You
6496 can then examine the values of variables as above, continue by
6497 applying `ERRET` to one argument (which is ignored), `RETRY` a `FRAME`
6498 lower on the control stack, or flush everything by applying `ERRET` to
6499 no arguments.
6500
6501 16.8. Control-S (\^S)
6502
6503 Typing control-S (`^S`, `<ASCII 19>`) at Muddle causes it to stop what
6504 is happening and return to the `FRAME` `.LERR\ !-INTERRUPTS`,
6505 returning the `ATOM` `T`. (In the Tenex and Tops-20 versions, `^O`
6506 also has the same effect.)
6507
6508 16.9. OVERFLOW
6509
6510     <OVERFLOW false-or-any>
6511
6512 There is one error that can be disabled: numeric overflow and
6513 underflow caused by the arithmetic `SUBR`s (`+`, `-`, `*`, `/`). The
6514 `SUBR` `OVERFLOW` takes one argument: if it is of `TYPE` `FALSE`,
6515 under/overflow errors are disabled; otherwise they are enabled. The
6516 initial state is enabled. `OVERFLOW` returns `T` or `#FALSE ()`,
6517 reflecting the previous state. Calling it with no argument returns the
6518 current state.
6519
6520 Chapter 17. Macro-operations
6521 ============================
6522
6523 17.1. READ Macros
6524 -----------------
6525
6526 ### 17.1.1. % and %%
6527
6528 The tokens `%` and `%%` are interpreted by `READ` in such a way as to
6529 give a "macro" capability to Muddle similar to PL/I's.
6530
6531 Whenever `READ` encounters a single `%` -- anywhere, at any depth of
6532 recursion -- it **immediately**, without looking at the rest of the
6533 input, evaluates the object following the `%`. The result of that
6534 evaluation is used by `READ` in place of the object following the `%`.
6535 That is, `%` means "don't really `READ` this, use `EVAL` of it
6536 instead." `%` is often used in files in front of calls to `ASCII`,
6537 `BITS` (which see), etc., although when the `FUNCTION` is compiled the
6538 compiler will do the evaluation if the arguments are constant. Also
6539 seen is `%.INCHAN`, read as the `CHANNEL` in use during `LOAD` or
6540 `FLOAD`; for example, `<PUT %.INCHAN 18 8>` causes succeeding `FIX`es
6541 to be read as octal.
6542
6543 Whenever `READ` encounters `%%`, it likewise immediately evaluates the
6544 object following the `%%`. However, it completely ignores the result
6545 of that evaluation. Side effects of that evaluation remain, of course.
6546
6547 Example:
6548
6549     <DEFINE SETUP () <SET A 0>>$
6550     SETUP
6551     <DEFINE NXT () <SET A <+ .A 1>>>$
6552     NXT
6553     [%%<SETUP> %<NXT> %<NXT> (%%<SETUP>) %<NXT>]$
6554     [1 2 () 1]
6555
6556 ### 17.1.2. LINK
6557
6558     <LINK exp:any string oblist>
6559
6560 creates an object of `TYPE` `LINK`, `PRIMTYPE` `ATOM`. A `LINK` looks
6561 vaguely like an `ATOM`; it has a `PNAME` (the *string* argument),
6562 resides in an `OBLIST` (the *oblist* argument) and has a "value" (the
6563 *exp* argument). A `LINK` has the strange property that, whenever it
6564 is encountered by `READ` (that is, its `PNAME` is read, just like an
6565 `ATOM`, possibly with `OBLIST` trailers), `READ` substitutes the
6566 `LINK`'s "value" for the `LINK` immediately. The effect of `READ`ing a
6567 `LINK`'s `PNAME` is exactly the same as the effect of reading its
6568 "value".
6569
6570 The *oblist* argument is optional, `<1 .OBLIST>` by default. `LINK`
6571 returns its first argument. The `LINK` is created via `INSERT`, so an
6572 error results if there is already an `ATOM` or `LINK` in *oblist* with
6573 the same `PNAME`.
6574
6575 The primary use of `LINK`s is in interactive work with Muddle:
6576 expressions which are commonly used, but annoyingly long to type, can
6577 be "linked" to `PNAME`s which are shorter. The standard example is the
6578 following:
6579
6580     <LINK '<ERRET> "^E" <ROOT>>
6581
6582 which links the `ATOM` of `PNAME` `^E` in the `ROOT` `OBLIST` to the
6583 expression `<ERRET>`.
6584
6585 ### 17.1.3. Program-defined Macro-characters
6586
6587 During `READ`ing from an input `CHANNEL` or `PARSE`ing a `STRING`, any
6588 character can be made to have a special meaning. A character can cause
6589 an arbitrary routine to be invoked, which can then return any number
6590 of elements to be put into the object being built by `READ`, `PARSE`,
6591 or `LPARSE`. Translation of characters is also possible. This facility
6592 was designed for those persons who want to use Muddle `READ` to do
6593 large parts of their input but have to modify its actions for some
6594 areas: for example, one might want to treat left and right parentheses
6595 as tokens, rather than as delimiters indicating a `LIST`.
6596
6597 #### 17.1.3.1. READ (finally)
6598
6599 Associated with `READ` is an `ATOM`, `READ-TABLE!-`, whose local
6600 value, if any, must be a `VECTOR` of elements, one for each character
6601 up to and including all characters to be treated specially. Each
6602 element indicates, if not `0`, the action to be taken upon `READ`'s
6603 encounter with that character. A similar `VECTOR`, the local value of
6604 `PARSE-TABLE!-`, if any, is used to find the action to take for
6605 characters encountered when `PARSE` or `LPARSE` is applied to a
6606 `STRING`.
6607
6608 These tables can have up to 256 elements, one for each ASCII character
6609 and one for each possible exclamation-point/ASCII-character pair. In
6610 Muddle, the exclamation-point is used as a method of expanding the
6611 ASCII character set, and an exclamation-point/character pair is
6612 treated as one logical character when not reading a `STRING`.
6613
6614 The element corresponding to a character is
6615 `<NTH table <+ 1 <ASCII char>>>`. The element corresponding to an
6616 exclamation-point/ASCII-character pair is
6617 `<NTH table <+ 129 <ASCII char>>>`. The table can be shorter than 256
6618 elements, in which case it is treated as if it were 256 long with `0`
6619 elements beyond its actual length.
6620
6621 An element of the tables must satisfy one of the following `DECL`
6622 Patterns:
6623
6624 > `'0` indicates that no special action is to be taken when this
6625 > character is encountered.
6626 >
6627 > `CHARACTER` indicates that the encountered character is to be
6628 > translated into the given `CHARACTER` whenever it appears, except
6629 > when as an object of `TYPE` `CHARACTER`, or in a `STRING`, or
6630 > immediately following a `\`.
6631 >
6632 > `FIX` indicates that the character is to be given the same treatment
6633 > as the character with the ASCII value of the `FIX`. This allows you
6634 > to cause other characters to be treated in the same way as A-Z for
6635 > example. The same exceptions apply as for a `CHARACTER`.
6636 >
6637 > `<LIST FIX>` indicates the same thing, except that the character
6638 > does not by itself cause a break. Therefore, if it occurs when
6639 > reading an `ATOM` or number, it will be treated as part of that
6640 > `ATOM` or number.
6641 >
6642 > `APPLICABLE` (to one argument) indicates that the character is to be
6643 > a break character. Whenever it is encountered, the reading of the
6644 > current object is finished, and the corresponding element of the
6645 > table is `APPLY`ed to the ASCII `CHARACTER`. (If `READ` is called
6646 > during the application, the end-of-file slot of the `CHANNEL`
6647 > temporarily contains a special kind of `ACTIVATION` (`TYPE` `READA`)
6648 > so that end-of-file can be signalled properly to the original
6649 > `READ`. Isn't that wonderful?) The value returned is taken to be
6650 > what was read, unless an object of `TYPE` `SPLICE` is returned. If
6651 > so, the elements of this object, which is of `PRIMTYPE` `LIST`, are
6652 > spliced in at the point where Muddle is reading. An empty `SPLICE`
6653 > allows one to return nothing. If a structured object is not being
6654 > built, and a `SPLICE` is returned, elements after the first will be
6655 > ignored. A `SPLICE` says "expand me", whereas the structure
6656 > containing a `SEGMENT` says "I will expand you".
6657 >
6658 > `<LIST APPLICABLE>` indicates the same thing, except that the
6659 > character does not by itself cause a break. Therefore, if it occurs
6660 > when reading an `ATOM` or number, it will be treated as part of that
6661 > `ATOM` or number.
6662
6663 `READ` takes an additional optional argument, which is what to use
6664 instead of the local value of the `ATOM` `READ-TABLE` as the `VECTOR`
6665 of read-macro characters. If this argument is supplied, `READ-TABLE`
6666 is rebound to it within the call to `READ`. `READ` takes from zero to
6667 four arguments. The fullest call to `READ` is thus:
6668
6669     <READ channel eof-routine look-up read-table:vector>
6670
6671 The other arguments are explained in sections 11.1.1.1, 11.3, and
6672 15.7.1.
6673
6674 `ERROR` and `LISTEN` rebind `READ-TABLE` to the `GVAL` of
6675 `READ-TABLE`, if any, else `UNASSIGN` it.
6676
6677 #### 17.1.3.2. Examples
6678
6679 Examples of each of the different kinds of entries in macro tables:
6680
6681     <SET READ-TABLE <IVECTOR 256 0>>$
6682     [...]
6683
6684     <PUT .READ-TABLE <+ 1 <ASCII !\a>> !\A>
6685                     ;"CHARACTER: translate a to A."$
6686     [...]
6687     abc$
6688     Abc
6689
6690     <PUT .READ-TABLE <+ 1 <ASCII !\%>> <ASCII !\A>>
6691             ;"FIX: make % just a normal ASCII character."$
6692     [...]
6693     A%BC$
6694     A\%BC
6695
6696     <PUT .READ-TABLE <+ 1 <ASCII !\.>> (<ASCII !\.>)>
6697             ;"<LIST FIX>: make comma no longer a break
6698               character, but still special if at a break."$
6699     [...]
6700     A,B$
6701     A\,B
6702     ;"That was an ATOM with PNAME A,B ."
6703     ',B$
6704     ,B
6705     ;"That was the FORM <GVAL B> ."
6706
6707     <PUT .READ-TABLE <+ 1 <ASCII !\:>>
6708         #FUNCTION ((X) <LIST COLON <READ>>)>
6709             ;"APPLICABLE: make a new thing like ( < and [ ."$
6710     [...]
6711     B:A$
6712     B
6713     (COLON A)
6714     :::FOO$
6715     (COLON (COLON (COLON FOO)))
6716
6717     <PUT .READ-TABLE <+ 1 <ASCII !\:>>
6718         '(#FUNCTION ((X) <LIST COLON <READ>>))>
6719             ;"<LIST APPLICABLE>: like above, but not a break
6720               now."$
6721     [...]
6722     B:A$
6723     B:A
6724     ;"That was an ATOM."
6725     :::FOO$
6726     (COLON (COLON (COLON FOO)))
6727
6728 #### 17.1.3.3. PARSE and LPARSE (finally)
6729
6730     <PARSE string radix look-up parse-table:vector look-ahead:character>
6731
6732 is the fullest call to `PARSE`. `PARSE` can take from zero to five
6733 arguments. If `PARSE` is given no arguments, it returns the first
6734 object parsed from the local value of the `STRING` `PARSE-STRING` and
6735 additionally `SET`s `PARSE-STRING` to the `STRING` having those
6736 `CHARACTER`s which were parsed `REST`ed off. If `PARSE` is given a
6737 `STRING` to parse, the `ATOM` `PARSE-STRING` is rebound to the
6738 `STRING` within that call. If the *parse-table* argument is given to
6739 `PARSE`, `PARSE-TABLE` is rebound to it within that call to `PARSE`.
6740 Finally, `PARSE` can take a *look-ahead* `CHARACTER`, which is treated
6741 as if it were logically concatenated to the front of the *string*
6742 being parsed. Other arguments are described in sections 7.6.6.2 and
6743 15.7.2.
6744
6745 `LPARSE` is exactly like `PARSE`, except that it tries to parse the
6746 whole `STRING`, returning a `LIST` of the objects created.
6747
6748 17.2. EVAL Macros
6749 -----------------
6750
6751 An `EVAL` macro provides the convenience of a `FUNCTION` without the
6752 overhead of calling, `SPECIAL`s, etc. in the **compiled** version. A
6753 special-purpose function that is called often by `FUNCTION`s that will
6754 be compiled is a good candidate for an `EVAL` macro.
6755
6756 ### 17.2.1. DEFMAC and EXPAND
6757
6758 `DEFMAC` ("define macro") is syntactically exactly the same as
6759 `DEFINE`. However, instead of creating a `FUNCTION`, `DEFMAC` creates
6760 a `MACRO`. A `MACRO` is of `PRIMTYPE` `LIST` and in fact has a
6761 `FUNCTION` (or other `APPLICABLE` `TYPE`) as its single element.
6762
6763 A `MACRO` can itself be applied to arguments. A `MACRO` is applied in
6764 a funny way, however: it is `EVAL`ed twice. The first `EVAL` causes
6765 the `MACRO`'s element to be applied to the `MACRO`'s arguments.
6766 Whatever that application returns (usually another `FORM`) is also
6767 `EVAL`ed. The result of the second `EVAL`uation is the result of
6768 applying the `MACRO`. `EXPAND` is used to perform the first `EVAL`
6769 without the second.
6770
6771 To avoid complications, the first `EVAL` (by `EXPAND`, to create the
6772 object to be `EVAL`ed the second time around) is done in a top-level
6773 environment. The result of this policy is that two syntactically
6774 identical invocations of a `MACRO` always return the same expansion to
6775 be `EVAL`ed in the second step. The first `EVAL` generates two extra
6776 `FRAME`s: one for a call to `EXPAND`, and one for a call to `EVAL` the
6777 `MACRO` application in a top-level environment.
6778
6779 Example:
6780
6781     <DEFMAC INC (ATM "OPTIONAL" (N 1))
6782             #DECL ((VALUE) FORM (ATM) ATOM (N) <OR FIX FLOAT>)
6783             <FORM SET .ATM <FORM + <FORM LVAL .ATM> .N>>>$
6784     INC
6785     ,INC$
6786     #MACRO (#FUNCTION ((ATM "OPTIONAL" (N 1)) ...))
6787     <SET X 1>$
6788     1
6789     <INC X>$
6790     2
6791     .X$
6792     2
6793     <EXPAND '<INC X>>$
6794     <SET X <+ .X 1>>
6795
6796 Perhaps the intention is clearer if `PARSE` and `%` are used:
6797
6798     <DEFMAC INC (ATM "OPTIONAL" (N 1))
6799             #DECL (...)
6800             <PARSE "<SET %.ATM <+ %.ATM %.N>>">>
6801
6802 `MACRO`s really exhibit their advantages when they are compiled. The
6803 compiler will simply cause the first `EVAL`uation to occur (via
6804 `EXPAND`) and compile the result. The single element of a compiled
6805 `MACRO` is an `RSUBR` or `RSUBR-ENTRY`.
6806
6807 ### 17.2.2. Example
6808
6809 Suppose you want to change the following simple `FUNCTION` to a
6810 `MACRO`:
6811
6812     <DEFINE DOUBLE (X) #DECL ((X) FIX) <+ .X .X>>
6813
6814 You may be tempted to write:
6815
6816     <DEFMAC DOUBLE (X) #DECL ((X) FIX) <FORM + .X .X>>
6817
6818 This `MACRO` works, but only when the argument does not use temporary
6819 bindings. Consider
6820
6821     <DEFINE TRIPLE (Y) <+ .Y <DOUBLE .Y>>>
6822
6823 If this `FUNCTION` is applied, the top-level binding of `Y` is used,
6824 not the binding just created by the application. Compilation of this
6825 `FUNCTION` would probably fail, because the compiler probably would
6826 have no top-level binding for `Y`. Well, how about
6827
6828     <DEFMAC DOUBLE ('X) <FORM + .X .X>>  ;"The DECL has to go."
6829
6830 Now this is more like the original `FUNCTION`, because no longer is
6831 the argument evaluated and the result evaluated again. And `TRIPLE`
6832 works. But now consider
6833
6834     <DEFINE INC-AND-DOUBLE (Y) <DOUBLE <SET Y <+ 1 .Y>>>>
6835
6836 You might hope that
6837
6838     <INC-AND-DOUBLE 1> -> <DOUBLE <SET Y <+ 1 1>>>
6839                        -> <DOUBLE 2>
6840                        -> <+ 2 2>
6841                        -> 4
6842
6843 But, when `DOUBLE` is applied to that `FORM`, the argument is
6844 `QUOTE`d, so:
6845
6846     <INC-AND-DOUBLE 1> -> <DOUBLE <SET Y <+ 1 1>>>
6847                        -> <FORM + <SET Y <+ 1 .Y>> <SET Y <1 .Y>>>
6848                        -> <+ 2 3>
6849                        -> 5
6850
6851 So, since the evaluation of `DOUBLE`'s argument has a side effect, you
6852 should ensure that the evaluation is done exactly once, say by `FORM`:
6853
6854     <DEFMAC DOUBLE ('ANY)
6855             <FORM PROG ((X .ANY)) #DECL ((X) FIX) '<+ .X .X>>>
6856
6857 As a bonus, the `DECL` can once more be used.
6858
6859 This example is intended to show that writing good `MACRO`s is a
6860 little trickier than writing good `FUNCTION`s. But the effort may be
6861 worthwhile if the compiled program must be speedy.
6862
6863 Chapter 18. Machine Words and Bits
6864 ==================================
6865
6866 The Muddle facility for dealing with uninterpreted machine words and
6867 bits involves two data TYPEs: WORD and BITS. A WORD is simply an
6868 uninterpreted machine word, while a BITS is a "pointer" to a set of
6869 bits within a WORD. Operating on WORDs is usually done only when
6870 compiled programs are used (chapter 19).
6871
6872 18.1. WORDs
6873 -----------
6874
6875 A `WORD` in Muddle is a PDP-10 machine word of 36 bits. A `WORD`
6876 always `PRINT`s in "\# format", and its contents are always printed in
6877 octal (hence preceded and followed by `*`). Examples:
6878
6879     #WORD 0                  ;"all 0s"$
6880     #WORD *000000000000*
6881
6882     #WORD *2000*             ;"one bit 1"$
6883     #WORD *000000002000*
6884
6885     #WORD *525252525252*     ;"every other bit 1"$
6886     #WORD *525252525252*
6887
6888 `WORD` is its own `PRIMTYPE`; it is also the `PRIMTYPE` of `FIX`,
6889 `FLOAT`, `CHARACTER`, and any other `TYPE` which can fit its data into
6890 one machine word.
6891
6892 A `WORD` cannot be an argument to `+`, `-`, or indeed any `SUBR`s
6893 except for `CHTYPE`, `GETBITS`, `PUTBITS` and several bit-manipulating
6894 functions, all to be described below. Thus any arithmetic bit
6895 manipulation must be done by `CHTYPE`ing a `WORD` to `FIX`, doing the
6896 arithmetic, and then `CHTYPE`ing back to `WORD`. However, bit
6897 manipulation can be done without `CHTYPE`ing the thing to be played
6898 with to a `WORD`, so long as it is of `PRIMTYPE` `WORD`; the result of
6899 the manipulation will be of the same `TYPE` as the original object or
6900 can be `CHTYPE`d to it.
6901
6902 18.2. BITS
6903 ----------
6904
6905 An object of `TYPE` `BITS` is of `PRIMTYPE` `WORD`, and `PRINT`s just
6906 like a `WORD`. The internal form of a `BITS` is precisely that of a
6907 PDP-10 "byte pointer", which is, in fact, just what a `BITS` is.
6908
6909 For purposes of explaining what a `BITS` is, assume that the bits in a
6910 `WORD` are numbered from **right** to **left**, with the rightmost bit
6911 numbered 0 and the leftmost numbered 35, as in
6912
6913     35 34 33 ... 2 1 0
6914
6915 (This is not the "standard" ordering: the "standard" one goes from
6916 left to right.)
6917
6918 A `BITS` is most conveniently created via the `SUBR` `BITS`:
6919
6920     <BITS width:fix right-edge:fix>
6921
6922 returns a `BITS` which "points to" a set of bits *width* wide, with
6923 rightmost bit *right-edge*. Both arguments must be of `TYPE` `FIX`,
6924 and the second is optional, 0 by default.
6925
6926 Examples: the indicated application of `BITS` returns an object of
6927 `TYPE` `BITS` which points to the indicated set of bits in a `WORD`:
6928
6929   Example         Returns
6930   --------------- ------------------------------------
6931   `<BITS 7>`      35 ... 7 **6 ... 0**
6932   `<BITS 4 18>`   35 ... 22 **21 20 19 18** 17 ... 0
6933   `<BITS 36>`     ***35 ... 0***
6934
6935 18.3. GETBITS
6936 -------------
6937
6938     <GETBITS from:primtype-word bits>
6939
6940 where *from* is an object of `PRIMTYPE` `WORD`, returns a **new**
6941 object whose `TYPE` is `WORD`. This object is constructed in the
6942 following way: the set of bits in *from* pointed to by *bits* is
6943 copied into the new object, right-adjusted, that is, lined up against
6944 the right end (bit number 0) of the new object. All those bits of the
6945 new object which are not copied are set to zero. In other words,
6946 `GETBITS` takes bits from an arbitrary place in *from* and puts them
6947 at the right of a new object. The *from* argument to `GETBITS` is not
6948 affected.
6949
6950 Examples:
6951
6952     <GETBITS #WORD *777777777777* <BITS 3>>$
6953     #WORD *000000000007*
6954     <GETBITS *012345670123* <BITS 6 18>>$
6955     #WORD *000000000045*
6956
6957 18.4. PUTBITS
6958 -------------
6959
6960     <PUTBITS to:primtype-word bits from:primtype-word>
6961
6962 where *to* and *from* are of `PRIMTYPE` `WORD`, returns a **copy** of
6963 *to*, modified as follows: the set of bits in *to* which are pointed
6964 to by *bits* are replaced by the appropriate number of rightmost bits
6965 copied from *from* (optional, 0 by default). In other words: `PUTBITS`
6966 takes bits from the right of *from* and stuffs them into an arbitrary
6967 position in a copy of *to*. **None** of the arguments to `PUTBITS` is
6968 affected.
6969
6970 Examples:
6971
6972     <PUTBITS #WORD *777777777777* <BITS 6 3>>$
6973     #WORD *777777777007*
6974     <PUTBITS #WORD *666777000111* <BITS 5 15> #WORD *123*>$
6975     #WORD *666776300111*
6976     <PUTBITS #WORD *765432107654* <BITS 18>>$
6977     #WORD *765432000000*
6978
6979 18.5. Bitwise Boolean Operations
6980 --------------------------------
6981
6982 Each of the `SUBR`s `ANDB`, `ORB`, `XORB`, and `EQVB` takes arguments
6983 of `PRIMTYPE` `WORD` and returns a `WORD` which is the bitwise Boolean
6984 "and", inclusive "or", exclusive "or", or "equivalence" (inverse of
6985 exclusive "or"), respectively, of its arguments. Each takes any number
6986 of arguments. If no argument is given, a `WORD` with all bits off
6987 (`ORB` and `XORB`) or on (`ANDB` and `EQVB`) is returned. If only one
6988 argument is given, it is returned unchanged but `CHTYPE`d to a `WORD`.
6989 If more than two arguments are given, the operator is applied to the
6990 first two, then applied to that result and the third, etc. Be sure not
6991 to confuse `AND` and `OR` with `ANDB` and `ORB`.
6992
6993 18.6. Bitwise Shifting Operations
6994 ---------------------------------
6995
6996     <LSH from:primtype-word amount:fix>
6997
6998 returns a **new** `WORD` containing the bits in *from*, shifted the
6999 number of bits specified by *amount* (mod 256, says the hardware).
7000 Zero bits are brought in at the end being vacated; bits shifted out at
7001 the other end are lost. If *amount* is positive, shifting is to the
7002 left; if *amount* is negative, shifting is to the right. Examples:
7003
7004     <LSH 8 6>$
7005     #WORD *000000001000*
7006     <LSH 8 -6>$
7007     #WORD *000000000000*
7008
7009     <ROT from:primtype-word amount:fix>
7010
7011 returns a **new** `WORD` containing the bits from *from*, rotated the
7012 number of bits specified by *amount* (mod 256, says the hardware).
7013 Rotation is a cyclic bitwise shift where bits shifted out at one end
7014 are put back in at the other. If *amount* is positive, rotation is to
7015 the left; if *amount* is negative, rotation is to the right. Examples:
7016
7017     <ROT 8 6>$
7018     #WORD *000000001000*
7019     <ROT 8 -6>$
7020     #WORD *100000000000*
7021
7022 Chapter 19. Compiled Programs
7023 =============================
7024
7025 19.1. RSUBR (the TYPE)
7026 ----------------------
7027
7028 `RSUBR`s ("relocatable subroutines") are machine-language programs
7029 written to run in the Muddle environment. They are usually produced by
7030 the Muddle assembler (often from output produced by the compiler)
7031 although this is not necessary. All `RSUBR`s have two components: the
7032 "reference vector" and the "code vector". In some cases the code
7033 vector is in pure storage. There is also a set of "fixups" associated
7034 with every `RSUBR`, although it may not be available in the running
7035 Muddle.
7036
7037 19.2. The Reference Vector
7038 --------------------------
7039
7040 An `RSUBR` is basically a `VECTOR` that has been `CHTYPE`d to `TYPE`
7041 `RSUBR` via the `SUBR` `RSUBR` (see below). This ex-`VECTOR` is the
7042 reference vector. The first three elements of the reference vector
7043 have predefined meanings:
7044
7045 -   The first element is of `TYPE` `CODE` or `PCODE` and is the impure
7046     or pure code vector respectively.
7047 -   The second element is an `ATOM` and specifies the name of the
7048     `RSUBR`.
7049 -   The third element is of `TYPE` `DECL` and declares the
7050     type/structure of the `RSUBR`'s arguments and result.
7051
7052 The rest of the elements of the reference vector are objects in
7053 garbage-collected storage that the `RSUBR` needs to reference and any
7054 impure slots that the `RSUBR` needs to use.
7055
7056 When the `RSUBR` is running, one of the PDP-10 accumulators (with
7057 symbolic name `R`) is always pointing to the reference vector, to
7058 permit rapid access to the various elements.
7059
7060 19.3. RSUBR Linking
7061 -------------------
7062
7063 `RSUBR`s can call any `APPLICABLE` object, all in a uniform manner. In
7064 general, a call to an F/SUBR is linked up at assembly/compile time so
7065 that the calling instruction (UUO) points directly at the code in the
7066 interpreter for the F/SUBR. However, the locations of most other
7067 `APPLICABLE`s are not known at assembly/compile time. Therefore, the
7068 calling UUO is set up to point at a slot in the reference vector (by
7069 indexing off accumulator `R`). This slot initially contains the `ATOM`
7070 whose G/LVAL is the called object. The calling mechanism (UUO handler)
7071 causes control to be transferred to the called object and, depending
7072 on the state of the `RSUBR`-link flag, the `ATOM` will be replaced by
7073 its G/LVAL. (If the call is of the "quick" variety, the called `RSUBR`
7074 or `RSUBR-ENTRY` will be `CHTYPE`d to a `QUICK-RSUBR` or
7075 `QUICK-ENTRY`, respectively, before replacement.) Regardless of the
7076 `RSUBR`-link flag's state, calls to `FUNCTION`s are never permanently
7077 linked. A call to a non-Subroutine generates an extra `FRAME`, whose
7078 `FUNCT` is the dummy `ATOM` `CALLER`.
7079
7080 `RSUBR`s are linked together for faster execution, but linking may not
7081 be desirable if the `RSUBR`s are being debugged, and various revisions
7082 are being re-loaded. A linked call will forever after go to the same
7083 code, regardless of the current G/LVAL of the called `ATOM`. Thus,
7084 while testing `RSUBR`s, you may want to disable linking, by calling
7085 the `RSUBR-LINK` `SUBR` with a `FALSE` argument. Calling it with a
7086 non-`FALSE` argument enables linking thereafter. It returns the
7087 previous state of the link flag, either `T` or `#FALSE ()`. Calling it
7088 with no argument returns the current state.
7089
7090 19.4. Pure and Impure Code
7091 --------------------------
7092
7093 The first element of an `RSUBR` is the code vector, of `TYPE` `CODE`
7094 or `PCODE`. `TYPE` `CODE` is of `PRIMTYPE` `UVECTOR`, and the `UTYPE`
7095 should be of `PRIMTYPE` `WORD`. The code vector is simply a block of
7096 words that are the instructions which comprise the `RSUBR`. Since the
7097 code vector is stored just like a standard `UVECTOR`, it will be moved
7098 around by the garbage collector. Therefore, all `RSUBR` code is
7099 required to be location-insensitive. The compiler guarantees the
7100 location-insensitivity of its output. The assembler helps to make the
7101 code location-insensitive by defining all labels as offsets relative
7102 to the beginning of the code vector and causing instructions that
7103 refer to labels to index automatically off the PDP-10 accumulator
7104 symbolically named `M`. `M`, like `R`, is set up by the UUO handler,
7105 but it points to the code vector instead of the reference vector. The
7106 code vector of an `RSUBR` can be frozen (using the `FREEZE` `SUBR`) to
7107 prevent it from moving during debugging by DDT in the superior
7108 operating-system process.
7109
7110 If the first element of an `RSUBR` is of `TYPE` `PCODE` ("pure code"),
7111 the code vector of the `RSUBR` is pure and sharable. `TYPE` `PCODE` is
7112 of `PRIMTYPE` `WORD`. The left half of the word specifies an offset
7113 into an internal table of pure `RSUBR`s, and the right half specifies
7114 an offset into the block of code where this `RSUBR` starts. The
7115 `PCODE` prints out as:
7116
7117     %<PCODE name:string offset:fix>
7118
7119 where *name* names the entry in the user's pure-`RSUBR` table, and
7120 *offset* is the offset. (Obviously, `PCODE` is also the name of a
7121 `SUBR`, which generates a pure code vector.) Pure `RSUBR`s may also
7122 move around, but only by being included in Muddle's page map at
7123 different places. Once again `M` can be used exactly as before to do
7124 location-independent address referencing. Individual pure code vectors
7125 can be "unmapped" (marked as being not in primary storage but in their
7126 original pure-code disk files) if the space in storage allocated for
7127 pure code is exhausted. An unmapped `RSUBR` is mapped in again
7128 whenever needed. All pure `RSUBR`s are unmapped before a `SAVE` file
7129 is written, so that the code is not duplicated on disk. A purified
7130 `RSUBR` must use `RGLOC` ("relative GLOC") instead of `GLOC`. `RGLOC`
7131 produces objects of `TYPE` `LOCR` instead of `LOCD`.
7132
7133 19.5. TYPE-C and TYPE-W
7134 =======================
7135
7136 In order to handle user `NEWTYPE`s reasonably, the internal `TYPE`
7137 codes for them have to be able to be different from one Muddle run to
7138 another. Therefore, references to the `TYPE` codes must be in the
7139 reference vector rather than the code vector. To help handle this
7140 problem, two `TYPE`s exist, `TYPE-C` ("type code") and `TYPE-W` ("type
7141 word"), both of `PRIMTYPE` `WORD`. They print as:
7142
7143     %<TYPE-C type primtype:atom>
7144     %<TYPE-W type primtype:atom>
7145
7146 The `SUBR` `TYPE-C` produces an internal `TYPE` code for the *type*,
7147 and `TYPE-W` produces a prototype "`TYPE` word" (appendix 1) for an
7148 object of that `TYPE`. The *primtype* argument is optional, included
7149 only as a check against the call to `NEWTYPE`. `TYPE-W` can also take
7150 a third argument, of `PRIMTYPE` `WORD`, whose right half is included
7151 in the generated "`TYPE` word". If *type* is not a valid `TYPE`, a
7152 `NEWTYPE` is automatically done.
7153
7154 To be complete, a similar `SUBR` and `TYPE` should be mentioned here.
7155
7156     <PRIMTYPE-C type>
7157
7158 produces an internal "storage allocation code" (appendix 1) for the
7159 *type*. The value is of `TYPE` `PRIMTYPE-C`, `PRIMTYPE` `WORD`. In
7160 almost all cases the `SUBR` `TYPEPRIM` gives just as much information,
7161 except in the case of `TEMPLATE`s: all `TYPE`s of `TEMPLATE`s have the
7162 same `TYPEPRIM`, but they all have different `PRIMTYPE-C`s.
7163
7164 19.6. RSUBR (the SUBR)
7165 ----------------------
7166
7167     <RSUBR [code name decl ref ref ...]>
7168
7169 `CHTYPE`s its argument to an `RSUBR`, after checking it for legality.
7170 `RSUBR` is rarely called other than in the Muddle Assembler (Lebling,
7171 1979). It can be used if changes must be made to an `RSUBR` that are
7172 prohibited by Muddle's built-in safety mechanisms. For example, if the
7173 `GVAL` of *name* is an `RSUBR`:
7174
7175     <SET FIXIT <CHTYPE ,name VECTOR>>$
7176     [...]
7177
7178     ...(changes to .FIXIT)...
7179
7180     <SETG name <RSUBR .FIXIT>>$
7181     #RSUBR [...]
7182
7183 19.7. RSUBR-ENTRY
7184 -----------------
7185
7186 `RSUBR`s can have multiple entry points. An `RSUBR-ENTRY` can be
7187 applied to arguments exactly like an `RSUBR`.
7188
7189     <RSUBR-ENTRY [rsubr-or-atom name:atom decl] offset:fix>
7190
7191 returns the `VECTOR` argument `CHTYPE`d to an `RSUBR-ENTRY` into the
7192 *rsubr* at the specified *offset*. If the `RSUBR-ENTRY` is to have a
7193 `DECL` (`RSUBR` style), it should come as shown.
7194
7195     <ENTRY-LOC rsubr-entry>
7196
7197 ("entry location") returns the *offset* into the `RSUBR` of this
7198 entry.
7199
7200 19.8. RSUBRs in Files
7201 ---------------------
7202
7203 There are three kinds of files that can contain `RSUBR`s, identified
7204 by second names `BINARY`, `NBIN` and `FBIN`. There is nothing magic
7205 about these names, but they are used by convention.
7206
7207 A `BINARY` file is a completely ASCII file containing complete impure
7208 `RSUBR`s in character representation. Even a code vector appears as
7209 `#CODE` followed by a `UVECTOR` of `PRIMTYPE` `WORD`s. `BINARY` files
7210 are generally slow to load, because of all the parsing that must be
7211 done.
7212
7213 An `NBIN` file contains a mixture of ASCII characters and binary code.
7214 The start of a binary portion is signalled to `READ` by the character
7215 control-C, so naive readers of an `NBIN` file under ITS may
7216 incorrectly assume that it ends before any binary code appears. An
7217 `NBIN` file cannot be edited with a text editor. An `RSUBR` is written
7218 in `NBIN` format by being `PRINT`ed on a `"PRINTB"` `CHANNEL`. The
7219 `RSUBR`s in `NBIN` files are not purified either.
7220
7221 An `FBIN` file is actually part of a triad of files. The `FBIN`
7222 file(s) itself is the impure part of a collection of purified
7223 `RSUBR`s. It is simply ASCII and can be edited at will. (Exception: in
7224 the ITS and Tops-20 versions, the first object in the file should not
7225 be removed or changed in any way, lest a "grim reaper" program for
7226 `FBIN` files think that the other files in the triad are obsolete and
7227 delete them.) The pure code itself resides (in the ITS and Tops-20
7228 versions) in a special large file that contains all currently-used
7229 pure code, or (in the Tenex version) in a file in a special disk
7230 directory with first name the same as the *name* argument to `PCODE`
7231 for the `RSUBR`. The pure-code file is page-mapped directly into
7232 Muddle storage in read-only mode. It can be unmapped when the pure
7233 storage must be reclaimed, and it can be mapped at a different storage
7234 address when pure storage must be compacted. There is also a "fixup"
7235 file (see below) or portion of a file associated with the `FBIN` to
7236 round out the triad.
7237
7238 An initial Muddle can have pure `RSUBR`s in it that were "loaded"
7239 during the initialization procedure. The files are not page-mapped in
7240 until they are actually needed. The "loading" has other side effects,
7241 such as the creation of `OBLIST`s (chapter 15). Exactly what is
7242 pre-loaded is outside the scope of this document.
7243
7244 19.9. Fixups
7245 ------------
7246
7247 The purpose of "fixups" is to correct references in the `RSUBR` to
7248 parts of the interpreter that change from one release of Muddle to the
7249 next. The reason the fixups contain a release number is so that they
7250 can be completely ignored when an `RSUBR` is loaded into the same
7251 release of Muddle as that from which it was last written out.
7252
7253 There are three forms of fixups, corresponding to the three kinds of
7254 `RSUBR` files. ASCII `RSUBR`s, found in `BINARY` files, have ASCII
7255 fixups. The fixups are contained in a `LIST` that has the following
7256 format:
7257
7258     (Muddle-release:fix
7259         name:atom value:fix (use:fix use:fix ...)
7260         name:atom value:fix (use:fix use:fix ...)
7261         ...)
7262
7263 The fixups in `NBIN` files and the fixup files associated with `FBIN`
7264 files are in a fast internal format that looks like a `UVECTOR` of
7265 `PRIMTYPE` `WORD`s.
7266
7267 Fixups are usually discarded after they are used during the loading
7268 procedure. However, if, while reading a `BINARY` or `NBIN` file the
7269 `ATOM` `KEEP-FIXUPS!-` has a non-`FALSE` `LVAL`, the fixups will be
7270 kept, via an association between the `RSUBR` and the `ATOM` `RSUBR`.
7271 It should be noted that, besides correcting the code, the fixups
7272 themselves are corrected when `KEEP-FIXUPS` is bound and true. Also,
7273 the assembler and compiler make the same association when they first
7274 create an `RSUBR`, so that it can be written out with its fixups.
7275
7276 In the case of pure `RSUBR`s (`FBIN` files), things are a little
7277 different. If a pure-code file exists for this release of Muddle, it
7278 is used immediately, and the fixups are completely ignored. If a
7279 pure-code file for this release doesn't exist, the fixup file is used
7280 to create a new copy of the file from an old one, and also a new
7281 version of the fixup file is created to go with the new pure-code
7282 file. This all goes on automatically behind the user's back.
7283
7284 Chapter 20. Coroutines
7285 ======================
7286
7287 This chapter purports to explain the coroutine primitives of Muddle.
7288 It does make some attempt to explain coroutines as such, but only as
7289 required to specify the primitives. If you are unfamiliar with the
7290 basic concepts, confusion will probably reign.
7291
7292 A coroutine in Muddle is implemented by an object of `TYPE` `PROCESS`.
7293 In this manual, this use of the word "process" is distinguished by a
7294 capitalization from its normal use of denoting an operating-system
7295 process (which various systems call a process, job, fork, task, etc.).
7296
7297 Muddle's built-in coroutine primitives do not include a "time-sharing
7298 system". Only one `PROCESS` is ever running at a time, and control is
7299 passed back and forth between `PROCESS`es on a coroutine-like basis.
7300 The primitives are sufficient, however, to allow the writing of a
7301 "time-sharing system" **in Muddle**, with the additional use of the
7302 Muddle interrupt primitives. This has, in fact, been done.
7303
7304 20.1. PROCESS (the TYPE)
7305 ------------------------
7306
7307 A `PROCESS` is an object which contains the "current state" of a
7308 computation. This includes the `LVAL`s of `ATOM`s ("bindings"),
7309 "depth" of functional application, and "position" within the
7310 application of each applied function. Some of the things which are
7311 **not** part of any specific `PROCESS` are the `GVAL`s of `ATOM`s,
7312 associations (`ASOC`s), and the contents of `OBLIST`s. `GVAL`s (with
7313 `OBLIST`s) are a chief means of communication and sharing between
7314 `PROCESS`es (all `PROCESS`es can refer to the `SUBR` which is the
7315 `GVAL` of `+`, for instance.) Note that an `LVAL` in one `PROCESS`
7316 cannot easily be directly referenced from another `PROCESS`.
7317
7318 A `PROCESS` `PRINT`s as `#PROCESS` *p*, where *p* is a `FIX` which
7319 uniquely identifies the `PROCESS`; *p* is the "`PROCESS` number" typed
7320 out by `LISTEN`. A `PROCESS` cannot be read in by `READ`.
7321
7322 The term "run a `PROCESS`" will be used below to mean "perform some
7323 computation, using the `PROCESS` to record the intermediate state of
7324 that computation".
7325
7326 N.B.: A `PROCESS` is a rather large object; creating one will often
7327 cause a garbage collection.
7328
7329 20.2. STATE of a PROCESS
7330 ------------------------
7331
7332     <STATE process>
7333
7334 returns an `ATOM` (in the `ROOT` `OBLIST`) which indicates the "state"
7335 of the `PROCESS` *process*. The `ATOM`s which `STATE` can return, and
7336 their meanings, are as follows:
7337
7338 -   `RUNABLE` (sic) -- *process* has never ever been run.
7339 -   `RUNNING` -- *process* is currently running, that is, it did the
7340     application of `STATE`.
7341 -   `RESUMABLE` -- *process* has been run, is not currently running,
7342     and can run again.
7343 -   `DEAD` -- *process* has been run, but it can **not** run again; it
7344     has "terminated".
7345
7346 In addition, an interrupt (chapter 21) can be enabled to detect the
7347 time at which a `PROCESS` becomes "blocked" (waiting for terminal
7348 input) or "unblocked" (terminal input arrived). (The `STATE` `BLOCKED`
7349 has not been implemented.)
7350
7351 20.3. PROCESS (the SUBR)
7352 ------------------------
7353
7354     <PROCESS starter:applicable>
7355
7356 creates and returns a new `PROCESS` but does **not** run it; the
7357 `STATE` of the returned `PROCESS` is `RUNABLE` (sic).
7358
7359 *starter* is something applicable to **one** argument, which must be
7360 evaluated. *starter* is used both in starting and "terminating" a
7361 `PROCESS`. In particular, if the *starter* of a `PROCESS` **ever**
7362 returns a value, that `PROCESS` becomes `DEAD`.
7363
7364 20.4. RESUME
7365 ------------
7366
7367 The `SUBR` `RESUME` is used to cause a computation to start or to
7368 continue running in another `PROCESS`. An application of `RESUME`
7369 looks like this:
7370
7371     <RESUME retval:any process>
7372
7373 where *retval* is the "returned value" (see below) of the `PROCESS`
7374 that does the `RESUME`, and *process* is the `PROCESS` to be started
7375 or continued.
7376
7377 The *process* argument to `RESUME` is optional, by default the last
7378 `PROCESS`, if any, to `RESUME` the `PROCESS` in which this `RESUME` is
7379 applied. If and when the current `PROCESS` is later `RESUME`d by
7380 another `PROCESS`, that `RESUME`'s *retval* is returned as the value
7381 of this `RESUME`.
7382
7383 20.5. Switching PROCESSes
7384 -------------------------
7385
7386 ### 20.5.1. Starting Up a New PROCESS
7387
7388 Let us say that we are running in some `PROCESS`, and that this
7389 original `PROCESS` is the `GVAL` of `P0`. Somewhere, we have evaluated
7390
7391     <SETG P1 <PROCESS ,STARTER>>
7392
7393 where `,STARTER` is some appropriate function. Now, **in `,P0`** we
7394 evaluate
7395
7396     <RESUME .A ,P1>
7397
7398 and the following happens:
7399
7400 1.  **In `,P0`** the arguments of the `RESUME` are evaluated: that is,
7401     we get that `LVAL` of `A` which is current in `,P0` and the `GVAL`
7402     of `P1`.
7403 2.  The `STATE` of `,P0` is changed to `RESUMABLE` and `,P0` is
7404     "frozen" right where it is, in the middle of the `RESUME`.
7405 3.  The `STATE` of `,P1` is changed to `RUNNING`, and `,STARTER` is
7406     applied to `,P0`'s `LVAL` of `A` **in `,P1`**. `,P1` now continues
7407     on its way, evaluating the body of `,STARTER.`
7408
7409 The `.A` in the `RESUME` could have been anything, of course. The
7410 important point is that, whatever it is, it is evaluated in `,P0`.
7411
7412 What happens next depends, of course, on what `,STARTER` does.
7413
7414 ### 20.5.2. Top-level Return
7415
7416 Let us initially assume that `,STARTER` does nothing relating to
7417 `PROCESS`es, but instead simply returns a value -- say *starval*. What
7418 happens when `,STARTER` returns is this:
7419
7420 1.  The `STATE` of `,P1` is changed to `DEAD`. `,P1` can never again
7421     be `RESUME`d.
7422 2.  The last `PROCESS` to `RESUME` `,P1` is found, namely `,P0`, and
7423     its `STATE` is changed to `RUNNING`.
7424 3.  *starval* is returned in `,P0` as the value of the original
7425     `RESUME`, and `,P0` continues where it left off.
7426
7427 All in all, this simple case looks just like an elaborate version of
7428 applying `,STARTER` to `.A` in `,P0`.
7429
7430 ### 20.5.3. Symmetric RESUMEing
7431
7432 Now suppose that while still in `,P1`, the following is evaluated,
7433 either in `,STARTER` or in something called by `,STARTER`:
7434
7435     <RESUME .BAR ,P0>
7436
7437 This is what happens:
7438
7439 1.  The arguments of the `RESUME` are evaluated **in `,P1`**.
7440 2.  The `STATE` of `,P1` is changed to `RESUMABLE`, and `,P1` is
7441     "frozen" right in the middle of the `RESUME`.
7442 3.  The `STATE` of `,P0` is changed to `RUNNING`, and `,P1`'s `LVAL`
7443     of `BAR` is returned as the value of **`,P0'`s** original `RESUME`
7444     `,P0` then continues right where it left off.
7445
7446 This is **the** interesting case, because `,P0` can now do **another**
7447 `RESUME` of `,P1`; this will "turn off" `,P0`, pass a value to `,P1`
7448 and "turn on" `,P1`. `,P1` can now again `RESUME` `,P0`. which can
7449 `RESUME` `,P1` back again, etc. **ad nauseam**, with everything done
7450 in a perfectly symmetric manner. This can obviously also be done with
7451 three or more `PROCESS`es in the same manner.
7452
7453 Note how this differs from normal functional application: you cannot
7454 "return" from a function without destroying the state that function is
7455 in. The whole point of `PROCESS`es is that you can "return"
7456 (`RESUME`), remembering your state, and later continue where you left
7457 off.
7458
7459 20.6. Example
7460 -------------
7461
7462     ;"Initially, we are in LISTEN in some PROCESS.
7463     <DEFINE SUM3 (A)
7464             #DECL ((A) (OR FIX FLOAT>)
7465             <REPEAT ((S .A))
7466                     #DECL ((S) <OR FIX FLOAT>)
7467                     <SET S <+ .S <RESUME "GOT 1">>>
7468                     <SET S <+ .S <RESUME "GOT 2">>>
7469                     <SET S <RESUME .S>>>>$
7470     SUM3
7471     ;"SUM3, used as the startup function of another PROCESS,
7472     gets RESUMEd with numbers. It returns the sum of the last
7473     three numbers it was given every third RESUME."
7474     <SETG SUMUP <PROCESS ,SUM3>>$
7475     ;"Now we start SUMUP and give SUM3 its three numbers."
7476     <RESUME 5 ,SUMUP>$
7477     "GOT 1"
7478     <RESUME 1 ,SUMUP>$
7479     "GOT 2"
7480     <RESUME 2 ,SUMUP>$
7481     8
7482
7483 Just as a note, by taking advantage of Muddle's order of evaluation,
7484 SUM3 could be have been written as:
7485
7486     <DEFINE SUM3 (A)
7487             <REPEAT ((S .A))
7488                #DECL ((A S0 <OR FIX FLOAT>)
7489                <SET S <RESUME <+ .S <RESUME "GOT 1"> <RESUME "GOT 2">>>>>>
7490
7491 20.7. Other Coroutining Features
7492 --------------------------------
7493
7494 ### 20.7.1. BREAK-SEQ
7495
7496     <BREAK-SEQ any process>
7497
7498 ("break evaluation sequence") returns *process*, which must be
7499 `RESUMABLE`, after having modified it so that when it is next
7500 `RESUME`d, it will **first** evaluate *any* and **then** do an
7501 absolutely normal `RESUME`; the value returned by any is thrown away,
7502 and the value given by the `RESUME` is used normally.
7503
7504 If a `PROCESS` is `BREAK-SEQ`ed more than once between `RESUME`s,
7505 **all** of the *any*s `BREAK-SEQ`ed onto it will be remembered and
7506 evaluated when the `RESUME` is finally done. The *any*s will be
7507 evaluated in "last-in first-out" order. The `FRAME` generated by
7508 `EVAL`ing more than one *any* will have as its `FUNCT` the dummy
7509 `ATOM` `BREAKER`.
7510
7511 ### 20.7.2. MAIN
7512
7513 When you initially start up Muddle, the `PROCESS` in which you are
7514 running is slightly "special" in these two ways:
7515
7516 1.  Any attempt to cause it become `DEAD` will be met with an error.
7517 2.  `<MAIN>` always returns that `PROCESS`.
7518
7519 The `PROCESS` number of `<MAIN>` is always `1`. The initial `GVAL` of
7520 `THIS-PROCESS` is what `MAIN` always returns, `#PROCESS 1`.
7521
7522 ### 20.7.3. ME
7523
7524     <ME>
7525
7526 returns the `PROCESS` in which it is evaluated. The `LVAL` of
7527 `THIS-PROCESS` in a `RUNABLE` (new) `PROCESS` is what `ME` always
7528 returns.
7529
7530 ### 20.7.4. RESUMER
7531
7532     <RESUMER process>
7533
7534 returns the `PROCESS` which last `RESUME`d *process*. If no `PROCESS`
7535 has ever `RESUME`d process, it returns `#FALSE ()`. *process* is
7536 optional, `<ME>` by default. Note that `<MAIN>` does not ever have any
7537 resumer. Example:
7538
7539     <PROG ((R <RESUMER>))           ;"not effective in <MAIN>"
7540        #DECL ((R) <OR PROCESS FALSE>)
7541        <AND .R
7542             <==? <STATE .R> RESUMABLE>
7543             <RESUME T .R>>>
7544
7545 ### 20.7.5. SUICIDE
7546
7547     <SUICIDE retval process>
7548
7549 acts just like `RESUME`, but clobbers the `PROCESS` (which cannot be
7550 `<MAIN>`) in which it is evaluated to the `STATE` `DEAD`.
7551
7552 ### 20.7.6. 1STEP
7553
7554     <1STEP process>
7555
7556 returns *process*, after putting it into "single-step mode".
7557
7558 A `PROCESS` in single-step mode, whenever `RESUME`d, runs only until
7559 an application of `EVAL` in it begins or finishes. At that point in
7560 time, the `PROCESS` that did the `1STEP` is `RESUME`d, with a *retval*
7561 which is a `TUPLE`. If an application of `EVAL` just began, the
7562 `TUPLE` contains the `ATOM` `EVLIN` and the arguments to `EVAL`. If an
7563 application of `EVAL` just finished, the `TUPLE` contains the `ATOM`
7564 `EVLOUT` and the result of the evaluation.
7565
7566 *process* will remain in single-step mode until `FREE-RUN` (below) is
7567 applied to it. Until then, it will stop before and after each `EVAL`
7568 in it. Exception: if it is `RESUME`d from an `EVLIN` break with a
7569 *retval* of `TYPE` `DISMISS` (`PRIMTYPE` `ATOM`), it will leave
7570 single-step mode only until the current call to EVAL is about to
7571 return. Thus lower-level `EVAL`s are skipped over without leaving the
7572 mode. The usefulness of this mode in debugging is obvious.
7573
7574 ### 20.7.7. FREE-RUN
7575
7576     <FREE-RUN process>
7577
7578 takes its argument out of single-step mode. Only the `PROCESS` that
7579 put *process* into single-step mode can take it out of the mode; if
7580 another `PROCESS` tries, `FREE-RUN` returns a `FALSE`.
7581
7582 20.8. Sneakiness with PROCESSes
7583 -------------------------------
7584
7585 `FRAME`s, `ENVIRONMENT`s, `TAG`s, and `ACTIVATION`s are specific to
7586 the `PROCESS` which created them, and each "knows its own father".
7587 **Any** `SUBR` which takes these objects as arguments can take one
7588 which was generated by **any** `PROCESS`, no matter where the `SUBR`
7589 is really applied. This provides a rather sneaky means of crossing
7590 between `PROCESS`es. The various cases are as follows:
7591
7592 `GO`, `RETURN`, `AGAIN`, and `ERRET`, given arguments which lie in
7593 another `PROCESS`, each effectively "restarts" the `PROCESS` of its
7594 argument and acts as if it were evaluated over there. If the `PROCESS`
7595 in which it was executed is later `RESUME`d, it **returns** a value
7596 just like `RESUME`!
7597
7598 `SET`, `UNASSIGN`, `BOUND?`, `ASSIGNED?`, `LVAL`, `VALUE`, and `LLOC`,
7599 given optional `ENVIRONMENT` arguments which lie in another `PROCESS`,
7600 will gleefully change, or return, the local values of `ATOM`s in the
7601 other `PROCESS`. The optional argument can equally well be a
7602 `PROCESS`, `FRAME`, or `ACTIVATION` in another `PROCESS`; in those
7603 cases, each uses the `ENVIRONMENT` which is current in the place
7604 specified.
7605
7606 `FRAME`, `ARGS`, and `FUNCT` will be glad to return the `FRAME`s,
7607 argument `TUPLE`s, and applied Subroutine names of another `PROCESS`.
7608 If one is given a `PROCESS` (including `<ME>`) as an argument instead
7609 of a `FRAME`, it returns all or the appropriate part of the topmost
7610 `FRAME` on that `PROCESS`'s control stack.
7611
7612 If `EVAL` is applied in `PROCESS` `P1` with an `ENVIRONMENT` argument
7613 from a `PROCESS` `P2`, it will do the evaluation **in `P1`** but with
7614 `P2`'s `ENVIRONMENT` (!). That is, the other `PROCESS`'s `LVAL`s, etc.
7615 will be used, but (1) any **new** `FRAME`s needed in the course of the
7616 evaluation will be created in `P1`; and (2) **`P1`** will be `RUNNING`
7617 -- not `P2`. Note the following: if the `EVAL` in `P1` eventually
7618 causes a `RESUME` of `P2`, `P2` could functionally return to below the
7619 point where the `ENVIRONMENT` used in `P1` is defined; a `RESUME` of
7620 `P1` at this point would cause an `ERROR` due to an invalid
7621 `ENVIRONMENT`. (Once again, `LEGAL?` can be used to forestall this.)
7622
7623 20.9. Final Notes
7624 -----------------
7625
7626 1.  A `RESUMABLE` `PROCESS` can be used in place of an `ENVIRONMENT`
7627     in any application. The "current" `ENVIRONMENT` of the `PROCESS`
7628     is effectively used.
7629 2.  `FRAME`s and `ENVIRONMENT`s can be `CHTYPE`d arbitrarily to one
7630     another, or an `ACTIVATION` can be `CHTYPE`d to either of them,
7631     and the result "works". Historically, these different `TYPE`s were
7632     first used with different `SUBR`s -- `FRAME` with `ERRET`,
7633     `ENVIRONMENT` with `LVAL`, `ACTIVATION` with `RETURN` -- hence the
7634     invention of different `TYPE`s with similar properties.
7635 3.  Bugs in multi-`PROCESS` programs usually exhibit a degree of
7636     subtlety and nastiness otherwise unknown to the human mind. If
7637     when attempting to work with multiple processes you begin to feel
7638     that you are rapidly going insane, you are in good company.
7639
7640 Chapter 21. Interrupts
7641 ======================
7642
7643 The Muddle interrupt handling facilities provide the ability to say
7644 the following: whenever "this event" occurs, stop whatever is being
7645 done at the time and perform "this action"; when "this action" is
7646 finished, continue with whatever was originally being done. "This
7647 event" can be things like the typing of a character at a terminal, a
7648 time interval ending, a `PROCESS` becoming blocked, or a
7649 program-defined and -generated "event". "This action" is the
7650 application of a specified `APPLICABLE` object to arguments provided
7651 by the Muddle interrupt system. The sets of events and actions can be
7652 changed in extremely flexible ways, which accounts for both the
7653 variety of `SUBR`s and arguments, and the rich interweaving of the
7654 topics in this chapter. Interrupt handling is a kind of parallel
7655 processing: a program can be divided into a "main-level" part and one
7656 or more interrupt handlers that execute only when conditions are ripe.
7657
7658 21.1. Definitions of Terms
7659 --------------------------
7660
7661 An **interrupt** is not an object in Muddle, but rather a class of
7662 events, for example, "ticks" of a clock, garbage collections, the
7663 typing of a character at a terminal, etc.
7664
7665 An interrupt is said to **occur** when one of the events in its class
7666 takes place.
7667
7668 An **external** interrupt is one whose occurrences are signaled to
7669 Muddle by the operating system, for example, "ticks" of a clock. An
7670 **internal** interrupt is one whose occurrences are detected by Muddle
7671 itself, for example, garbage collections. Muddle can arrange for the
7672 operating system to not signal occurrences of an external interrupt to
7673 it; then, as far as Muddle is concerned, that interrupt does not
7674 occur.
7675
7676 Each interrupt has a **name** which is either a `STRING` (for example,
7677 `"GC"`, `"CHAR"`, `"WRITE"`) or an `ATOM` with that `PNAME` in a
7678 special `OBLIST`, named `INTERRUPTS!-`. (This `OBLIST` is returned by
7679 `<INTERRUPTS>`.) Certain names must always be further specified by a
7680 `CHANNEL` or a `LOCATIVE` to tell **which** interrupt by that name is
7681 meant.
7682
7683 When an interrupt occurs, the interpreter looks for an association on
7684 the interrupt's name. If there is an association, its `AVALUE` should
7685 be an `IHEADER`, which heads a list of actions to be performed. In
7686 each `IHEADER` is the name of the interrupt with which the `IHEADER`
7687 is or was associated.
7688
7689 In each `IHEADER` is an element telling whether it is disabled. If an
7690 `IHEADER` is **disabled**, then none of its actions is performed. The
7691 opposite of disabled is **enabled**. It is sometimes useful to disable
7692 an `IHEADER` temporarily, but removing its association with the
7693 interrupt's name is better than long-term disabling. There are `SUBR`s
7694 for creating an `IHEADER`, associating it with an interrupt, and later
7695 removing the association.
7696
7697 In each `IHEADER` is a **priority**, a `FIX` greater than `0` which
7698 specifies the interrupt's "importance". The processing of a
7699 higher-priority (larger-numbered) interrupt will supersede the
7700 processing of a lower-priority (smaller-numbered) interrupt until the
7701 high-priority interrupt has been handled.
7702
7703 In each `IHEADER` is a (possibly empty) list of `HANDLER`s. (This list
7704 is not a Muddle `LIST`.) Each `HANDLER` corresponds to an action to
7705 perform. There are `SUBR`s for creating a `HANDLER`, adding it to an
7706 `IHEADER`'s list, and later removing it.
7707
7708 In each `HANDLER` is a function that we will call a **handler** (in
7709 lower case), despite possible confusion, because that is really the
7710 best name for it. An **action** consists of applying a handler to
7711 arguments supplied by the interrupt system. The number and meaning of
7712 the arguments depend on the name of the interrupt. In each `HANDLER`
7713 is an element telling in which `PROCESS` the action should be
7714 performed.
7715
7716 21.2. EVENT
7717 -----------
7718
7719     <EVENT name priority which>
7720
7721 creates and returns an enabled `IHEADER` with no `HANDLER`s. The
7722 *name* may be an `ATOM` in the `INTERRUPTS` `OBLIST` or a `STRING`; if
7723 it is a `STRING`, `EVENT` does a `LOOKUP` or `INSERT` in
7724 `<INTERRUPTS>`. If there already is an `IHEADER` associated with
7725 *name*, `EVENT` just returns it, ignoring the given *priority*.
7726
7727 *which* must be given only for certain *name*s:
7728
7729 -   It must be a `CHANNEL` if and only if *name* is `"CHAR"` (or
7730     `CHAR!-INTERRUPTS`). In this case it is the input `CHANNEL` from
7731     the (pseudo-)terminal or Network socket whose received characters
7732     will cause the interrupt to occur, or the output `CHANNEL` to the
7733     pseudo-terminal or Network socket whose desired characters will
7734     cause the interrupt to occur. (See below. Pseudo-terminals are not
7735     available in the Tenex and Tops-20 versions.)
7736 -   The argument must be a `LOCATIVE` if and only if *name* is
7737     `"READ"` (or `READ!-INTERRUPTS`) or `"WRITE"` (or
7738     `WRITE!-INTERRUPTS`). In this case it specifies an object to be
7739     "monitored" for usage by (interpreted) Muddle programs (section
7740     21.8.9).
7741
7742 If the interrupt is external, Muddle arranges for the operating system
7743 to signal its occurrences.
7744
7745 21.3. HANDLER (the SUBR)
7746 ------------------------
7747
7748     <HANDLER iheader applicable process>
7749
7750 creates a `HANDLER`, adds it to the front of *iheader*'s `HANDLER`
7751 list (first action to be performed), and returns it as a value.
7752 *applicable* may be any `APPLICABLE` object that takes the proper
7753 number of arguments. (None of the arguments can be `QUOTE`d; they must
7754 all be evaluated at call time.) *process* is the `PROCESS` in which
7755 the handler will be applied, by default whatever `PROCESS` was running
7756 when the interrupt occurred.
7757
7758 The value returned by the handler is ignored, unless it is of `TYPE`
7759 `DISMISS` (`PRIMTYPE` `ATOM`), in which case none of the remaining
7760 actions in the list will be performed.
7761
7762 The processing of an interrupt's actions can terminate prematurely if
7763 a handler calls the `SUBR` `DISMISS` (see below.)
7764
7765 21.4. OFF
7766 ---------
7767
7768     <OFF iheader>
7769
7770 removes the association between *iheader* and the name of its
7771 interrupt, and then disables *iheader* and returns it. (An error
7772 occurs if there is no association.) If the interrupt is external,
7773 Muddle arranges for the operating system not to signal its
7774 occurrences.
7775
7776     <OFF name which>
7777
7778 finds the `IHEADER` associated with *name* and proceeds as above,
7779 returning the `IHEADER`. *which* must be given only for certain
7780 *names*, as for `EVENT`. Caution: if you `<OFF "CHAR" ,INCHAN>`,
7781 Muddle will become deaf.
7782
7783     <OFF handler>
7784
7785 returns *handler* after removing it from its list of actions. There is
7786 no effect on any other `HANDLER`s in the list.
7787
7788 Now that you know how to remove `IHEADER`s and `HANDLER`s from their
7789 normal places, you need to know how to put them back:
7790
7791     <EVENT iheader>
7792
7793 If *iheader* was previously disabled or disassociated from its name,
7794 `EVENT` will associate and enable it.
7795
7796     <HANDLER iheader handler>
7797
7798 If *handler* was previously removed from its list, `HANDLER` will add
7799 it to the front of *iheader*'s list of actions. Note that *process*
7800 cannot be specified.
7801
7802 21.5. IHEADER and HANDLER (the TYPEs)
7803 -------------------------------------
7804
7805 Both these `TYPE`s are of `PRIMTYPE` `VECTOR`, but they do not `PRINT`
7806 that way, since they are self-referencing. Instead they `PRINT` as
7807
7808     #type most-interesting-component
7809
7810 The contents of `IHEADER`s and `HANDLER`s can be changed by `PUT`, and
7811 the new values will then determine the behavior of Muddle.
7812
7813 Before describing the elements of these `TYPE`s in detail, here are a
7814 picture and a Pattern, both purporting to show how they look:
7815
7816     #IHEADER [name:atom or which
7817               disabled?
7818               *-----------> #HANDLER [*-----------> #HANDLER [#HANDLER []
7819               priority] <-------------*                +------*
7820                                       applicable       |      applicable
7821                                       process] <-------+      process]
7822
7823     <IHEADER <OR ATOM CHANNEL LOCATIVE>
7824              <OR '#LOSE 0 '#LOSE -1>
7825              <HANDLER HANDLER <OR HANDLER IHEADER> APPLICABLE PROCESS>
7826              FIX>
7827
7828 ### 21.5.1. IHEADER
7829
7830 The elements of an `IHEADER` are as follows:
7831
7832 1.  name of interrupt (`ATOM`, or `CHANNEL` if the name is `"CHAR"`,
7833     or `LOCATIVE` if the name is `"READ"` or `"WRITE"`)
7834 2.  non-zero if and only if disabled
7835 3.  first `HANDLER`, if any, else a zero-length `HANDLER`
7836 4.  priority
7837
7838 If you lose track of an `IHEADER`, you can get it via the association:
7839
7840 -   For `"CHAR"` interrupts, `<GET channel INTERRUPT>` returns the
7841     `IHEADER` or `#FALSE ()` if there is no association;
7842     `<EVENT "CHAR" 0 channel>` returns the `IHEADER`, creating it if
7843     there is no association.
7844 -   For `"READ"` interrupts, `<GET locative READ!-INTERRUPTS>` returns
7845     the `IHEADER` or `#FALSE ()` if there is no association;
7846     `<EVENT "READ" 0 locative>` returns the `IHEADER`, creating it if
7847     there is no association.
7848 -   For `"WRITE"` interrupts, `<GET locative WRITE!-INTERRUPTS>`
7849     returns the `IHEADER` or `#FALSE ()` if there is no association:
7850     `<EVENT "WRITE" 0 locative>` returns the `IHEADER`, creating it if
7851     there is no association.
7852 -   Otherwise, the `IHEADER` is `PUT` on the name `ATOM` with the
7853     indicator `INTERRUPT`. Thus, for example,
7854     `<GET CLOCK!-INTERRUPTS INTERRUPT>` returns the `IHEADER` for the
7855     clock interrupt or `#FALSE ()` if there is no association;
7856     `<EVENT "CLOCK" 0>` returns the `IHEADER`, creating it if there is
7857     no association.
7858
7859 ### 21.5.2. HANDLER
7860
7861 A `HANDLER` specifies a **particular** action for a **particular**
7862 interrupt. The elements of a `HANDLER` are as follows:
7863
7864 1.  next `HANDLER` if any, else a zero-length `HANDLER`
7865 2.  previous `HANDLER` or the `IHEADER` (Thus the `HANDLER`s of a
7866     given interrupt form a "doubly-linked list" chaining between each
7867     other and back to the `IHEADER`.)
7868 3.  handler to be applied (anything but `APPLICABLE` that evaluates
7869     its arguments -- the application is done not by `APPLY` but by
7870     `RUNINT`, which can take a `PROCESS` argument: see next line)
7871 4.  `PROCESS` in which the handler will be applied, or `#PROCESS 0`,
7872     meaning whatever `PROCESS` was running when the interrupt occurred
7873     (In the former case, `RUNINT` is applied to the handler and its
7874     arguments in the currently running `PROCESS`, which causes an
7875     `APPLY` in the `PROCESS` stored in the `HANDLER`, which `PROCESS`
7876     must be `RESUMABLE`. The running `PROCESS` becomes `RESUMABLE`,
7877     and the stored `PROCESS` becomes `RUNNING`, but no other `PROCESS`
7878     variables (for example `RESUMER`) are changed.)
7879
7880 21.6. Other SUBRs
7881 -----------------
7882
7883     <ON name applicable priority:fix process which>
7884
7885 is equivalent to
7886
7887     <HANDLER <EVENT name priority which>
7888              applicable process>
7889
7890 `ON` is a combination of `EVENT` and `HANDLER`: it creates (or finds)
7891 the `IHEADER`, associates and enables it, adds a `HANDLER` to the
7892 front the list (first to be performed), and returns the `HANDLER`.
7893
7894     <DISABLE iheader>
7895
7896 is effectively `<PUT iheader 2 #LOSE -1>`. Actually the `TYPE` `LOSE`
7897 is unimportant, but the `-1` signifies that *iheader* is disabled.
7898
7899     <ENABLE iheader>
7900
7901 is effectively `<PUT iheader 2 #LOSE 0>`. Actually the `TYPE` `LOSE`
7902 is unimportant, but the `0` signfies that *iheader* is enabled.
7903
7904 21.7. Priorities and Interrupt Levels
7905 -------------------------------------
7906
7907 At any given time there is a defined **interrupt level**. This is a
7908 `FIX` which determines which interrupts can really "interrupt" -- that
7909 is, cause the current processing to be suspended while their wants are
7910 satisfied. Normal, non-interrupt programs operate at an interrupt
7911 level of 0 (zero.) An interrupt is processed at an interrupt level
7912 equal to the interrupt's priority.
7913
7914 ### 21.7.1. Interrupt Processing
7915
7916 Interrupts "actually" only occur at well-defined points in time:
7917 during a call to a Subroutine, or at critical places within
7918 Subroutines (for example, during each iteration of `MAPF` on a `LIST`,
7919 which may be circular), or while a `PROCESS` is `"BLOCKED"` (see
7920 below). No interrupts can occur during garbage collection.
7921
7922 What actually happens when an enabled interrupt occurs is that the
7923 priority of the interrupt is compared with the current interrupt
7924 level, and the following is done:
7925
7926 If the priority is **greater than** the current interrupt level, the
7927 current processing is "frozen in its tracks" and processing of the
7928 action(s) specified for that interrupt begins.
7929
7930 If the priority is less than or equal to the current interrupt level,
7931 the interrupt occurrence is **queued** -- that is, the fact that it
7932 occurred is saved away for processing when the interrupt level becomes
7933 low enough.
7934
7935 When the processing of an interrupt's actions is completed, Muddle
7936 usually (1) "acts as if" the previously-existing interrupt level is
7937 restored, and processing continues on what was left off (perhaps for
7938 no time duration); and (2) "acts as if" any queued interrupt
7939 occurrences actually occurred right then, in their original order of
7940 occurrence.
7941
7942 ### 21.7.2. INT-LEVEL
7943
7944 The `SUBR` `INT-LEVEL` is used to examine and change the current
7945 interrupt level directly.
7946
7947     <INT-LEVEL>
7948
7949 simply returns the current interrupt level.
7950
7951     <INT-LEVEL fix>
7952
7953 changes the interrupt level to its argument and returns the
7954 **previously**-existing interrupt level.
7955
7956 If `INT-LEVEL` lowers the priority of the interrupt level, it does not
7957 "really" return until all queued occurrences of interrupts of higher
7958 priority than the target priority have been processed.
7959
7960 Setting the `INT-LEVEL` extremely high (for example,
7961 `<INT-LEVEL <CHTPE <MIN> FIX>>`) effectively disables all interrupts
7962 (but occurrences of enabled interrupts will still be queued).
7963
7964 If `LISTEN` or `ERROR` is called when the `INT-LEVEL` is not zero,
7965 then the typeout will be
7966
7967     LISTENING-AT-LEVEL I PROCESS p INT-LEVEL i
7968
7969 ### 21.7.3. DISMISS
7970
7971 `DISMISS` permits a handler to return an arbitrary value for an
7972 arbitrary `ACTIVATION` at an arbitrary interrupt level. The call is as
7973 follows:
7974
7975     <DISMISS value:any activation int-level:fix>
7976
7977 where only the *value* is required. If *activation* is omitted, return
7978 is to the place interrupted from, and *value* is ignored. If
7979 *int-level* is omitted, the `INT-LEVEL` prior to the current interrupt
7980 is restored.
7981
7982 21.8. Specific Interrupts
7983 -------------------------
7984
7985 Descriptions of the characteristics of particular "built-in" Muddle
7986 interrupts follow. Each is named by its `STRING` name. Expect this
7987 list to be incomplete yesterday.
7988
7989 `"CHAR"` is currently the most complex built-in interrupt, because it
7990 serves duty in several ways. These different ways will be described in
7991 several different sections. All ways are concerned with characters or
7992 machine words that arrive or depart at unpredictable times, because
7993 Muddle is communicating with a person or another processor. Each
7994 `"CHAR"` `IHEADER` has a `CHANNEL` for the element that names the
7995 interrupt, and the mode of the `CHANNEL` tells what kinds of `"CHAR"`
7996 interrupts occur to be handled through that `IHEADER`.
7997
7998 1.  If the `CHANNEL` is for `INPUT`, "CHAR" occurs every time an
7999     "interesting" character (see below) is received from the
8000     `CHANNEL`'s real terminal, or any character is received from the
8001     `CHANNEL`'s pseudo-terminal, or a character or word is received
8002     from the `CHANNEL`'s Network socket, or indeed (in the ITS
8003     version) the operating system generates an interrupt for any
8004     reason.
8005 2.  If the `CHANNEL` is for output to a pseudo-terminal or Network
8006     socket, `"CHAR"` occurs every time a character or word is wanted.
8007 3.  If the `CHANNEL` is for output to a terminal, `"CHAR"` occurs
8008     every time a line-feed character is output or (in the ITS version)
8009     the operating system generates a screen-full interrupt for the
8010     terminal.
8011
8012 ### 21.8.1. "CHAR" received
8013
8014 A handler for an input `"CHAR"` interrupt on a real terminal must take
8015 two arguments: the `CHARACTER` which was typed, and the `CHANNEL` on
8016 which it was typed.
8017
8018 In the ITS version, the "interesting" characters are those "enabled
8019 for interrupts" on a real terminal, namely `^@` through `^G`, `^K`
8020 through `^_`, and `DEL` (that is, ASCII codes 0-7, 13-37, and 177
8021 octal.)
8022
8023 In the Tenex and Tops-20 versions, the operating system can be told
8024 which characters typed on a terminal should cause this interrupt to
8025 occur, by calling the `SUBR` `ACTIVATE-CHARS` with a `STRING` argument
8026 containing those characters (no more than six, all with ASCII codes
8027 less than 33 octal). If called with no argument, `ACTIVATE-CHARS`
8028 returns a `STRING` containing the characters that currently interrupt.
8029 Initially, only `^G`, `^S`, and `^O` interrupt.
8030
8031 An initial Muddle already has `"CHAR"` enabled on `,INCHAN` with a
8032 priority 8 (eight), the `SUBR` `QUITTER` for a handler to run in
8033 `#PROCESS 0` (the running `PROCESS`); this is how `^G` and `^S` are
8034 processed. In addition, every time a new `CHANNEL` is `OPEN`ed in
8035 `"READ"` mode to a terminal, a similar `IHEADER` and `HANDLER` are
8036 associated with that new `CHANNEL` automatically. These
8037 automatically-generated `IHEADER`s and `HANDLER`s use the standard
8038 machinery, and they can be `DISABLE`d or `OFF`ed at will. **However**,
8039 the `IHEADER` for `,INCHAN` should not be `OFF`ed: Muddle knows that
8040 `$` is typed only by an interrupt!
8041
8042 Example: the following causes the given message to be printed out
8043 whenever a `^Y` is typed on `.INCHAN`:
8044
8045     <SET H <HANDLER <GET .INCHAN INTERRUPT>
8046          #FUNCTION ((CHAR CHAN)
8047           #DECL ((VALUE) ANY (CHAR) CHARACTER (CHAN) CHANNEL)
8048           <AND <==? .CHAR !\^Y>
8049                <PRINC " [Some of the best friends are ^Ys.] ">>)>>$
8050     #HANDLER #FUNCTION **CHAR CHAN) ...)
8051     <+ 2 ^Y [Some of my best friends are ^Ys.] 2>$
8052     4
8053     <OFF .H>$
8054     #HANDLER #FUNCTION (...)
8055
8056 Note that occurrences of `"CHAR"` do **not** wait for the `$` to be
8057 typed, and the interrupting character is omitted from the input
8058 stream.
8059
8060 A `"CHAR"` interrupt can also be associated with an input `CHANNEL`
8061 open to a Network socket (`"NET"` device). A handler gets applied to a
8062 `NETSTATE` array (which see) and the `CHANNEL`.
8063
8064 In the ITS version, a `"CHAR"` interrupt can also be associated with
8065 an input `CHANNEL` open to a pseudo-terminal ("STY" device and
8066 friends). An interrupt occurs when a character is available for input.
8067 These interrupts are set up in exactly the same way as real-terminal
8068 interrupts, except that a handler gets applied to only **one**
8069 argument, the `CHANNEL`. Pseudo-terminal are not available in the
8070 Tenex and Tops-20 versions.
8071
8072 For any other flavor of ITS channel interrupt, a handler gets applied
8073 to only **one** argument, the `CHANNEL`.
8074
8075 ### 21.8.2. "CHAR" wanted
8076
8077 A `"CHAR"` interrupt can be associated with an output `CHANNEL` open
8078 to a Network socket (`"NET"` device). A handlers gets applied to a
8079 `NETSTATE` array (which see) and the `CHANNEL`.
8080
8081 In the ITS version, a `"CHAR"` interrupt can also be associated with
8082 an output `CHANNEL` open to a pseudo-terminal (`"STY"` device and
8083 friends). An interrupt occurs when the program at the other end needs
8084 a character (and the operating-system buffer is empty). A handler gets
8085 applied to one argument, the `CHANNEL`. Pseudo-terminals are not
8086 available in the Tenex and Tops-20 versions.
8087
8088 ### 21.8.3. "CHAR" for new line
8089
8090 A handler for an output `"CHAR"` interrupt on a real terminal must
8091 take **one or two** arguments (using `"OPTIONAL"` or `"TUPLE"`): if
8092 two arguments are supplied by the interrupt system, they are the line
8093 number (`FIX`) and the `CHANNEL`, respectively, and the interrupt is
8094 for a line-feed; if only one argument is supplied (only in the ITS
8095 version), it is the `CHANNEL`, and the interrupt is for a full
8096 terminal screen. Note: the supplied line number comes from the
8097 `CHANNEL`, and it may not be accurate if the program alters it in
8098 subtle ways, for example, via `IMAGE` calls or special control
8099 characters. (The program can compensate by putting the proper line
8100 number into the `CHANNEL`.)
8101
8102 ### 21.8.4. "GC"
8103
8104 `"GC"` occurs just **after** every garbage collection. Enabling this
8105 interrupt is the only way a program can know that a garbage collection
8106 has occurred. A handler for `"GC"` takes three arguments. The first is
8107 a FLOAT indicating the number of seconds the garbage collection took.
8108 The second argument is a FIX indicating the cause of the garbage
8109 collection, as follows (chapter 22):
8110
8111 0.  Program called GC.
8112 1.  Movable storage was exhausted.
8113 2.  Control stack overflowed.
8114 3.  Top-level LVALs overflowed.
8115 4.  GVAL vector overflowed.
8116 5.  TYPE vector overflowed.
8117 6.  Immovable garbage-collected storage was exhausted.
8118 7.  Internal stack overflowed.
8119 8.  Both control and internal stacks overflowed (rare).
8120 9.  Pure storage was exhausted.
8121 10. Second, exhaustive garbage collection occurred.
8122
8123 The third argument is an ATOM indicating what initiated the garbage
8124 collection: `GC-READ`, `BLOAT`, `GROW`, `LIST`, `VECTOR`, `SET`,
8125 `SETG`, `FREEZE`, `GC`, `NEWTYPE`, `PURIFY`, `PURE-PAGE-LOADER` (pure
8126 storage was exhausted), or `INTERRUPT-HANDLER` (stack overflow,
8127 unfortunately).
8128
8129 ### 21.8.5. "DIVERT-AGC"
8130
8131 `"DIVERT-AGC"` ("Automatic Garbage Collection") occurs just **before**
8132 a deferrable garbage collection that is needed because of exhausted
8133 movable garbage-collected storage. Enabling this interrupt is the only
8134 way a program can know that a garbage collection is about to occur. A
8135 handler takes two arguments: A `FIX` telling the number of machine
8136 words needed and an `ATOM` telling what initiated the garbage
8137 collection (see above). If it wishes, a handler can try to prevent a
8138 garbage collection by calling `BLOAT` with the `FIX` argument. If the
8139 pending request for garbage-collected storage cannot then be
8140 satisfied, a garbage collection occurs anyway. `AGC-FLAG` is `SET` to
8141 `T` while the handler is running, so that new storage requests do not
8142 try to cause a garbage collection.
8143
8144 ### 21.8.6. "CLOCK"
8145
8146 `"CLOCK"`, when enabled, occurs every half second (the ITS
8147 "slow-clock" tick.) It is not available in the Tenex or Tops-20
8148 versions. It wants handlers which take no arguments. Example:
8149
8150     <ON "CLOCK" <FUNCTION () <PRINC "TICK ">> 1>
8151
8152 ### 21.8.7. "BLOCKED"
8153
8154 `"BLOCKED"` occurs whenever **any** `PROCESS` (not only the `PROCESS`
8155 which may be in a `HANDLER`) starts waiting or terminal input: that
8156 is, an occurrence indicates that somewhere, somebody did a `READ`,
8157 `READCHR`, `NEXTCHR`, `TYI`, etc. to a console. The handler for a
8158 `"BLOCKED"` interrupt should take one argument, namely the `PROCESS`
8159 which started waiting (which will also be the `PROCESS` in which the
8160 handler runs, if no specific one is in the `HANDLER`).
8161
8162 Example: the following will cause Muddle to acquire a `*` prompting
8163 character.
8164
8165     <ON "BLOCKED" #FUNCTION ((IGNORE) <PRINC !\*>) 5>
8166
8167 ### 21.8.8. "UNBLOCKED"
8168
8169 `"UNBLOCKED"` occurs whenever a `$` (`ESC`) is typed on a terminal if
8170 a program was hanging and waiting for input, or when a TYI call (which
8171 see) is satisfied. A handler takes one argument: the `CHANNEL` via
8172 which the `$` or character is input.
8173
8174 ### 21.8.9. "READ" and "WRITE"
8175
8176 `"READ"` and `"WRITE"` are associated with read or write references to
8177 Muddle objects. These interrupts are often called "monitors", and
8178 enabling the interrupt is often called "monitoring" the associated
8179 object. A "read reference" to an `ATOM`'s local value includes
8180 applying `BOUND?` or `ASSIGNED?` to the `ATOM`; similarly for a global
8181 value and `GASSIGNED?`. If the `INT-LEVEL` is too high when `"READ"`
8182 or `"WRITE"` occurs, an error occurs, because occurrences of these
8183 interrupts cannot be queued.
8184
8185 Monitors are set up with `EVENT` or `ON`, using a locative to the
8186 object being monitored as the extra *which* argument, just as a
8187 `CHANNEL` is given for `"CHAR"`. A handler for `"READ"` takes two
8188 arguments: the locative and the `FRAME` of the function application
8189 that make the reference. A handler for `"WRITE"` takes three
8190 arguments: the locative, the new value, and the `FRAME`. For example:
8191
8192     <SET A (1 2 3)>$
8193     (1 2 3)
8194     <SET B <AT .A 2>>$
8195     #LOCL 2
8196     <ON "WRITE" <FUNCTION (OBJ VAL FRM)
8197             #DECL ((VALUE VAL ANY (OBJ) LOCATIVE (FRM) FRAME)
8198             <CRLF>
8199             <PRINC "Program changed ">
8200             <PRIN1 .OBJ>
8201             <PRINC " to ">
8202             <PRIN1 .VAL>
8203             <PRINC " via ">
8204             <PRINC .FRM>
8205             <CRLF>>
8206             4 0 .B>$
8207     #HANDLER FUNCTION (...)
8208     <1 .A 10>$
8209     (10 2 3)
8210     <2 .A 20>$
8211     Program changed #LOCL 2 to 20 via #FRAME PUT
8212     (10 20 3)
8213     <OFF "WRITE" .B>$
8214     #IHEADER #LOCL 20
8215
8216 ### 21.8.10. "SYSDOWN"
8217
8218 `"SYSDOWN"` occurs when a system-going-down or system-revived signal
8219 is received from ITS. It is not available in the Tenex or Tops-20
8220 versions. If no `IHEADER` is associated and enabled, a warning message
8221 is printed on the terminal. A handler takes one argument: a `FIX`
8222 giving the number of thirtieths of a second until the shutdown (-1 for
8223 a reprieve).
8224
8225 ### 21.8.11. "ERROR"
8226
8227 In an effort to simplify error handling by programs, Muddle has a
8228 facility allowing errors to be handled like interrupts. `SETG`ing
8229 `ERROR` to a user function is a distasteful method, not safe if any
8230 bugs are around. An `"ERROR"` interrupt wants a handler that takes any
8231 number of arguments, via `"TUPLE"`. When an error occurs, handlers are
8232 applied to the `FRAME` of the `ERROR` call and the `TUPLE` of `ERROR`
8233 arguments. If a given handler "takes care of the error", it can
8234 `ERRET` with a value from the `ERROR` `FRAME`, after having done
8235 `<INT-LEVEL 0>`. If no handler takes care of the error, it falls into
8236 the normal `ERROR`.
8237
8238 If an error occurs at an `INT-LEVEL` greater than or equal to that of
8239 the `"ERROR"` interrupt, real `ERROR` will be called, because
8240 `"ERROR"`interrupts cannot be queued.
8241
8242 ### 21.8.12. "IPC"
8243
8244 `"IPC"` occurs when a message is received on the ITS IPC device
8245 (chapter 23). It is not available in the Tenex and Tops-20 versions.
8246
8247 ### 21.8.13. "INFERIOR"
8248
8249 `"INFERIOR"` occurs when an inferior ITS process interrupts the Muddle
8250 process. It is not available in the Tenex and Tops-20 versions. A
8251 handler takes one argument: A `FIX` between `0` and `7` inclusive,
8252 telling which inferior process is interrupting.
8253
8254 ### 21.8.14. "RUNT and "REALT"
8255
8256 These are not available in the Tenex and Tops-20 versions.
8257
8258 `"RUNT"`, if enabled, occurs **once**, *N* seconds of Muddle running
8259 time (CPU time) after calling `<RUNTIMER N:fix-or-float>`, which
8260 returns its argument. A handler takes no arguments. If `RUNTIMER` is
8261 called with no argument, it returns a `FIX`, the number of run-time
8262 seconds left until the interrupt occurs, or `#FALSE ()` if the
8263 interrupt is not going to occur.
8264
8265 `"REALT"`, if enabled, occurs **every** *N* seconds of real-world time
8266 after calling `<REALTIMER N:fix-or-float>`, which returns its
8267 argument. A handler takes no arguments. `<REALTIMER 0>` tells the
8268 operating system not to generate real-time interrupts. If `REALTIMER`
8269 is called with no argument, it returns a `FIX`, the number of
8270 real-time seconds given in the most recent call to `REALTIMER` with an
8271 argument, or `#FALSE ()` if `REALTIMER` has not been called.
8272
8273 ### 21.8.15. "Dangerous" Interrupts
8274
8275 `"MPV"` ("memory protection violation") occurs if Muddle tries to
8276 refer to a storage address not in its address space. `"PURE"` occurs
8277 if Muddle tries to alter read-only storage. `"ILOPR"` occurs if Muddle
8278 executes and illegal instruction ("operator"). `"PARITY"` occurs if
8279 the CPU detects a parity error in Muddle's address space. All of these
8280 require a handler that takes one argument: the address (`TYPE` `WORD`)
8281 following the instruction that was being executed at the time.
8282
8283 `"IOC"` occurs if Muddle tries to deal illegally with an I/O channel.
8284 A handler must take two arguments: a three-element `FALSE` like one
8285 that `OPEN` might return, and the `CHANNEL` that got the error.
8286
8287 Ideally these interrupts should never occur. In fact, in the Tenex and
8288 Tops-20 versions, these interrupts always go to the superior operating
8289 system process instead of to Muddle. In the ITS version, if and when a
8290 "dangerous" interrupt does occur:
8291
8292 -   If no `IHEADER` is associated with the interrupt, then the
8293     interrupt goes to the superior operating system process.
8294 -   If an `IHEADER` is associated but disabled, the error
8295     `DANGEROUS-INTERRUPT-NOT-HANDLED` occurs (`FILE-SYSTEM-ERROR` for
8296     \`"IOC").
8297 -   If an `IHEADER` is associated and enabled, but the `INT-LEVEL` is
8298     too high, the error `ATTEMPT-TO-DEFER-UNDEFERABLE-INTERRUPT`
8299     occurs.
8300
8301 21.9. User-Defined Interrupts
8302 -----------------------------
8303
8304 If the interrupt name given to `EVENT` or `ON` is **not** one of the
8305 standard predefined interrupts of Muddle, they will gleefully create
8306 an `ATOM` in `<INTERRUPTS>` and an associated `IHEADER` anyway, making
8307 the assumption that you are setting up a "program-defined" interrupt.
8308
8309 Program-defined interrupts are made to occur by applying the `SUBR`
8310 `INTERRUPT`, as in
8311
8312     <INTERRUPT name arg1 ... argN>
8313
8314 where *name* is a `STRING`, `ATOM` or `IHEADER`, and *arg1* through
8315 *argN* are the arguments wanted by the handlers for the interrupt.
8316
8317 If the interrupt specified by `INTERRUPT` is enabled, `INTERRUPT`
8318 returns `T`; otherwise it returns `#FALSE ()`. All the usual priority
8319 and queueing rules hold, so that even if `INTERRUPT` returns `T`, it
8320 is possible that nothing "really happened" (yet).
8321
8322 `INTERRUPT` can also be used to cause "artificial" occurrences of
8323 standard predefined Muddle interrupts.
8324
8325 Making a program-defined interrupt occur is similar to calling a
8326 handler directly, but there are differences. The value returned by a
8327 handler is ignored, so side effects must be used in order to
8328 communicate information back to the caller, other than whether any
8329 handler ran or will run. One good use for a program-defined interrupt
8330 is to use the priority and queueing machinery of `INT-LEVEL` to
8331 control the execution of functions that must not run concurrently. For
8332 example, if a `"CHAR"` handler just deposits characters in a buffer,
8333 then a function to process the buffered characters should probably run
8334 at a higher priority level -- to prevent unpredictable changes to the
8335 buffer during the processing -- and it is natural to invoke the
8336 processing with `INTERRUPT`.
8337
8338 In more exotic applications, `INTERRUPT` can signal a condition to be
8339 handled by an unknown number of independent and "nameless" functions.
8340 The functions are "nameless" because the caller doesn't know their
8341 name, only the name of the interrupt. This programming style is
8342 modular and event-driven, and it is one way of implementing
8343 "heuristic" algorithms. In addition, each `HANDLER` has a `PROCESS` in
8344 which to run its handler, and so the different handlers for a given
8345 condition can do their thing in different environments quite easily,
8346 with less explicit control than when using `RESUME`.
8347
8348 21.10. Waiting for Interrupts
8349 -----------------------------
8350
8351 ### 21.10.1. HANG
8352
8353     <HANG pred>
8354
8355 hangs interruptibly, without consuming any CPU time, potentially
8356 forever. `HANG` is nice for a program that cannot do anything until an
8357 interrupt occurs. If the optional *pred* is given, it is evaluated
8358 every time an interrupt occurs and is dismissed back into the `HANG`;
8359 if the result of evaluation is not `FALSE`, `HANG` unhangs and returns
8360 it as a value. If *pred* is not given, there had better be a named
8361 `ACTIVATION` somewhere to which a handler can return.
8362
8363 ### 21.10.2. SLEEP
8364
8365     <SLEEP time:fix-or-float pred>
8366
8367 suspends execution, interruptibly, without consuming any CPU time, for
8368 *time* seconds, where *time* is non-negative, and then returns `T`.
8369 *pred* is the same as for `HANG`.
8370
8371 Chapter 22. Storage Management
8372 ==============================
8373
8374 The reason this chapter comes so late in this document is that, except
8375 for special cases, Muddle programs have their storage needs handled
8376 automatically. There is usually no need even to consider storage
8377 management, except as it affects efficiency (chapter 24). This chapter
8378 gives some explanation of why this is so, and covers those special
8379 means by which a program can assume control of storage management.
8380
8381 The Muddle address space is divided into five parts, which are usually
8382 called
8383
8384 1.  movable garbage-collected space,
8385 2.  immovable space (both garbage-collected and not),
8386 3.  user pure/page space,
8387 4.  pure-`RSUBR` mapping space, and
8388 5.  internal storage.
8389
8390 Internal storage occupies both the highest and lowest addresses in the
8391 address space, and its size never changes as Muddle executes. The
8392 other spaces can vary in size according to the needs of the executing
8393 program. Generally the interpreter allocates a contiguous set of
8394 addresses for each space, and each space gradually fills up as new
8395 objects are created and as disk files are mapped in. The action taken
8396 when space becomes full varies, as discussed below.
8397
8398 22.1. Movable Garbage-collected Storage
8399 ---------------------------------------
8400
8401 Most storage used explicitly by Muddle programs is obtained from a
8402 pool of free storage managed by a "garbage collector". Storage is
8403 obtained from this pool by the `SUBR`s which construct objects. When a
8404 `SUBR` finds that the pool of available storage is exhausted, it
8405 automatically calls the garbage collector.
8406
8407 The garbage collector has two algorithms available to it: the
8408 "copying" algorithm, which is used by default, and the "mark-sweep"
8409 algorithm. Actually, one often speaks of two separate garbage
8410 collectors, the "copying" one and the "mark-sweep" one, because each
8411 is an independent module that is mapped in to the interpreter's
8412 internal storage from disk only during garbage collection. For
8413 simplicity, this document speaks of "the" garbage collector, which has
8414 two algorithms.
8415
8416 The garbage collector examines the storage pool and **marks** all the
8417 objects there, separating them into two classes: those which cannot
8418 possibly be referenced by a program, and those which can. The
8419 "copying" algorithm then copies the latter into one compact section of
8420 the pool, and the remainder of the pool is made available for newly
8421 constructed objects. The "mark-sweep" algorithm, instead, puts all
8422 objects in the former class (garbage) into "free lists", where the
8423 object-construction `SUBR`s can find them and re-use their storage.
8424
8425 If the request for more storage still cannot be satisfied from
8426 reclaimed storage, the garbage collector will attempt to obtain more
8427 total storage from the operating system under which Muddle runs.
8428 (Also, if there is a gross superfluity of storage space, the garbage
8429 collector will politely return some storage to the operating system.)
8430 Only when the total system resources are exhausted will you finally
8431 lose.
8432
8433 Thus, if you just "forget about" an object, that is, lose all possible
8434 means of referencing it, its storage is automatically reclaimed.
8435 "Object" in this context includes that stack-structured storage space
8436 used in `PROCESS`es for functional application.
8437
8438 ### 22.1.1. Stacks and Other Internal Vectors
8439
8440 Control stacks are used in Muddle to control the changes in
8441 environment caused by calling and binding. Each active `PROCESS` has
8442 its own control stack. On this stack are stored `LVAL`s for `ATOM`s;
8443 `PRIMTYPE` `TUPLE`s, which are otherwise like `VECTOR`s; `PRIMTYPE`
8444 `FRAME`s, which are generated by calling Subroutines; and
8445 `ACTIVATION`s, which are generated by calling `FUNCTION`s with named
8446 `ACTIVATION`s, `PROG`, and `REPEAT`. `TAG` and `LLOC` can make `TAG`s
8447 and `LOCD`s (respectively) that refer to a specific place on a
8448 specific control stack. (`LEGAL?` returns `T` if and only if the
8449 portion of the control stack in which its argument is found or to
8450 which its argument refers is still active, or if its argument doesn't
8451 care about the control stack. The garbage collector may change a
8452 non-`LEGAL?` object to `TYPE` `ILLEGAL` before reclaiming it.) As the
8453 word "stack" implies, things can be put on it and removed from it at
8454 only one end, called the top. It has a maximum size (or depth), and
8455 attempting to put too many things on it will cause overflow. A stack
8456 is stored like a `VECTOR`, and it must be `GROW`n if and when it
8457 overflows.
8458
8459 A control stack is actually two stacks in one. One section is used for
8460 "top-level" `LVAL`s -- those `SET` while the `ATOM` is not bound by
8461 any active Function's argument `LIST` or Subroutine's `SPECIAL`
8462 binding -- and the other section is used for everything else. Either
8463 section can overflow, of course. The top-level-`LVAL` section is below
8464 the other one, so that a top-level `LVAL` will be found only if the
8465 `ATOM` is not currently bound elsewhere, namely in the other section.
8466
8467 Muddle also has an internal stack, used for calling and temporary
8468 storage within the interpreter and compiled programs. It too is stored
8469 like a `VECTOR` and can overflow. There are other internal vectors
8470 that can overflow: the "global vector" holds pairs ("slots") of
8471 `ATOM`s and corresponding `GVAL`s ("globally bound" or `GBOUND?` means
8472 that the `ATOM` in question is in this vector, whether or not it
8473 currently has a global value), and the "`TYPE` vector" holds `TYPE`
8474 names (predefined and `NEWTYPE`s) and how they are to be treated.
8475
8476 22.2. Immovable Storage
8477 -----------------------
8478
8479 ### 22.2.1. Garbage-collected: FREEZE
8480
8481 In very special circumstances, such as debugging `RSUBR`s, you may
8482 need to prevent an object from being moved by the garbage collector.
8483 `FREEZE` takes one argument, of `PRIMTYPE` `VECTOR`, `UVECTOR`,
8484 `STRING`, `BYTES` or `TUPLE`. It copies its argument into non-moving
8485 garbage-collected space. `FREEZE` returns the copy `CHTYPE`d to its
8486 `PRIMTYPE`, except in the case of a `TUPLE`, which is changed to a
8487 `VECTOR`.
8488
8489 ### 22.2.2. Non-garbage-collected: STORAGE (the PRIMTYPE)
8490
8491 An object of `PRIMTYPE` `STORAGE` is really a frozen `UVECTOR` whose
8492 `UTYPE` is of `PRIMTYPE` `WORD`, but it is always pointed to by
8493 something internal to Muddle and thus is never garbage-collectible.
8494 The use of `FREEZE` is always preferable, except when for historical
8495 reasons a `STORAGE` is necessary.
8496
8497 22.3. Other Storage
8498 -------------------
8499
8500 User pure/page space serves two purposes. First, when a user program
8501 `PURIFY`s (see below) Muddle objects, they are copied into this space.
8502 Second, so-called hand-crafted `RSUBR`s (assembled but not compiled)
8503 can call on the interpreter to map pages of disk files into this space
8504 for arbitrary purposes.
8505
8506 Pure-`RSUBR` mapping space is used by the interpreter to dynamically
8507 map pages of pure compiled programs into and out of the Muddle address
8508 space. Pure code can refer to impure storage through the "transfer
8509 vector", another internal vector. This space is the most vulnerable to
8510 being compressed in size by the long-term growth of other spaces.
8511
8512 Internal storage has both pure and impure parts. The interpreter
8513 program itself is pure and sharable, while impure storage is used for
8514 internal pointers, counters, and flags, for example, pointers to the
8515 boundaries of other spaces. In the pure part of this space are most of
8516 the `ATOM`s in an initial Muddle, along with their `OBLIST` buckets
8517 (`LIST`s) and `GVAL` slots (a pure extension of the global vector),
8518 where possible. A `SET` or `SETG` of a pure `ATOM` automatically
8519 impurifies the `ATOM` and as much of its `OBLIST` bucket as needs to
8520 be impure.
8521
8522 22.4. Garbage Collection: Details
8523 ---------------------------------
8524
8525 When either of the garbage-collected spaces (movable or immovable)
8526 becomes full, Muddle goes through the following procedure:
8527
8528 1.  A `"DIVERT-AGC"` interrupt occurs if the garbage collection can be
8529     deferred temporarily by shifting boundaries between storage spaces
8530     slightly. The interrupt handler may postpone a garbage collection
8531     by moving boundaries itself with a call to `BLOAT` (below).
8532 2.  The garbage collector begins execution. The "copying" algorithm
8533     creates an inferior operating-system process (named `AGC` in the
8534     ITS version) whose address space is used to hold the new copies of
8535     non-garbage objects. Muddle accesses the inferior's address space
8536     through two pages ("frontier" and "window") in its internal space
8537     that are shared with the inferior. If the garbage collection
8538     occurred because movable garbage-collected space was exhausted,
8539     then the "mark-sweep" algorithm might be used instead (see below)
8540     and no inferior process is created.
8541 3.  The garbage collector marks and moves all objects that can
8542     possibly be referenced hereafter. It begins with the `<MAIN>`
8543     `PROCESS` and the currently running `PROCESS` `<ME>`, considered
8544     as vectors containing the control stacks, object pointers in live
8545     registers, etc. Every object in these "`PROCESS` vectors" is
8546     marked "accessible", and every element of these objects (bindings,
8547     etc.), and so on recursively. The "copying" algorithm moves
8548     objects into the inferior process's address space as it marks
8549     them.
8550 4.  If the garbage collection is "exhaustive" -- which is possible
8551     only in the "copying" algorithm -- then both the chain of
8552     associations and top-level local/global bindings are examined
8553     thoroughly, which takes more time but is more likely to uncover
8554     garbage therein. In a normal garbage collection these constructs
8555     are not treated specially.
8556 5.  Finally, the "mark-sweep" algorithm sweeps through the storage
8557     space, adding unmarked objects to the internal free lists for
8558     later re-use. The "copying" algorithm maps the inferior process's
8559     address space into Muddle's own, replacing old garbagey with the
8560     new compact storage, and the inferior process is destroyed.
8561
8562 22.5 GC
8563 -------
8564
8565     <GC min:fix exh?:false-or-any ms-freq:fix>
8566
8567 causes the garbage collector to run and returns the total number of
8568 words of storage reclaimed. All of its arguments are optional: if they
8569 are not supplied, a call to GC simply causes a "copying" garbage
8570 collection.
8571
8572 If *min* is explicitly supplied as an argument, a garbage-collection
8573 parameter is changed permanently before the garbage collector runs.
8574 *min* is the smallest number of words of "free" (unclaimed, available
8575 for use) movable garbage-collected storage the garbage collector will
8576 be satisfied with having after it is done. Initially it is 8192 words.
8577 If the total amount of reclaimed storage is less than *min*, the
8578 garbage collector will ask the operating system for enough storage (in
8579 1024 word blocks) to make it up. N.B.: the system may be incivil
8580 enough not to grant the request; in that case, the garbage collector
8581 will be content with what it has, **unless** that is not enough to
8582 satisfy a **pending** request for storage. Then it will inform you
8583 that it is losing. A large *min* will result in fewer total garbage
8584 collections, but they will take longer since the total quantity of
8585 storage to be dealt with will generally be larger. Smaller *min*s
8586 result in shorter, more frequent garbage collections.
8587
8588 22.6. BLOAT
8589 -----------
8590
8591 `BLOAT` is used to cause a temporary expansion of the available
8592 storage space with or without changing the garbage-collection
8593 parameters. `BLOAT` is particularly useful for avoiding unnecessary
8594 garbage collections when loading a large file. It will cause (at most)
8595 one garbage collection, at the end of which the available storage will
8596 be at least the amount specified in the call to `BLOAT`. (Unless, of
8597 course, the operating system is cranky and will not provide the
8598 storage. Then you will get an error. `<ERRET 1>` from this error will
8599 cause the `BLOAT` to return `1`, which usually just causes you to lose
8600 at a later time -- unless the operating system feels nicer when the
8601 storage is absolutely necessary.)
8602
8603 A call to BLOAT looks like this:
8604
8605     <BLOAT fre stk lcl glb typ sto pstk
8606            min plcl pglb ptyp imp pur dpstk dstk>
8607
8608 where all arguments on the first line above are `FIX`, optional (`0`
8609 by default), and indicate the following:
8610
8611 -   *fre*: number of words of free movable storage desired (for
8612     `LIST`s, `VECTOR`s, `ATOM`s, etc.)
8613 -   *stk*: number of words of free control-stack space desired (for
8614     functional applications and binding of `ATOM`s)
8615 -   *lcl*: number of new top-level `LVAL`s for which to leave space
8616     (`SET`s of `ATOM`s which are not currently bound)
8617 -   *glb*: number of new `GVAL`s for which to leave space (in the
8618     global vector)
8619 -   *typ*: number of new `TYPE` definitions for which to leave space
8620     (in the `TYPE` vector)
8621 -   *sto*: number of words of immovable garbage-collected storage
8622     desired
8623 -   *pstk*: number of words of free internal-stack space desired (for
8624     `READ`ing large `STRING`s, and calling routines within the
8625     interpreter and compiled programs)
8626
8627 Arguments on the second line are also `FIX` and optional, but they set
8628 garbage-collection parameters permanently, as follows:
8629
8630 -   *min*: as for `GC`
8631 -   *plcl*: number of slots for `LVAL`s added when the space for
8632     top-level `LVAL`s is expanded (initially 64)
8633 -   *pglb*: number of slots for `GVAL`s added when the global vector
8634     is grown (initially 64)
8635 -   *ptyp*: number of slots for `TYPE`s added when the `TYPE` vector
8636     is grown (initially 32)
8637 -   *imp*: number of words of immovable garbage-collected storage
8638     added when it is expanded (initially 1024)
8639 -   *pur*: number of words reserved for pure compiled programs, if
8640     possible (initially 0)
8641 -   *dpstk*: most desirable size for the internal stack, to prevent
8642     repeated shrinking and `GROW`ing (initially 512)
8643 -   *dstk*: most desirable size for the control stack (initially 4096)
8644
8645 `BLOAT` returns the actual number of words of free movable
8646 garbage-collected storage available when it is done.
8647
8648 22.7. BLOAT-STAT
8649 ----------------
8650
8651 `BLOAT-STAT` can be used with `BLOAT` to "tune" the garbage collector
8652 to particular program requirements.
8653
8654     <BLOAT-STAT length-27:uvector>
8655
8656 fills the *uvector* with information about the state of storage of
8657 Muddle. The argument should be a `UVECTOR` of length 27 and `UTYPE`
8658 `FIX`. If `BLOAT-STAT` does not get an argument, it will provide its
8659 own `UVECTOR`. The information returned is as follows: the first 8
8660 elements indicate the number of garbage collections that are
8661 attributable to certain causes, and the other 19 give information
8662 about certain areas of storage. In detail:
8663
8664 1.  number of garbage collections caused by exhaustion of movable
8665     garbage-collected storage
8666 2.  ditto by overflow of control stack(s)
8667 3.  ditto by overflow of top-level-`LVAL` section of control stack(s)
8668 4.  ditto by overflow of global vector
8669 5.  ditto by overflow of `TYPE` vector
8670 6.  ditto by exhaustion of immovable garbage-collected storage
8671 7.  ditto by overflow of internal stack
8672 8.  ditto by overflow of both stacks at the same time (rare)
8673
8674 9.  number of words of movable storage
8675 10. number of words of movable storage used since last `BLOAT-STAT`
8676 11. maximum number of words of movable storage ever existing
8677 12. number of words of movable storage used since Muddle began running
8678 13. maximum size of control stack
8679 14. number of words on control stack in use
8680 15. maximum size of control stack(s) ever reached
8681 16. number of slots for top-level `LVAL`s
8682 17. number of top-level `LVAL`s existing
8683 18. number of slots for `GVAL`s in global vector
8684 19. number of `GVAL`s existing
8685 20. number of slots for `TYPE`s in `TYPE` vector
8686 21. number of `TYPE`s existing
8687 22. number of words of immovable garbage-collected storage
8688 23. number of words of immovable storage unused
8689 24. size of largest unused contiguous immovable-storage block
8690 25. number of words on internal stack
8691 26. number of words on internal stack in use
8692 27. maximum size of internal stack ever reached
8693
8694 22.8. GC-MON
8695 ------------
8696
8697     <GC-MOND pred>
8698
8699 ("garbage-collector monitor") determines whether or not the
8700 interpreter will hereafter print information on the terminal when a
8701 garbage collection starts and finishes, according to whether or not
8702 its argument is true. It returns the previous state. Calling it with
8703 no argument returns the current state. The initial state is false.
8704
8705 When typing is enabled, the "copying" garbage collector prints, when
8706 it starts:
8707
8708     GIN reason subr-that-caused:atom
8709
8710 and, when it finishes:
8711
8712     GOUT seconds-needed
8713
8714 The "mark-sweep" garbage collector prints `MSGIN` and `MSGOUT` instead
8715 of `GIN` and `GOUT`.
8716
8717 22.9. Related Subroutines
8718 -------------------------
8719
8720 Two `SUBR`s, described next, use only part of the garbage-collector
8721 algorithm, in order to find all pointers to an object. `GC-DUMP` and
8722 `GC-READ`, as their names imply, also use part in order to translate
8723 between Muddle objects and binary representation thereof.
8724
8725 ### 22.9.1. SUBSTITUTE
8726
8727     <SUBSTITUTE new:any old:any>
8728
8729 returns *old*, after causing a miniature garbage collection to occur,
8730 during which **all** references to *old* are changed so as to refer to
8731 *new*. Neither argument can be of `PRIMTYPE` `STRING` or `BYTES` or
8732 `LOCD` or live on the control stack, unless both are of the same
8733 `PRIMTYPE`. One `TYPE` name cannot be substituted for another. One of
8734 the few legitimate uses for it is to substitute the "right" `ATOM` for
8735 the "wrong" one, after `OBLIST`s have been in the wrong state. This is
8736 more or less the way `ATOM`s are impurified. It is also useful for
8737 unlinking `RSUBR`s. `SUBSTITUTE` returns *old* as a favor: unless you
8738 hang onto *old* at that point, it will be garbage-collected.
8739
8740 22.9.2 PURIFY
8741 -------------
8742
8743     <PURIFY any-1 ... any-N>
8744
8745 returns its last argument, after causing a miniature garbage
8746 collection that results in all the arguments becoming pure and
8747 sharable, and ignored afterward by the garbage collector. No argument
8748 can live on the control stack or be of `PRIMTYPE` `PROCESS` or `LOCD`
8749 or `ASOC`. Sharing between operating-system processes actually occurs
8750 after a `SAVE`, if and when the `SAVE` file is `RESTORE`d.
8751
8752 Chapter 23. Muddle as a System Process
8753 ======================================
8754
8755 This chapter treats Muddle considered as executing in an
8756 operating-system process, and interactions between Muddle and other
8757 operating-system processes. See also section 21.8.13.
8758
8759 23.1. TIME
8760 ----------
8761
8762 `TIME` takes any number of arguments, which are evaluated but ignored,
8763 and returns a `FLOAT` giving the number of seconds of CPU time the
8764 Muddle process has used so far. `TIME` is often used in machine-level
8765 debugging to examine the values of its arguments, by having Muddle's
8766 superior process (say, DDT) plant a breakpoint in the code for `TIME`.
8767
8768 23.2. Names
8769 -----------
8770
8771     <UNAME>
8772
8773 returns a `STRING` which is the "user name" of Muddle's process. This
8774 is the "uname" process-control variable in the ITS version and the
8775 logged-in directory in the Tenex and Tops-20 versions.
8776
8777     <XUNAME>
8778
8779 returns a `STRING` which is the "intended user name" of Muddle's
8780 process. This is the "xuname" process-control variable in the ITS
8781 version and identical to `<UNAME>` in the Tenex and Tops-20 versions.
8782
8783     <JNAME>
8784
8785 returns a `STRING` which is the "job name" of Muddle's process. This
8786 is the "jname" process-control variable in the ITS version and the
8787 `SETNM` name in the Tenex and Tops-20 versions. The characters belong
8788 to the "sixbit" or "printing" subset of ASCII, namely those between
8789 `<ASCII *40*>` and `<ASCII *137*>` inclusive.
8790
8791     <XJNAME>
8792
8793 returns a `STRING` which is the "intended job name" of Muddle's
8794 process. This is the "xjname" process-control variable in the ITS
8795 version and identical to `<JNAME>` in the Tenex and Tops-20 versions.
8796
8797 23.3. Exits
8798 -----------
8799
8800     <LOGOUT>
8801
8802 attempts to log out the process in which it is executed. It will
8803 succeed only if the Muddle is the top-level process, that is, it is
8804 running disowned or as a daemon. If it succeeds, it of course never
8805 returns. If it does not, it returns `#FALSE ()`.
8806
8807     <QUIT>
8808
8809 causes Muddle to stop running, in an orderly manner. In the ITS
8810 version, it is equivalent to a `.LOGOUT 1` instruction. In the Tenex
8811 and Tops-20 versions, it is equivalent to a control-C signal, and
8812 control passes to the superior process.
8813
8814     <VALRET string-or-fix>
8815
8816 ("value return") seldom returns. It passes control back up the process
8817 tree to the superior of Muddle, passing its argument as a message to
8818 that superior. If it does return, the value is `#FALSE ()`. If the
8819 argument is a `STRING`, it is passed to the superior as a command to
8820 be executed, via `.VALUE` in the ITS version and `RSCAN` in the
8821 Tops-20 version. If the argument is a `FIX`, it is passed to the
8822 superior as the "effective address" of a `.BREAK 16`, instruction in
8823 the ITS version and ignored in other versions.
8824
8825 23.4. Inter-process Communication
8826 ---------------------------------
8827
8828 All of the `SUBR`s in this section are available only in the ITS
8829 version.
8830
8831 The IPC ("inter-process communication") device is treated as an I/O
8832 device by ITS but not explicitly so by Muddle: that is, it is never
8833 `OPEN`ed. It allows Muddle to communicate with other ITS processes by
8834 means of sending and receiving messages. A process identifies itself
8835 as sender or recipient of a message with an ordered pair of "sixbit"
8836 `STRING`s, which are often but not always `<UNAME>` and `<JNAME>`. A
8837 message has a "body" and a "type".
8838
8839 ### 23.4.1. SEND and SEND-WAIT
8840
8841     <SEND othern1 othern2 body type mynamel myname2>
8842
8843     <SEND-WAIT othern1 othern2 body type mynamel myname2>
8844
8845 both send an IPC message to any job that is listening for it as
8846 *othern1* *othern2*. *body* must be either a `STRING`, or a `UVECTOR`
8847 of objects of `PRIMTYPE` `WORD`. *type* is an optional `FIX`, `0` by
8848 default, which is part of the information the other guy receives. The
8849 last two arguments are from whom the message is to be sent. These are
8850 optional, and `<UNAME>` and `<JNAME>` respectively are used by
8851 default. `SEND` returns a `FALSE` if no one is listening, while
8852 `SEND-WAIT` hangs until someone wants it. Both return `T` if someone
8853 accepts the message.
8854
8855 ### 23.4.2. The "IPC" Interrupt
8856
8857 When your Muddle process receives an IPC message, `"IPC"` occurs
8858 (chapter 21). A handler is called with either four or six arguments
8859 gleaned from the message. *body*, *type*, *othern1*, and *othern2* are
8860 supplied only if they are not this process's `<UNAME>` and `<JNAME>`.
8861
8862 There is a built-in `HANDLER` for the `"IPC"` interrupt, with a
8863 handler named `IPC-HANDLER` and `0` in the `PROCESS` slot. The handler
8864 prints out on the terminal the *body*, whom it is from, the *type* if
8865 not `0`, and whom it is to if not `<UNAME>` `<JNAME>`. If the *type*
8866 is `1` and the *body* is a `STRING`, then, after the message
8867 information is printed out, the `STRING` is `PARSE`d and `EVAL`uated.
8868
8869 ### 23.4.3. IPC-OFF
8870
8871 `<IPC-OFF>` stops all listening on the IPC device.
8872
8873 ### 23.4.4. IPC-ON
8874
8875     <IPC-ON myname1 myname2>
8876
8877 causes listening on the IPC device as *myname1* *myname2*. If no
8878 arguments are provided, listening is on `<UNAME>` `<JNAME>`. When a
8879 message arrives, `"IPC"` occurs.
8880
8881 Muddle is initially listening as `<UNAME>` `<JNAME>` with the built-in
8882 `HANDLER` set up on the `"IPC"` interrupt with a priority of `1`.
8883
8884 ### 23.4.5. DEMSIG
8885
8886     <DEMSIG daemon:string>
8887
8888 signals to ITS (directly, not via the IPC device) that the daemon
8889 named by its argument should run now. It returns `T` if the daemon
8890 exists, `#FALSE ()` otherwise.
8891
8892 Chapter 24. Efficiency and Tastefulness
8893 =======================================
8894
8895 24.1. Efficiency
8896 ----------------
8897
8898 Actually, you make Muddle programs efficient by thinking hard about
8899 what they really make the interpreter **do**, and making them do less.
8900 Some guidelines, in order of decreasing expense:
8901
8902 1.  Free storage is expensive.
8903 2.  Calling functions is expensive.
8904 3.  `PROG` and `REPEAT` are expensive, except when compiled.
8905
8906 Explanation:
8907
8908 1.  Unnecessary use of free storage (creating needless `LIST`s,
8909     `VECTOR`s, `UVECTOR`s, etc.) will cause the garbage collector to
8910     run more often. This is **expensive!** A fairly large Muddle (for
8911     example, 60,000 36-bit words) can take ten seconds of PDP-10 CPU
8912     time for a garbage collection. Be especially wary of constructions
8913     like `(0)`. Every time that is evaluated, it creates a new
8914     one-element `LIST`; it is too easy to write such things when they
8915     aren't really necessary. Unless you are doing `PUT`s or `PUTREST`s
8916     on it, use `'(0)` instead.
8917 2.  Sad, but true. Also generally ignored. If you call a function only
8918     once, or if it is short (less than one line), you are much better
8919     off in speed if you substitute its body in by hand. On the other
8920     hand, you may be much worse off in modularity. There are
8921     techniques for combining several `FUNCTION`s into one `RSUBR`
8922     (with `RSUBR-ENTRY`s), either during or after compilation, and for
8923     changing `FUNCTION`s into `MACRO`s.
8924 3.  `PROG` is almost never necessary, given (a) `"AUX"` in
8925     `FUNCTION`s; (b) the fact that `FUNCTION`s can contain any number
8926     of `FORM`s; (c) the fact that `COND` clauses can contain any
8927     number of `FORM`s; and (d) the fact that new variables can be
8928     generated and initialized by `REPEAT`. However, `PROG` may be
8929     useful when an error occurs, to establish bindings needed for
8930     cleaning things up or interacting with a human.
8931
8932 The use of `PROG` may be sensible when the normal flow of control can
8933 be cut short by unusual conditions, so that the program wants to
8934 `RETURN` before reaching the end of `PROG`. Of course, nested `COND`s
8935 can accomplish the same end, but deep nesting may tend to make the
8936 program unreadable. For example:
8937
8938     <PROG (TEMP)
8939           <OR <SET TEMP <OK-FOR-STEP-1?>>
8940               <RETURN .TEMP>>
8941           <STEP-1>
8942           <OR <SET TEMP <OK-FOR-STEP-2?>>
8943               <RETURN .TEMP>>
8944           <STEP-2>>
8945
8946 could instead be written
8947
8948     <COND (<OK-FOR-STEP-1?>
8949            <STEP-1>
8950            <COND (<OK-FOR-STEP-2?>
8951                   <STEP-2>)>)>
8952
8953 By the way, `REPEAT` is faster than `GO` in a `PROG`. The `<GO x>`
8954 `FORM` has to be separately interpreted, right? In fact, if you
8955 organize things properly you **very** seldom need a `GO`; using `GO`
8956 is generally considered "bad style", but in some cases it's needed.
8957 Very few.
8958
8959 In many cases, a `REPEAT` can be replaced with a `MAPF` or `MAPR`, or
8960 an `ILIST`, `IVECTOR`, etc. of the form
8961
8962     <ILIST .N '<SET X <+ .X 1>>
8963
8964 which generates an `N`-element `LIST` of successive numbers starting
8965 at `X+1`.
8966
8967 Whether a program is interpreted or compiled, the first two
8968 considerations mentioned above hold: garbage collection and function
8969 calling remain expensive. Garbage collection is, clearly, exactly the
8970 same. Function calling is relatively more expensive. However, the
8971 compiler careth not whether you use `REPEAT`, `GO`, `PROG`, `ILIST`,
8972 `MAPF`, or whatnot: it all gets compiled into practically the same
8973 thing. However, the `REPEAT` or `PROG` will be slower if it has an
8974 `ACTIVATION` that is `SPECIAL` or used other than by `RETURN` or
8975 `AGAIN`.
8976
8977 ### 24.1.1. Example
8978
8979 There follows an example of a `FUNCTION` that does many things wrong.
8980 It is accompanied by commentary, and two better versions of the same
8981 thing. (This function actually occurred in practice. Needless to say,
8982 names are withheld to protect the guilty.)
8983
8984 Blunt comment: this is terrible. Its purpose is to output the
8985 characters needed by a graphics terminal to draw lines connecting a
8986 set of points. The points are specified by two input lists: `X` values
8987 and `Y` values. The output channel is the third argument. The actual
8988 characters for each line are returned in a `LIST` by the function
8989 `TRANS`.
8990
8991     <DEFINE PLOTVDSK (X Y CHN "AUX" L LIST)
8992        <COND (<NOT <==? <SET L <LENGTH .X>><LENGTH .Y> >>
8993               <ERROR "LENGTHS NOT EQUAL">)>
8994        <SET LIST (29)>
8995        <REPEAT ((N 1))
8996            <SET LIST (!.LIST !<TRANS <.N .X> <.N .Y>>)>
8997            <COND (<G? <SET N <+ .N 1>> .L><RETURN .N>)> >
8998        <REPEAT ((N 1) (L1 <LENGTH .LIST>))
8999            <PRINC <ASCII <.N .LIST>> .CHN>
9000            <COND (<G? <SET N <+ .N 1>> .L1>
9001                   <RETURN "DONE">)> >>
9002
9003 Comments:
9004
9005 1.  `LIST` is only temporarily necessary. It is just created and then
9006     thrown away.
9007 2.  Worse, the construct `(!.LIST !<TRANS ...>)` **copies** the
9008     previous elements of `LIST` every time it is executed!
9009 3.  Indexing down the elements of `LIST` as in `<.N .LIST>` takes a
9010     long time, if the `LIST` is long. `<3 ...>` or `<4 ...>` is not
9011     worth worrying about, but `<10 ...>` is, and `<100 ...>` takes
9012     quite a while. Even if the indexing were not phased out, the
9013     compiler would be happier with `<NTH .LIST .N>`.
9014 4.  The variable `CHN` is unnecessary if `OUTCHAN` is bound to the
9015     argument `CHANNEL`.
9016 5.  It is tasteful to call `ERROR` in the same way that F/SUBRs do.
9017     This includes using an `ATOM` from the `ERRORS` `OBLIST` (if one
9018     is appropriate) to tell what is wrong, and it includes identifying
9019     yourself.
9020
9021 So, do it this way:
9022
9023     <DEFINE PLOTVDSK (X Y OUTCHAN)
9024     #DECL ((OUTCHAN <SPECIAL CHANNEL>)
9025     <COND (<NOT <==? <LENGTH .X> <LENGTH .Y>>>
9026             <ERROR VECTOR-LENGTHS-DIFFER!-ERRORS PLOTVDSK>)>
9027     <PRINC <ASCII 29>>
9028     <REPEAT ()
9029             <COND (<EMPTY? .X> <RETURN "DONE">)>
9030             <REPEAT ((OL <TRANS <1 .X> <1 .Y>>))
9031                     <PRINC <ASCII <1 .OL>>>
9032                     <COND (<EMPTY? <SET OL <REST .OL>>>
9033                            <RETURN>)>>
9034             <SET X <REST .X>>
9035             <SET Y <REST .Y>>>>
9036
9037 Of course, if you know how long is the `LIST` that `TRANS` returns,
9038 you can avoid using the inner `REPEAT` loop and have explicit `PRINC`s
9039 for each element. This can be done even better by using `MAPF`, as in
9040 the next version, which does exactly the same thing as the previous
9041 one, but uses `MAPF` to do the `REST`ing and the end conditional:
9042
9043     <DEFINE PLOTVDSK (X Y OUTCHAN)
9044     #DECL ((OUTCHAN <SPECIAL CHANNEL>)
9045     <COND (<NOT <==? <LENGTH .X> <LENGTH .Y>>>
9046             <ERROR VECTOR-LENGTHS-DIFFER!-ERRORS PLOTVDSK>)>
9047     <PRINC <ASCII 29>> <MAPF <>
9048           #FUNCTION ((XE YE)
9049                     <MAPF <> #FUNCTION ((T) <PRINC <ASCII .T>>) <TRANS
9050     .XE .YE>>)
9051           .X
9052           .Y>
9053     "DONE">
9054
9055 24.2. Creating a LIST in Forward Order
9056 --------------------------------------
9057
9058 If you must create the elements of a `LIST` in sequence from first to
9059 last, you can avoid copying earlier ones when adding a later one to
9060 the end. One way is to use `MAPF` or `MAPR` with a first argument of
9061 `,LIST`: the elements are put on the control stack rather than in free
9062 storage, until the final call to `LIST`. If you know how many elements
9063 there will be, you can put them on the control stack yourself, in a
9064 `TUPLE` built for that purpose. Another way is used when `REPEAT` is
9065 necessary:
9066
9067     <REPEAT ((FIRST (T)) (LAST .FIRST) ...)
9068             #DECL ((VALUE FIRST LAST) LIST ...)
9069             ...
9070             <SET LAST <REST <PUTREST .LAST (.NEW)>>>
9071             ...
9072             <RETURN <REST .FIRST>>>
9073             ...>
9074
9075 Here, `.LAST` always points to the current last element of the `LIST`.
9076 Because of the order of evaluation, the `<SET LAST ...>` could also be
9077 written `<PUTREST .LAST (SET LAST (.NEW)>>`.
9078
9079 24.3. Read-only Free Variables
9080 ------------------------------
9081
9082 If a Function uses the value of a free variable
9083 (`<GVAL unmanifest:atom>` or `<LVAL special:atom>`) without changing
9084 it, the compiled version may be more efficient if the value is
9085 assigned to a dummy `UNSPECIAL` `ATOM` in the Function's `"AUX"` list.
9086 This is true because an `UNSPECIAL` `ATOM` gets compiled into a slot
9087 on the control stack, which is accessible very quickly. The tradeoff
9088 is probably worthwhile if a *special* is referenced more than once, or
9089 if an *unmanifest* is referenced more than twice. Example:
9090
9091     <DEFINE MAP-LOOKUP (THINGS "AUX" (DB ,DATA-BASE))
9092             #DECL ((VALUE) VECTOR (THINGS DB) <UNSPECIAL <PRIMTYPE LIST>>)
9093             <MAPF ,VECTOR <FUNCTION (T) <MEMQ .T .DB>> .THINGS>>
9094
9095 24.4. Global and Local Values
9096 -----------------------------
9097
9098 In the interpreter the sequence `,X .X ,X .X` is slower than
9099 `,X ,X .X .X` because of interference between the `GVAL` and `LVAL`
9100 mechanisms (appendix 1). Thus it is not good to use both the `GVAL`
9101 and `LVAL` of the same `ATOM` frequently, unless references to the
9102 `LVAL` will be compiled away (made into control stack references).
9103
9104 24.5. Making Offsets for Arrays
9105 -------------------------------
9106
9107 It is often the case that you want to attach some meaning to each
9108 element of an array and access it independently of other elements.
9109 Firstly, it is a good idea to use names (`ATOM`s) rather than integers
9110 (`FIX`es or even `OFFSET`s) for offsets into the array, to make future
9111 changes easier. Secondly, it is a good idea to use the `GVAL`s of the
9112 name `ATOM`s to remember the actual `FIX`es, so that the `ATOM`s can
9113 be `MANIFEST` for the compiler's benefit. Thirdly, to establish the
9114 `GVAL`s, both the interpreter and the compiler will be happier with
9115 `<SETG name offset>` rather than
9116 `<DEFINE name ("TUPLE" T) <offset !.T>>`.
9117
9118 24.6. Tables
9119 ------------
9120
9121 There are several ways in Muddle to store a table, that is, a
9122 collection of (names and) values that will be searched.
9123 Unsurprisingly, choosing the best way is often dictated by the size of
9124 the table and/or the nature of the (names and) values.
9125
9126 For a small table, the names and values can be put in (separate)
9127 structures -- the choice of `LIST` or array being determined by
9128 volatility and limitability -- which are searched using `MEMQ` or
9129 `MEMBER`. This method is very space-efficient. If the table gets
9130 larger, and if the elements are completely orderable, a (uniform)
9131 vector can be used, kept sorted, and searched with a binary search.
9132
9133 For a large table, where reasonably efficient searches are required, a
9134 hashing scheme is probably best. Two methods are available in Muddle:
9135 associations and `OBLIST`s.
9136
9137 In the first method, `PUTPROP` and `GETPROP` are used, which are very
9138 fast. The number of hashing buckets is fixed. Duplicates are
9139 eliminated by `==?` testing. If it is necessary to use `=?` testing,
9140 or to find all the entries in the table, you can duplicate the table
9141 in a `LIST` or array, to be used only for those purposes.
9142
9143 In the second method, `INSERT` and `LOOKUP` on a specially-built
9144 `OBLIST` are used. (If the names are not `STRING`s, they can be
9145 converted to `STRING`s using `UNPARSE`, which takes a little time.)
9146 The number of hashing buckets can be chosen for best efficiency.
9147 Duplicates are eliminated by `=?` testing. MAPF/R can be used to find
9148 all the entries in the table.
9149
9150 24.7. Nesting
9151 -------------
9152
9153 The beauty of deeply-nested control structures in a single `FUNCTION`
9154 is definitely in the eye of the beholder. (`PPRINT`, a preloaded
9155 `RSUBR`, finds them trying. However, the compiler often produces
9156 better code from them.) **If** you don't like excessive nesting, then
9157 you will agree that
9158
9159     <SET X ...>
9160     <COND (<0? .X> ...) ...>
9161
9162 looks better than
9163
9164     <COND (<0? <SET X ...>> ...) ...>
9165
9166 and that
9167
9168     <REPEAT ...
9169             <COND ...
9170                   (... <RETURN ...>)>
9171             ...
9172             ...>
9173
9174 looks better than
9175
9176     <REPEAT ...
9177             <COND ...
9178                   (... <RETURN ...>)
9179                   (ELSE ...)>
9180             ...>
9181
9182 You can see the nature of the choices. Nesting is still and all better
9183 than `GO`.
9184
9185 Appendix 1. A Look Inside
9186 =========================
9187
9188 This appendix tells about the mapping between Muddle objects and
9189 PDP-10 storage -- in other words, the way things look "on the inside".
9190 None of this information is essential to knowing how to program in
9191 Muddle, but it does give some reasons for capabilities and
9192 restrictions that otherwise you have to memorize. The notation and
9193 terminology get a little awkward in this discussion, because we are in
9194 a twilight zone between the worlds of Muddle objects and of bit
9195 patterns. In general the words and phrases appearing in diagrams refer
9196 to bit patterns not Muddle objects. A lower-case word (like "tuple")
9197 refers to the storage occupied by an object of the corresponding
9198 `PRIMTYPE` (like `TUPLE`).
9199
9200 First some terminology needs discussion. The sine qua non of any
9201 Muddle object is a **pair** of 36-bit computer words. In general,
9202 lists consist of pairs chained together by pointers (addresses), and
9203 vectors consist of contiguous blocks of pairs. `==?` essentially tests
9204 two pairs to see whether they contain the same bit patterns.
9205
9206 The first (lower-addressed) word of a pair is called the **`TYPE`
9207 word**, because it contains a numeric **`TYPE` code** that represents
9208 the object's `TYPE`. The second (higher-addressed) word of a pair is
9209 called the **value word**, because it contains (part of or the
9210 beginning of) the "data part" of the object. The `TYPE` word (and
9211 sometimes the value word) is considered to be made of a left half and
9212 a right half. We will picture a pair like this:
9213
9214     ---------------------------------
9215     |      TYPE     |               |
9216     | - - - - - - - - - - - - - - - |
9217     |             value             |
9218     ---------------------------------
9219
9220 where a vertical bar in the middle of a word means the word's halves
9221 are used independently. You can see that the `TYPE` code is confined
9222 to the left half of the `TYPE` word. (Half-)words are sometimes
9223 subdivided into **fields** appropriate for the context; fields are
9224 also pictured as separated by vertical bars. The right half of the
9225 `TYPE` word is used for different purposes depending on the `TYPE` of
9226 the object and actual location of the value.
9227
9228 Actually the 18-bit `TYPE` field is further decoded. The high-order
9229 (leftmost) bit is the mark bit, used exclusively by the garbage
9230 collector when it runs. The next two bits are monitor bits, used to
9231 cause `"READ"` and `"WRITE"` interrupts on read and write references
9232 to the pair. The next bit is used to differentiate between list
9233 elements and vector dope words. The next bit is unused but could be
9234 used in the future for an "execute" monitor. The remaining 13 bits
9235 specify the actual `TYPE` code. What `CHTYPE` does is to copy the pair
9236 and put a new `TYPE` code into the new pair.
9237
9238 Each data `TYPE` (predefined and `NEWTYPE`s) must belong to one of
9239 about 25 "storage allocation classes" (roughly corresponding to Muddle
9240 `PRIMTYPE`s). These classes are characterized primarily by the manner
9241 in which the garbage collector treats them. Some of these classes will
9242 now be described.
9243
9244 "One Word"
9245
9246 This class includes all data that are not pointers to some kind of
9247 structure. All external (program-available) `TYPE`s in this class are
9248 of `PRIMTYPE` `WORD`. Example:
9249
9250     ---------------------------------
9251     |       FIX     |       0       |
9252     | - - - - - - - - - - - - - - - |
9253     |              105              |
9254     ---------------------------------
9255
9256 "Two Word"
9257
9258 The members of this class are all 18-bit pointers to list elements.
9259 All external `TYPE`s in this class are of `PRIMTYPE` `LIST`. Example:
9260
9261     ---------------------------------
9262     |      LIST     |       0       |
9263     | - - - - - - - - - - - - - - - |
9264     |       0       |    pointer    |
9265     ---------------------------------
9266
9267 where `pointer` is a pointer to the first list element. If there are
9268 no elements, `pointer` is zero; thus empty objects of `PRIMTYPE`
9269 `LIST` are `==?` if their `TYPE`s are the same.
9270
9271 "Two N Word"
9272
9273 Members of this class are all "counting pointers" to blocks of
9274 two-word pairs. The right half of a counting pointer is an address,
9275 and the left half is the negative of the number of 36-bit words in the
9276 block. (This format is tailored to the PDP-10 `AOBJN` instruction.)
9277 The number of pairs in the block (`LENGTH`) is half that number, since
9278 each pair is two words. All external `TYPE`s in this class are of
9279 `PRIMTYPE` `VECTOR`. Example:
9280
9281     ---------------------------------
9282     |     VECTOR    |       0       |
9283     | - - - - - - - - - - - - - - - |
9284     |   -2*length   |    pointer    |
9285     ---------------------------------
9286
9287 where `length` is the `LENGTH` of the `VECTOR` and `pointer` is the
9288 location of the start (the element selected by an `NTH` argument of 1)
9289 of the `VECTOR`.
9290
9291 "N word"
9292
9293 This class is the same as the previous one, except that the block
9294 contains objects all of the same `TYPE` without individual `TYPE`
9295 words. The `TYPE` code for all the elements is in vector dope words,
9296 which are at addresses just larger than the block itself. Thus, any
9297 object that carries information in its `TYPE` word cannot go into the
9298 block: `PRIMTYPE`s `STRING`, `BYTES`, `TUPLE` (and the corresponding
9299 locatives `LOCS`, `LOCB`, `LOCA`), `FRAME`, and `LOCD`. All external
9300 `TYPE`s in this class are of `PRIMTYPE` `UVECTOR`. Example:
9301
9302     ---------------------------------
9303     |    UVECTOR    |       0       |
9304     | - - - - - - - - - - - - - - - |
9305     |    -length    |    pointer    |
9306     ---------------------------------
9307
9308 where `length` is the `LENGTH` of the `UVECTOR` and `pointer` points
9309 to the beginning of the `UVECTOR`.
9310
9311 "Byte String" and "Character String"
9312
9313 These two classes are almost identical. Byte strings are byte pointers
9314 to strings of arbitrary-size bytes. `PRIMTYPE` `BYTES` is the only
9315 member of this class. Character strings are byte pointers to strings
9316 of ASCII characters. `PRIMTYPE` `STRING` is the only member of this
9317 class. Both of these classes consist of a length and a PDP-10 byte
9318 pointer. In the case of character strings, the byte-size field in the
9319 byte pointer is always seven bits per byte (hence five bytes per
9320 word). Example:
9321
9322     ---------------------------------
9323     |     STRING    |    length     |
9324     | - - - - - - - - - - - - - - - |
9325     |         byte-pointer          |
9326     ---------------------------------
9327
9328 where `length` is the `LENGTH` of the `STRING` (in bytes) and
9329 `byte-pointer` points to a byte just before the beginning of the
9330 string (an `ILDB` instruction is needed to get the first byte). A
9331 newly-created `STRING` always has `*010700*` in the left half of
9332 `byte-pointer`. Unless the string was created by `SPNAME`,
9333 `byte-pointer` points to a uvector, where the elements (characters) of
9334 the `STRING` are stored, packed together five to a word.
9335
9336 "Frame"
9337
9338 This class gives the user program a handle on its control and
9339 variable-reference structures. All external `TYPE`s in this class are
9340 of `PRIMTYPE` `FRAME`. Three numbers are needed to designate a frame:
9341 a unique 18-bit identifying number, a pointer to the frame's storage
9342 on a control stack, and a pointer to the `PROCESS` associated with the
9343 frame. Example:
9344
9345     ---------------------------------
9346     |     FRAME     |PROCESS-pointer|
9347     | - - - - - - - - - - - - - - - |
9348     |   unique-id   | frame-pointer |
9349     ---------------------------------
9350
9351 where `PROCESS-pointer` points to the dope words of a `PROCESS`
9352 vector, and `unique-id` is used for validating (testing `LEGAL?`) the
9353 `frame-pointer`, which points to a frame for some Subroutine call on
9354 the control stack.
9355
9356 "Tuple"
9357
9358 A tuple pointer is a counting pointer to a vector on the control
9359 stack. It may be a pointer to the arguments to a Subroutine or a
9360 pointer generated by the `"TUPLE"` declaration in a `FUNCTION`. Like
9361 objects in the previous class, these objects contain a unique
9362 identifying number used for validation. `PRIMTYPE` `TUPLE` is the only
9363 member of this class. Example:
9364
9365     ---------------------------------
9366     |     TUPLE     |   unique-id   |
9367     | - - - - - - - - - - - - - - - |
9368     |   -2*length   |    pointer    |
9369     ---------------------------------
9370
9371 Other Storage Classes
9372
9373 The rest of the storage classes include strictly internal `TYPE`s and
9374 pointers to special kinds of lists and vectors like locatives, `ATOM`s
9375 and `ASOC`s. A pair for any `LOCATIVE` except a `LOCD` looks like a
9376 pair for the corresponding structure, except of course that the `TYPE`
9377 is different. A `LOCD` pair looks like a tuple pair and needs a word
9378 and a half for its value; the `unique-id` refers to a binding on the
9379 control stack or to the "global stack" if zero. Thus `LOCD`s are in a
9380 sense "stack objects" and are more restricted than other locatives.
9381
9382 An `OFFSET` is stored with the `INDEX` in the right half of the value
9383 word and the Pattern in the left half. Since the Pattern can be either
9384 an `ATOM` or a `FORM`, the left half actually points to a pair, which
9385 points to the actual Pattern. The Patttern `ANY` is recognized as a
9386 special case: the left-half pointer is zero, and no pair is used.
9387 Thus, if you're making the production version of your program and want
9388 to save some storage, can do something like
9389 `<SETG FOO <PUT-DECL ,FOO ANY>>` for all `OFFSET`s.
9390
9391 Basic Data Structures
9392 ---------------------
9393
9394 Lists
9395
9396 List elements are pairs linked together by the right halves of their
9397 first words. The list is terminated by a zero in the right half of the
9398 last pair. For example the `LIST` `(1 2 3)` would look like this:
9399
9400     -------------
9401     | LIST | 0  |
9402     | - - - - - |   -----------     -----------     -----------
9403     |  0   | ------>| FIX | ------->| FIX | ------->| FIX | 0 |
9404     -------------   | - - - - |     | - - - - |     | - - - - |
9405                     |    1    |     |    2    |     |    3    |
9406                     -----------     -----------     -----------
9407
9408 The use of pointers to tie together elements explains why new elements
9409 can be added easily to a list, how sharing and circularity work, etc.
9410 The links go in only one direction through the list, which is why a
9411 list cannot be `BACK`ed or `TOP`ped: there's no way to find the
9412 `REST`ed elements.
9413
9414 Since some Muddle values require a word and a half for the value in
9415 the pair, they do not fit directly into list elements. This problem is
9416 solved by having "deferred pointers". Instead of putting the datum
9417 directly into the list element, a pointer to another pair is used as
9418 the value with the special internal `TYPE` `DEFER`, and the real datum
9419 is put in the deferred pair. For example the `LIST` `(1 "hello" 3)`
9420 would look like this:
9421
9422     -------------
9423     | LIST | 0  |
9424     | - - - - - |   -----------     -----------     -----------
9425     |  0   | ------>| FIX | ------->|DEFER| ------->| FIX | 0 |
9426     -------------   | - - - - |     | - - - - |     | - - - - |
9427                     |    1    |     |       -----   |    3    |
9428                     -----------     ----------- |   -----------
9429                                                 |
9430                                     ----------- |
9431                                     |STRING| 5|<-
9432                                     | - - - - |
9433                                     |byte-pntr|
9434                                     -----------
9435
9436 Vectors
9437
9438 A vector is a block of contiguous words. More than one pair can point
9439 to the block, possibly at different places in the block; this is how
9440 sharing occurs among vectors. Pointers that are different arise from
9441 `REST` or `GROW`/`BACK` operations. The block is followed by two "dope
9442 words", at addresses just larger than the largest address in the
9443 block. Dope words have the following format:
9444
9445     /                               /
9446     |                               |
9447     |                               |
9448     ---------------------------------
9449     |      type     |      grow     |
9450     | - - - - - - - - - - - - - - - |
9451     |     length    |       gc      |
9452     ---------------------------------
9453
9454 The various fields have the following meanings:
9455
9456 `type` -- The fourth bit from the left (the "vector bit", `40000`
9457 octal) is always one, to distinguish these vector dope words from a
9458 `TYPE`/value pair.
9459
9460 If the high-order bit is zero, then the vector is a `UVECTOR`, and the
9461 remaining bits specify the uniform `TYPE` of the elements. `CHUTYPE`
9462 just puts a new `TYPE` code in this field. Each element is limited to
9463 a one-word value: clearly `PRIMTYPE` `STRING`s and `BYTES`es and stack
9464 objects can't go in uniform vectors.
9465
9466 If the high-order bit is one and the `TYPE` bits are zero, then this
9467 is a regular `VECTOR`.
9468
9469 If the high-order bit is one and the `TYPE` bits are not all zero,
9470 then this is either an `ATOM`, a `PROCESS`, an `ASOC`, or a
9471 `TEMPLATE`. The special internal format of these objects will be
9472 described a little later in this appendix.
9473
9474 `length` -- The high-order bit is the mark bit, used by the garbage
9475 collector. The rest of this field specifies the number of words in the
9476 block, including the dope words. This differs from the length given in
9477 pairs pointing to this vector, since such pairs may be the result of
9478 `REST` operations.
9479
9480 `grow` -- This is actually two nine-bit fields, specifying either
9481 growth or shrinkage at both the high and low ends of the vector. The
9482 fields are usually set only when a stack must be grown or shrunk.
9483
9484 `gc` -- This is used by the garbage collector to specify where this
9485 vector is moving during compaction.
9486
9487 Examples (numbers in octal): the `VECTOR` `[1 "bye" 3]` looks like:
9488
9489     ---------------
9490     | VECTOR |  0 |
9491     | - - - - - - |         -----------------
9492     |   -6   |  ----------->|  FIX  |       |
9493     ---------------         | - - - - - - - |
9494                             |       1       |
9495                             -----------------
9496                             | STRING |  3   |
9497                             | - - - - - - - |
9498                             |  byte pointer |
9499                             -----------------
9500                             |  FIX  |       |
9501                             | - - - - - - - |
9502                             |       3       |
9503                             -----------------
9504                             | 440000 |  0   |
9505                             | - - - - - - - |
9506                             |   10   |      |
9507                             -----------------
9508
9509 The `UVECTOR` `![-1 7 -4!]` looks like:
9510
9511     ---------------
9512     | UVECTOR | 0 |
9513     | - - - - - - |         -----------------
9514     |   -3    | ----------->|       -1      |
9515     ---------------         -----------------
9516                             |        7      |
9517                             -----------------
9518                             |       -4      |
9519                             -----------------
9520                             | 40000+FIX | 0 |
9521                             | - - - - - - - |
9522                             |   5       |   |
9523                             -----------------
9524
9525 Atoms
9526
9527 Internally, atoms are special vector-like objects. An atom contains a
9528 value cell (the first two words of the block, filled in whenever the
9529 global or local value of the `ATOM` is referenced and is not already
9530 there), an `OBLIST` pointer, and a print name (`PNAME`), in the
9531 following format:
9532
9533     ---------------------------------
9534     |      type     |     bindid    |
9535     ---------------------------------
9536     |       pointer-to-value        |
9537     ---------------------------------
9538     |       pointer-to-oblist       |
9539     ---------------------------------
9540     |           print-name          |
9541     /                               /
9542     /                               /
9543     |(ASCII with NUL padding on end)|
9544     ---------------------------------
9545     |      ATOM     |   valid-type  |
9546     | - - - - - - - - - - - - - - - |
9547     |     length    |       gc      |
9548     ---------------------------------
9549
9550 If the type field corresponds to `TYPE` `UNBOUND`, then the `ATOM` is
9551 locally and globally unbound. (This is different from a pair, where
9552 the same `TYPE` `UNBOUND` is used to mean unassigned.) If it
9553 corresponds to `TYPE` `LOCI` (an internal `TYPE`), then the value cell
9554 points either to the global stack, if `bindid` is zero, or to a local
9555 control stack, if `bindid` is non-zero. The `bindid` field is used to
9556 verify whether the local value pointed to by the value cell is valid
9557 in the current environment. The `pointer-to-OBLIST` is either a
9558 counting pointer to an oblist (uvector). a positive offset into the
9559 "transfer vector" (for pure `ATOM`s), or zero, meaning that this
9560 `ATOM` is not on an `OBLIST`. The `valid-type` field tells whether or
9561 not the `ATOM` represents a `TYPE` and if so the code for that `TYPE`:
9562 `grow` values are never needed for atoms.
9563
9564 Associations
9565
9566 Associations are also special vector-like objects. The first six words
9567 of the block contain `TYPE`/value pairs for the `ITEM`, `INDICATOR`
9568 and `AVALUE` of the `ASOC`. The next word contains forward and
9569 backward pointers in the chain for that bucket of the association hash
9570 table. The last word contains forward and backward pointers in the
9571 chain of all the associations.
9572
9573     ---------------------------------
9574     |             ITEM              |
9575     | - - - - - - - - - - - - - - - |
9576     |             pair              |
9577     ---------------------------------
9578     |          INDICATOR            |
9579     | - - - - - - - - - - - - - - - |
9580     |             pair              |
9581     ---------------------------------
9582     |            AVALUE             |
9583     | - - - - - - - - - - - - - - - |
9584     |             pair              |
9585     ---------------------------------
9586     |     bucket-chain-pointers     |
9587     ---------------------------------
9588     |  association-chain-pointers   |
9589     ---------------------------------
9590     |      ASOC     |       0       |
9591     | - - - - - - - - - - - - - - - |
9592     |    12 octal   |       gc      |
9593     ---------------------------------
9594
9595 `PROCESS`es
9596
9597 A `PROCESS` vector looks exactly like a vector of `TYPE`/value pairs.
9598 It is different only in that the garbage collector treats it
9599 differently from a normal vector, and it contains extremely volatile
9600 information when the `PROCESS` is `RUNNING`.
9601
9602 Templates
9603
9604 In a template, the number in the type field (left half or first dope
9605 word) identifies to which "storage allocation class" this `TEMPLATE`
9606 belongs, and it is used to find PDP-10 instructions in internal tables
9607 (frozen uvectors) for performing `LENGTH`, `NTH`, and `PUT` operations
9608 on any object of this `TYPE`. The programs to build these tables are
9609 not part of the interpreter, but the interpreter does know how to use
9610 them properly. The compiler can put these instructions directly in
9611 compiled programs if a `TEMPLATE` is never `REST`ed; otherwise it must
9612 let the interpreter discover the appropriate instruction. The value
9613 word of a template pair contains, not a counting pointer, but the
9614 number of elements that have been `REST`ed off in the left half and a
9615 pointer to the first dope word in the right half.
9616
9617 The Control Stack
9618 -----------------
9619
9620 Accumulators with symbolic names `AB`, `TB`, and `TP` are all pointers
9621 into the `RUNNING` `PROCESS`'s control stack. `AB` ("argument base")
9622 is a pointer to the arguments to the Subroutine now being run. It is
9623 set up by the Subroutine-call mediator, and its old value is always
9624 restored after a mediated Subroutine call returns. `TB` ("temporaries
9625 base") points to the frame for the running Subroutine and also serves
9626 as a stack base pointer. The `TB` pointer is really all that is
9627 necessary to return from a Subroutine -- given a value to return, for
9628 example by `ERRET` -- since the frame specifies the entire state of
9629 the calling routine. `TP` ("temporaries pointer") is the actual stack
9630 pointer and always points to the current top of the control stack.
9631
9632 While we're on the subject of accumulators, we might as well be
9633 complete. Each accumulator contains the value word of a pair, the
9634 corresponding `TYPE` words residing in the `RUNNING` `PROCESS` vector.
9635 When a `PROCESS` is not `RUNNING` (or when the garbage collector is
9636 running), the accumulator contents are stored in the vector, so that
9637 the Objects they point to look like elements of the `PROCESS` and thus
9638 are not garbage-collectible.
9639
9640 Accumulators `A`, `B`, `C`, `D`, `E` and `O` are used almost entirely
9641 as scratch accumulators, and they are not saved or restored across
9642 Subroutine calls. Of course the interrupt machinery always saves these
9643 and all other accumulators. `A` and `B` are used to return a pair as
9644 the value of a Subroutine call. Other than that special feature, they
9645 are just like the other scratch accumulators.
9646
9647 `M` and `R` are used in running `RSUBR`s. `M` is always set up to
9648 point to the start of the `RSUBR`'s code, which is actually just a
9649 uniform vector of instructions. All jumps and other references to the
9650 code use `M` as an index register. This makes the code
9651 location-insensitive, which is necessary because the code uvector will
9652 move around. `R` is set up to point to the vector of objects needed by
9653 the `RSUBR`. This accumulator is necessary because objects in
9654 garbage-collected space can move around, but the pointers to them in
9655 the reference vector are always at the same place relative to its
9656 beginning.
9657
9658 `FRM` is the internal frame pointer, used in compiled code to keep
9659 track of pending Subroutine calls when the control stack is heavily
9660 used. `P` is the internal-stack pointer, used primarily for internal
9661 calls in the interpreter.
9662
9663 One of the nicest features of the Muddle environment is the uniformity
9664 of the calling and returning sequence. All Subroutines -- both
9665 built-in F/SUBRs and compiled `RSUBR(-ENTRY)`s -- are called in
9666 exactly the same way and return the same way. Arguments are always
9667 passed on the control stack and results always end up in the same
9668 accumulators. For efficiency reasons, a lot of internal calls within
9669 the interpreter circumvent the calling sequence. However, all calls
9670 made by the interpreter when running user programs go through the
9671 standard calling sequence.
9672
9673 A Subroutine call is initiated by one of three UUOs (PDP-10
9674 instructions executed by software rather than hardware). `MCALL`
9675 ("Muddle call") is used when the number of arguments is known at
9676 assemble or compile time, and this number is less than 16. `QCALL`
9677 ("quick call") may be used if, in addition, an `RSUBR(-ENTRY)` is
9678 being called that can be called "quickly" by virtue of its having
9679 special information in its reference vector. `ACALL` ("accumulator
9680 call") is used otherwise. The general method of calling a Subroutine
9681 is to `PUSH` (a PDP-10 instruction) pairs representing the arguments
9682 onto the control stack via `TP` and then either (1) `MCALL` or `QCALL`
9683 or (2) put the number of arguments into an accumulator and `ACALL`.
9684 Upon return the object returned by the Subroutine will be in
9685 accumulators `A` and `B`, and the arguments will have been `POP`ped
9686 off the control stack.
9687
9688 The call mediator stores the contents of `P` and `TP` and the address
9689 of the calling instruction in the current frame (pointed to by `TB`).
9690 It also stores Muddle's "binding pointer" to the topmost binding in
9691 the control stack. (The bindings are linked together through the
9692 control stack so that searching through them is more efficient than
9693 looking at every object on the stack.) This frame now specifies the
9694 entire state of the caller when the call occurred. The mediator then
9695 builds a new frame on the control stack and stores a pointer back to
9696 the caller's frame (the current contents of `TB`), a pointer to the
9697 Subroutine being called, and the new contents of `AB`, which is a
9698 counting pointer to the arguments and is computed from the information
9699 in the `MCALL` or `QCALL` instruction or the `ACALL` accumulator. `TB`
9700 is then set up to point to the new frame, and its left half is
9701 incremented by one, making a new `unique-id`. The mediator then
9702 transfers control to the Subroutine.
9703
9704 A control stack frame has seven words as shown:
9705
9706     ---------------------------------
9707     |     ENTRY     |  called-addr  |
9708     ---------------------------------
9709     |   unique-id   |  prev frame   |
9710     ---------------------------------
9711     |       argument pointer        |
9712     ---------------------------------
9713     |    saved binding pointer      |
9714     ---------------------------------
9715     |           saved P             |
9716     ---------------------------------
9717     |           saved TP            |
9718     ---------------------------------
9719     |    saved calling address      |
9720     ---------------------------------
9721
9722 The first three words are set up during the call to the Subroutine.
9723 The rest are filled in when this routine calls another Subroutine. The
9724 left half of `TB` is incremented every time a Subroutine call occurs
9725 and is used as the `unique-id` for the frame, stored in frame and
9726 tuple pairs as mentioned before. Obviously this `id` is not strictly
9727 unique, since each 256K calls it wraps around to zero. The right half
9728 of `TB` is always left pointing one word past the
9729 saved-calling-address word in the frame. `TP` is also left pointing at
9730 that word, since that is the top of the control stack at Subroutine
9731 entry. The arguments to the called Subroutine are below the frame on
9732 the control stack (at lower storage addresses), and the temporaries
9733 for the called Subroutine are above the frame (at higher storage
9734 addresses). These arguments and temporaries are just pairs stored on
9735 the control stack while needed: they are all that remain of
9736 `UNSPECIAL` values in compiled programs.
9737
9738 The following figure shows what the control stack might look like
9739 after several Subroutine calls.
9740
9741     /               /
9742     |               |
9743     -----------------
9744     |               |
9745     |  args for S1  |
9746     |               |
9747     -----------------
9748     | frame for S1  |
9749     ----------------- <--
9750     |               |   |
9751     | temps for S1  |   |
9752     |               |   |
9753     -----------------   |
9754     |               |   |
9755     |  args for S2  |   |
9756     |               |   |
9757     -----------------   |
9758     | frame for S2  | ---
9759     ----------------- <------
9760     |               |       |
9761     | temps for S2  |       |
9762     |               |       |
9763     -----------------       |
9764     |  args for S3  |       |
9765     -----------------       |
9766     | frame for S3  | -------
9767     -----------------
9768     |               |
9769     | temps for S3  |
9770     |               |
9771     |               |
9772     -----------------
9773           (top)
9774
9775 The above figure shows the frames all linked together through the
9776 control stack (the "execution path"), so that it is easy to return to
9777 the caller of a given Subroutine (`ERRET` or `RETRY`).
9778
9779 Subroutine exit is accomplished simply by the call mediator, which
9780 loads the right half of `TB` from the previous frame pointer, restores
9781 the "binding pointer", `P`, and `TP`, and transfers control back to
9782 the instruction following the saved calling address.
9783
9784 Variable Bindings
9785 -----------------
9786
9787 All local `ATOM` values are kept on the control stack of the `PROCESS`
9788 to which they are local. As described before, the atom contains a word
9789 that points to the value on the control stack. The pointer is actually
9790 to a six-word "binding block" on the control stack. Binding blocks
9791 have the following format:
9792
9793     ---------------------------------
9794     | BIND or UBIND |      prev     |
9795     ---------------------------------
9796     |        pointer to ATOM        |
9797     ---------------------------------
9798     |             value             |
9799     | - - - - - - - - - - - - - - - |
9800     |             pair              |
9801     ---------------------------------
9802     |     decl      |   unique-id   |
9803     ---------------------------------
9804     |       previous-binding        |
9805     ---------------------------------
9806
9807 where:
9808
9809 -   `BIND` means this is a binding for a `SPECIAL` `ATOM` (the only
9810     kind used by compiled programs), and `UBIND` means this is a
9811     binding for an `UNSPECIAL` `ATOM` -- for `SPECIAL` checking by the
9812     interpreter;
9813 -   `prev` points to the closest previous binding block for any `ATOM`
9814     (the "access path" -- `UNWIND` objects are also linked in this
9815     chain);
9816 -   `decl` points to a `DECL` associated with this value, for
9817     `SET(LOC)` to check;
9818 -   `unique-id` is used for validation of this block; and
9819 -   `previous-binding` points to the closest previous binding for this
9820     `ATOM` (used in unbinding).
9821
9822 Bindings are generated by an internal subroutine called `SPECBIND`
9823 (name comes from `SPECIAL`). The caller to `SPECBIND` `PUSH`es
9824 consecutive six-word blocks onto the control stack via `TP` before
9825 calling `SPECBIND`. The first word of each block contains the `TYPE`
9826 code for `ATOM` in its left half and all ones in its right half.
9827 `SPECBIND` uses this bit pattern to identify the binding blocks.
9828 `SPECBIND`'s caller also fills in the next three words and leaves the
9829 last two words empty. `SPECBIND` fills in the rest and leaves the
9830 "binding pointer" pointing at the topmost binding on the control
9831 stack. `SPECBIND` also stores a pointer to the current binding in the
9832 value cell of the atom.
9833
9834 Unbinding is accomplished during Subroutine return. When the previous
9835 frame is being restored, the call mediator checks to see if the saved
9836 "binding pointer" and the current one are different; if they are,
9837 `SPECSTORE` is called. `SPECSTORE` runs through the binding blocks,
9838 restoring old value pointers in atoms until the "binding pointer" is
9839 equal to the one saved in the frame.
9840
9841 Obviously variable binding is more complicated than this, because
9842 `ATOM`s can have both local and global values and even different local
9843 values in different `PROCESS`es. The solution to all of these
9844 additional problems lies in the `bindid` field of the atom. Each
9845 `PROCESS` vector also contains a current `bindid`. Whenever an ATOM's
9846 local value is desired, the `RUNNING` `PROCESS`'s `bindid` is checked
9847 against that of the atom: if they are the same, the atom points to the
9848 current value; if not, the current `PROCESS`'s control stack must be
9849 searched to find a binding block for this `ATOM`. This binding scheme
9850 might be called "shallow binding". The searching is facilitated by
9851 having all binding blocks linked together. Accessing global variables
9852 is accomplished in a similar way, using a `VECTOR` that is referred to
9853 as the "global stack". The global stack has only an `ATOM` and a value
9854 slot for each variable, since global values never get rebound.
9855
9856 `EVAL` with respect to a different environment causes some additional
9857 problems. Whenever this kind of `EVAL` is done, a brand new `bindid`
9858 is generated, forcing all current local value cells of atoms to appear
9859 invalid. Local values must now be obtained by searching the control
9860 stack, which is inefficient compared to just pulling them out of the
9861 atoms. (The greatest inefficiency occurs when an `ATOM`'s `LVAL` is
9862 never accessed twice in a row in the same environment.) A special
9863 block is built on the control stack and linked into the binding-block
9864 chain. This block is called a "skip block" or "environment splice",
9865 and it diverts the "access path" to the new environment, causing
9866 searches to become relative to this new environment.