1 MIT Technical Report 293
3 Laboratory for Computer Science\
4 Massachusetts Institute of Technology\
6 Cambridge, Massachusetts 02139
11 This document is free of known copyright restrictions.
16 The Muddle programming language began existence in late 1970 (under
17 the name Muddle) as a successor to Lisp (Moon, 1974), a candidate
18 vehicle for the Dynamic Modeling System, and a possible base for
19 implementation of Planner (Hewitt, 1969). The original design goals
20 included an interactive integrated environment for programming,
21 debugging, loading, and editing: ease in learning and use; facilities
22 for structured, modular, shared programs; extensibility of syntax,
23 data types and operators: data-type checking for debugging and
24 optional data-type declarations for compiled efficiency; associative
25 storage, coroutining, and graphics. Along the way to reaching those
26 goals, it developed flexible input/output (including the ARPA
27 Network), and flexible interrupt and signal handling. It now serves as
28 a base for software prototyping, research, development, education, and
29 implementation of the majority of programs at MIT-DMS: a library of
30 sharable modules, a coherent user interface, special research
31 projects, autonomous daemons, etc.
33 This document was originally intended to be a simple low-level
34 introduction to Muddle. It has, however, acquired a case of
35 elephantiasis and now amounts to a discursive description of the whole
36 interpreter, as realized in Muddle release numbers 55 (ITS version)
37 and 105 (Tenex and Tops-20 versions). (Significant changes from the
38 previous edition are marked in the margin.) A low-level introduction
39 may still be had by restricting one's attention to specially-marked
40 sections only. The scope of the document is confined as much as
41 possible to the interpreter itself. Other adjuncts (compiler,
42 assembler, pre-loaded user programs, library) are mentioned as little
43 as possible, despite their value in promoting the language seen by a
44 user from "basic survival" to "comfortable living". Indeed, Muddle
45 could not fulfill the above design goals without the compiler,
46 assembler, structure editor, control-stack printer, context printer,
47 pretty-printer, dynamic loader, and library system -- all of which are
48 not part of the interpreter but programs written in Muddle and
49 symbiotic with one another. Further information on these adjuncts can
50 be found in Lebling's (1979) document.
55 I was not a member of the original group which labored for two years
56 in the design and initial implementation of Muddle; that group was
57 composed principally of Gerald Sussman, Carl Hewit, Chris Reeve, Dave
58 Cressey, and later Bruce Daniels. I would therefore like to take this
59 opportunity to thank my Muddle mentors, chiefly Chris Reeve and Bruce
60 Daniels, for remaining civil through several months of verbal
61 badgering. I believe that I learned more than "just another
62 programming language" in learning Muddle, and I am grateful for this
63 opportunity to pass on some of that knowledge. What I cannot pass on
64 is the knowledge gained by using Muddle as a system; that I can only
67 For editing the content of this document and correcting some
68 misconceptions, I would like to thank Chris Reeve, Bruce Daniels, and
69 especially Gerald Sussman, one of whose good ideas I finally did use.
74 Since Greg left the fold, I have taken up the banner and updated his
75 document. The main sources for small revisions have been the on-line
76 file of changes to Muddle, for which credit goes to Neal Ryan as well
77 as Reeve and Daniels, and the set of on-line abstracts for interpreter
78 Subroutines, contributed by unnamed members of the Programming
79 Technology Division. Some new sections were written almost entirely by
80 others: Dave Lebling wrote chapter 14 and appendix 3, Jim Michener
81 section 14.3, Reeve chapter 19 and appendix 1, Daniels and Reeve
82 appendix 2. Brian Berkowitz section 22.7, Tak To section 17.2.2, and
83 Ryan section 17.1.3. Sue Pitkin did the tedious task of marking
84 phrases in the manuscript for indexing. Pitts Jarvis and Jack Haverty
85 advised on the use of PUB and the XGP. Many PTD people commented
86 helpfully on a draft version.
88 My task has been to impose some uniformity and structure on these
89 diverse resources (so that the result sounds less like a dozen hackers
90 typing at a dozen terminals for a dozen days) and to enjoy some of the
91 richness of Muddle from the inside. I especially thank Chris Reeve
92 ("the oracle") for the patience to answer questions and resolve
93 doubts, as he no doubt as done innumerable times before.
98 This work was supported by the Advanced Research Projects Agency of
99 the Department of Defense and was monitored by the Office of Naval
100 Research under contract N00014-75-C-0661.
102 This document was prepared using [the PUB
103 system](http://www.nomodes.com/pub_manual.html) (originally from the
104 Stanford Artificial Intelligence Laboratory) and printed on the Xerox
105 Graphics Printer of the M.I.T. Artificial Intelligence Laboratory.
110 Trying to explain Muddle to an uninitiate is somewhat like trying to
111 untie a Gordian knot. Whatever topic one chooses to discuss first,
112 full discussion of it appears to imply discussion of everything else.
113 What follows is a discursive presentation of Muddle in an order
114 apparently requiring the fewest forward references. It is not perfect
115 in that regard; however, if you are patient and willing to accept a
116 few, stated things as "magic" until they can be explained better, you
117 will probably not have too many problems understanding what is going
120 There are no "practice problems"; you are assumed to be learning
121 Muddle for some purpose, and your work in achieving that purpose will
122 be more useful and motivated than artificial problems. In several
123 cases, the examples contain illustrations of important points which
124 are not covered in the text. Ignore examples as your peril.
126 This document does not assume knowledge of any specific programming
127 language on the \[sic\] your part. However, "computational literacy"
128 is assumed: you should have written at least one program before. Also
129 very little familiarity is assumed with the interactive time-sharing
130 operating systems under which Muddle runs -- ITS, Tenex, and Tops-20
131 -- namely just file and user naming conventions.
135 Sections marked \[1\] are recommended for any uninitiate's first
136 reading, in lieu of a separate introduction for Muddle. \[On first
137 reading, text within brackets like these should be ignored.\]
139 Most specifically indicated examples herein are composed of pairs of
140 lines. The first line of a pair, the input, always ends in `$` (which
141 is how the ASCII character `ESC` is represented, and which always
142 represents it). The second line is the result of Muddle's groveling
143 over the first. If you were to type all the first lines at Muddle, it
144 would respond with all the second lines. (More exactly, the "first
145 line" is one or more objects in Muddle followed by `$`, and the
146 "second line" is everything up to the next "first line".)
148 Anything which is written in the Muddle language or which is typed on
149 a computer terminal appears herein in a fixed width font, as in
150 `ROOT`. A metasyntactic variable -- something to be replaced in actual
151 use by something else -- appears as *radix:fix*, in an italic font;
152 often the variable will have both a meaning and a data type (as here),
153 but sometimes one of those will be ommitted, for obvious reasons.
155 An ellipsis (...) indicates that something uninteresting has been
156 omitted. The character `^` means that the following character is to be
157 "controllified": it is usually typed by holding down a terminal's
158 `CTRL` key and striking the other key.
160 Chapter 1. Basic Introduction
161 =============================
163 The purpose of this chapter is to provide you with that minimal amount
164 of information needed to experiment with Muddle while reading this
165 document. It is strongly recommended that you do experiment,
166 especially upon reaching chapter 5 (Simple Functions).
168 1.1. Loading Muddle \[1\]
169 -------------------------
171 First, catch your rabbit. Somehow get the interpreter running -- the
172 program in the file `SYS:TS.Muddle` in the ITS version or
173 `SYS:Muddle.SAV` in the Tenex version or `SYS:Muddle.EXE` in the
174 Tops-20 version. The interpreter will first type out some news
175 relating to Muddle, if any, then type
177 LISTENING-AT-LEVEL 1 PROCESS 1
179 and then wait for you to type something.
181 The program which you are now running is an interpreter for the
182 language Muddle. **All** it knows how to do is interpret Muddle
183 expressions. There is no special "command language"; you communicate
184 with the program -- make it do things for you -- by actually typing
185 legal Muddle expressions, which it then interprets. **Everything** you
186 can do at a terminal can be done in a program, and vice versa, in
187 exactly the same way.
189 The program will be referred to as just "Muddle" (or "the
190 interpreter") from here on. There is no ambiguity, since the program
191 is just an incarnation of the concept "Muddle".
196 Typing a character at Muddle normally just causes that character to be
197 echoed (printed on your terminal) and remembered in a buffer. The only
198 characters for which this is normally not true act as follows:
200 Typing `$` (`ESC`) causes Muddle to echo dollar-sign and causes the
201 contents of the buffer (the characters which you've typed) to be
202 interpreted as an expression(s) in Muddle. When this interpretation is
203 done, the result will be printed and Muddle will wait for more typing.
204 `ESC` will be represented by the glyph `$` in this document.
206 Typing the rubout character (`DEL` in the ITS and Top-20 versions,
207 `CTRL`+`A` in the Tenex version) causes the last character in the
208 buffer -- the one most recently typed -- to be thrown away (deleted).
209 If you now immediately type another rubout, once again the last
210 character is deleted -- namely the second most recently typed. Etc.
211 The character deleted is echoed, so you can see what you're doing. On
212 some "display" terminals, rubout will "echo" by causing the deleted
213 character to disappear. If no characters are in the buffer, rubout
214 echoes as a carriage-return line-feed.
216 Typing `^@` (`CTRL`+`@`) deletes everything you have typed since the
217 last `$`, and prints a carriage-return line-feed.
219 Typing `^D` (`CTRL`+`D`) causes the current input buffer to be typed
220 back out at you. This allows you to see what you really have, without
221 the confusing re-echoed characters produced by rubout.
223 Typing `^L` (`CTRL`+`L`) produces the same effect as typing `^D`,
224 except that, if your terminal is a "display" terminal (for example,
225 IMLAC, ARDS, Datapoint), it firsts clears the screen.
227 Typing `^G` (`CTRL`+`G`) causes Muddle to stop whatever it is doing
228 and act as if an error had occurred ([section
229 1.4](#14-errors-simple-considerations-1)). `^G` is generally most
230 useful for temporary interruptions to check the progress of a
231 computation. `^G` is "reversible" -- that is, it does not destroy any
232 of the "state" of the computation it interrupts. To "undo" a `^G`,
237 (This is discussed more fully far below, in section 16.4.)
239 Typing `^S` (`CTRL`+`S`) causes Muddle to **throw away** what it is
240 currently doing and return a normal "listening" state. (In the Tenex
241 and Tops-20 versions, `^O` also should have the same effect.) `^S` is
242 generally most useful for aborting infinite loops and similar terrible
243 things. `^S` **destroys** whatever is going on, and so it is **not**
246 Most expressions in Muddle include "brackets" (generically meant) that
247 must be correctly paired and nested. If you end your typing with the
248 pair of characters `!$` (`!`+`ESC`), all currently unpaired brackets
249 (but not double-quotes, which bracket strings of characters) will
250 automatically be paired and interpretation will start. Without the
251 `!`, Muddle will just sit there waiting for you to pair them. If you
252 have improperly nested parentheses, brackets, etc., within the
253 expression you typed, an error will occur, and Muddle will tell you
256 Once the brackets are properly paired, Muddle will immediately echo
257 carriage-return and line-feed, and the next thing it prints will be
258 the result of the evaluation. Thus, if a plain `$` is not so echoed,
259 you have some expression unclosed. In that case, if you have not typed
260 any characters beyond the `$`, you can usually rub out the `$` and
261 other characters back to the beginning of the unclosed expression.
262 Otherwise, what you have typed is beyond the help of rubout and `^@`;
263 if you want to abort it, use `^S`.
265 Muddle accepts and distinguishes between upper and lower case. All
266 "built-in functions" must be referenced in upper case.
268 1.3. Loading a File \[1\]
269 -------------------------
271 If you have a program in Muddle that you have written as an ASCII file
272 on some device, you can "load" it by typing
276 where *file* is the name of the file, in standard operating-system
277 syntax, enclosed in "s (double-quotes). Omitted parts of the file name
278 are taken by default from the file name `DSK: INPUT >` (in the ITS
279 version) or `DSK: INPUT.MUD` (in the Tenex and Tops-20 versions) in
280 the current disk directory.
282 Once you type `$`, Muddle will process the text in the file (including
283 `FLOAD`s) exactly as if you had typed it on a terminal and followed it
284 with `$`, except that "values" produced by the computations are not
285 printed. When Muddle is finished processing the file, it will print
288 When Muddle starts running, it will `FLOAD` the file `MUDDLE INIT`
289 (ITS version) or `MUDDLE.INIT` (Tenex and Tops-20 versions), if it
292 1.4. Errors — Simple Considerations \[1\]
293 -----------------------------------------
295 When Muddle decides for some reason that something is wrong, the
296 standard sequence of evaluation is interrupted and an error function
297 is called. This produces the following terminal output:
300 often-hyphenated-reason
301 function-in-which-error-occurred
302 LISTENING-AT-LEVEL integer PROCESS integer
304 You can now interact with Muddle as usual, typing expressions and
305 having them evaluated. There exist facilities (built-in functions)
306 allowing you to find out what went wrong, restart, or abandon whatever
307 was going on. In particular, you can recover from an error -- that is,
308 undo everything but side effects and return to the initial typing
309 phase -- by typing the following first line, to which Muddle will
310 respond with the second line:
313 LISTENING-AT-LEVEL 1 PROCESS 1
315 If you type the following first line while still in the error state
316 (before `<ERRET>`), Muddle will print, as shown, the arguments (or
317 "parameters or "inputs" or "independent variables") which gave
318 indigestion to the unhappy function:
320 <ARGS <FRAME <FRAME>>>$
321 [ arguments to unhappy function ]
323 This will be explained by and by.
325 Chapter 2. Read, Evaluate, and Print
326 ====================================
331 Once you type `$` and all brackets are correctly paired and nested,
332 the current contents of the input buffer go through processing by
333 three functions successively: first `READ`, which passes its output to
334 `EVAL` ("evaluate"), which passes its output to `PRINT`, whose output
335 is typed on the terminal.
337 \[Actually, the sequence is more like `READ`, `CRLF`, `EVAL`, `PRIN1`,
338 `CRLF` (explained in chapter 11); Muddle gives you a carriage-return
339 line-feed when the `READ` is complete, that is, when all brackets are
344 - `READ`: printable representations → Muddle objects
345 - `EVAL`: Muddle objects → Muddle objects
346 - `PRINT`: Muddle objects → printable representations
348 That is, `READ` takes ASCII text, such as is typed in at a terminal,
349 and creates the Muddle objects represented by that text. `PRINT` takes
350 Muddle objects, creates ASCII text representations of them, and types
351 them out. `EVAL`, which is the really important one, performs
352 transformations on Muddle objects.
354 2.2. Philosophy (TYPEs) \[1\]
355 -----------------------------
357 In a general sense, when you are interacting with Muddle, you are
358 dealing with a world inhabited only by a particular set of objects:
361 Muddle objects are best considered as abstract entities with abstract
362 properties. The properties of a particular Muddle object depend on the
363 class of Muddle objects to which it belongs. This class is the `TYPE`
364 of the Muddle object. Every Muddle object has a `TYPE`, and every
365 `TYPE` has its own peculiarities. There are many different `TYPE`s in
366 Muddle; they will gradually be introduced below, but in the meantime
367 here is a representative sample: `SUBR` (the `TYPE` of `READ`, `EVAL`,
368 and `PRINT`), `FSUBR`, `LIST`, `VECTOR`, `FORM`, `FUNCTION`, etc.
369 Since every object has a `TYPE`, one often abbreviates "an object of
370 `TYPE` *type*" by saying "a *type*".
372 The laws of the Muddle world are defined by `EVAL`. In a very real
373 sense, `EVAL` is the only Muddle object which "acts", which "does
374 something". In "acting", `EVAL` is always "following the directions"
375 of some Muddle object. Every Muddle object should be looked upon as
376 supplying a set of directions to `EVAL`; what these directions are
377 depends heavily on the `TYPE` of the Muddle object.
379 Since `EVAL` is so ever-present, an abbreviation is in order:
380 "evaluates to *something*" or "`EVAL`s to *something*" should be taken
381 as an abbreviation for "when given to `EVAL`, causes `EVAL` to return
384 As abstract entities, Muddle objects are, of course, not "visible".
385 There is, however, a standard way of representing abstract Muddle
386 objects in the real world. The standard way of representing any given
387 `TYPE` of Muddle object will be given below when the `TYPE` is
388 introduced. These standard representations are what `READ`
389 understands, and what `PRINT` produces.
391 2.3. Example (TYPE FIX) \[1\]
392 -----------------------------
397 The following has occurred:
399 First, `READ` recognized the character `1` as the representation for
400 an object of `TYPE` `FIX`, in particular the one which corresponds to
401 the integer one. (`FIX` means integer, because the decimal point is
402 understood always to be in a fixed position: at the right-hand end.)
403 `READ` built the Muddle object corresponding to the decimal
404 representation typed, and returned it.
406 Then `EVAL` noted that its input was of `TYPE` `FIX`. An object of
407 `TYPE` `FIX` evaluates to itself, so `EVAL` returned its input
410 Then `PRINT` saw that its input was of `TYPE` `FIX`, and printed on
411 the terminal the decimal character representation of the corresponding
414 2.4. Example (TYPE FLOAT) \[1\]
415 -------------------------------
420 What went on was entirely analogous to the preceding example, except
421 that the Muddle object was of `TYPE` `FLOAT`. (`FLOAT` means a real
422 number (of limited precision), because the decimal point can float
423 around to any convenient position: an internal exponent part tells
424 where it "really" belongs.)
426 2.5. Example (TYPE ATOM, PNAME) \[1\]
427 -------------------------------------
432 This time a lot more has happened.
434 `READ` noted that what was typed had no special meaning, and therefore
435 assumed that it was the representation of an identifier, that is, an
436 object of `TYPE` `ATOM`. ("Atom" means more or less *indivisible*.)
437 `READ` therefore attempted to look up the representation in a table it
438 keeps for such purposes \[a `LIST` of `OBLISTS`, available as the
439 local value of the `ATOM` `OBLIST`\]. If `READ` finds an `ATOM` in its
440 table corresponding to the representation, that `ATOM` is returned as
441 `READ`'s value. If `READ` fails in looking up, it creates a new
442 `ATOM`, puts it in the table with the representation read \[`INSERT`
443 into `<1 .OBLIST>` usually\], and returns the new `ATOM`. Nothing
444 which could in any way be referenced as a legal "value" is attached to
445 the new `ATOM`. The initially-typed representation of an `ATOM`
446 becomes its `PNAME`, meaning its name for `PRINT`. One often
447 abbreviates "object of `TYPE` `ATOM` with `PNAME` *name*" by saying
450 `EVAL`, given an `ATOM`, returned just that `ATOM`.
452 `PRINT`, given an `ATOM`, typed out its `PNAME`.
454 At the end of this chapter, the question "what is a legal `PNAME`"
455 will be considered. Further on, the methods used to attach values to
456 `ATOM`s will be described.
458 2.6. FIXes, FLOATs, and ATOMs versus READ: Specifics
459 ----------------------------------------------------
461 ### 2.6.1. READ and FIXed-point Numbers
463 `READ` considers any grouping of characters which are solely digits to
464 be a `FIX`, and the radix of the representation is decimal by default.
465 A `-` (hyphen) immediately preceding such a grouping represents a
466 negative `FIX`. The largest `FIX` representable on the PDP-10 is two
467 to the 35th power minus one, or 34,359,738,367 (decimal): the smallest
468 is one less than the negative of that number. If you attempt to type
469 in a `FIX` outside that range, `READ` converts it to a `FLOAT`; if a
470 program you write attempts to produce a `FIX` outside that range, an
471 overflow error will occur (unless it is disabled).
473 The radix used by `READ` and `PRINT` is changeable by the user;
474 however, there are two formats for representations of `FIX`es which
475 cause `READ` to use a specified radix independent of the current one.
476 These are as follows:
478 1. If a group of digits is immediately followed by a period (`.`),
479 `READ` interprets that group as the decimal representation of a
480 `FIX`. For example, `10.` is always interpreted by `READ` as the
481 decimal representation of ten.
483 2. If a group of digits is immediately enclosed on both sides with
484 asterisks (`*`), `READ` interprets that group as the octal
485 representation of a `FIX`. For example, `*10*` is always
486 interpreted by `READ` as the octal representation of eight.
488 ### 2.6.2. READ and PRINT versus FLOATing-point Numbers
490 `PRINT` can produce, and `READ` can understand, two different formats
491 for objects of `TYPE` `FLOAT`. The first is "decimal-point" notation,
492 the second is "scientific" notation. Decimal radix is always used for
493 representations of `FLOAT`s.
495 "Decimal-point" notation for a `FLOAT` consists of an arbitrarily long
496 string of digits containing one `.` (period) which is followed by at
497 least one digit. `READ` will make a `FLOAT` out of any such object,
498 with a limit of precision of one part in 2 to the 27th power.
500 "Scientific" notation consists of:
504 2. immediately followed by `E` or `e` (upper or lower case letter E),
506 3. immediately followed by an exponent,
508 where a "number" is an arbitrarily long string of digits, with or
509 without a decimal point (see following note): an an "exponent" is up
510 to two digits worth of `FIX`. This notation represents the "number" to
511 the "exponent" power of ten. Note: if the "number" as above would by
512 itself be a `FIX`, and if the "exponent" is positive, and if the
513 result is within the allowed range of `FIX`es, then the result will be
514 a `FIX`. For example, `READ` understands `10E1` as `100` (a `FIX`),
515 but `10E-1` as `1.0000000` (a `FLOAT`).
517 The largest-magnitude `FLOAT` which can be handled without overflow is
518 `1.7014118E+38` (decimal radix). The smallest-magnitude `FLOAT` which
519 can be handled without underflow is `.14693679E-38`.
521 ### 2.6.3. READ and PNAMEs
523 The question "what is a legal `PNAME`?" is actually not a reasonable
524 one to ask: **any** non-empty string of **arbitrary** characters can
525 be the `PNAME` of an `ATOM`. However, some `PNAME`s are easier to type
526 to `READ` than others. But even the question "what are easily typed
527 `PNAME`s?" is not too reasonable, because: `READ` decides that a group
528 of characters is a `PNAME` by **default**; if it can't possibly be
529 anything else, it's a `PNAME`. So, the rules governing the
530 specification of `PNAME`s are messy, and best expressed in terms of
531 what is not a `PNAME`. For simplicity, you can just consider any
532 uninterrupted group of upper- and lower-case letters and (customarily)
533 hyphens to be a `PNAME`; that will always work. If you neither a
534 perfectionist nor a masochist, skip to the next chapter.
536 #### 2.6.3.1. Non-PNAMEs
538 A group of characters is **not** a `PNAME` if:
540 1. It represents a `FLOAT` or a `FIX`, as described above -- that is,
541 it is composed wholly of digits, or digits and a single `.`
542 (period) or digits and a `.` and the letter `E` or `e` (with
543 optional minus signs in the right places).
545 2. It begins with a `.` (period).
547 3. It contains -- if typed interactively -- any of the characters
548 which have special interactive effects: `^@`, `^D`, `^L`, `^G`,
549 `^O`, `$` (`ESC`), rubout.
551 4. It contains a format character -- space, carriage-return,
552 line-feed, form-feed, horizontal tab, vertical tab.
554 5. It contains a `,` (comma) or a `#` (number sign) or a `'` (single
555 quote) or a `;` (semicolon) or a `%` (percent sign).
557 6. It contains any variety of bracket -- `(` or `)` or `[` or `]` or
558 `<` or `>` or `{` or `}` or `"`.
560 In addition, the character `\` (backslash) has a special
561 interpretation, as mentioned below. Also the pair of characters `!-`
562 (exclamation-point hyphen) has an extremely special interpretation,
563 which you will reach at chapter 15.
565 The characters mentioned in cases 4 through 6 are "separators" -- that
566 is, they signal to `READ` that whatever it was that the preceding
567 characters represented, it's done now. They can also indicate the
568 start of a new object's representation (all the opening "brackets" do
571 #### 2.6.3.2. Examples
573 The following examples are not in the "standard format" of "*line
574 typed in*`$` *result printed*", because they are not, in some cases,
575 completed objects; hence, `READ` would continue waiting for the
576 brackets to be closed. In other cases, they will produce errors during
577 `EVAL`uation if other -- currently irrelevant -- conditions are not
578 met. Instead, the right-hand column will be used to state just what
579 `READ` thought the input in the left-hand column really was.
581 ------------------------------------------------------------------------------------
583 --------------------------- --------------------------------------------------------
584 `ABC$` an `ATOM` of `PNAME` `ABC`
586 `abc$` an `ATOM` of `PNAME` `abc`
588 `ARBITRARILY-LONG-PNAME$` an `ATOM` of `PNAME` `ARBITRARILY-LONG-PNAME`
590 `1.2345$` a `FLOAT`, `PRINT`ed as `1.2345000`
592 `1.2.345$` an `ATOM` of `PNAME` `1.2.345`
594 `A.or.B$` a `ATOM` of `PNAME` `A.or.B`
596 `.A.or.B$` not an `ATOM`, but (as explained later) a `FORM`
597 containing an `ATOM` of `PNAME` `A.or.B`.
599 `MORE THAN ONE$` three `ATOM`s, with `PNAME`s `MORE`, and `THAN`, and
602 `ab(cd$` an `ATOM` of `PNAME` `ab`, followed by the start of
603 something else (The something else will contain an
604 `ATOM` of `PNAME` beginning `cd.`)
606 `12345A34$` an `ATOM` of `PNAME` `12345A35` (If the A had been an E,
607 the object would have been a `FLOAT`.)
608 ------------------------------------------------------------------------------------
610 #### 2.6.3.3. Â (Backslash) in ATOMs
612 If you have a strange, uncontrollable compulsion to have what were
613 referred to as "separators" above as part of the `PNAME`s of your
614 `ATOM`s, you can do so by preceding them with the character `\`
615 (backslash). `\` will also magically turn an otherwise normal `FIX` or
616 `FLOAT` into an `ATOM` if it appears amongst the digits. In fact,
617 backslash in front of **any** character changes it from something
618 special to "just another character" (including the character `\`). It
619 is an escape character.
621 When `PRINT` confronts an `ATOM` which had to be backslashed in order
622 to be an `ATOM`, it will dutifully type out the required `\`s. They
623 will not, however, necessarily be where you typed them; they will
624 instead be at those positions which will cause `READ` the least grief.
625 For example, `PRINT` will type out a `PNAME` which consists wholly of
626 digits by first typing a `\` and then typing the digits - no matter
627 where you originally typed the `\` (or `\`s).
629 #### 2.6.3.4. Examples of Awful ATOMs
631 The following examples illustrate the amount of insanity that can be
632 perpetrated by using `\`. The format of the examples is again
633 non-standard, this time not because anything is unfinished or in
634 error, but because commenting is needed: `PRINT` doesn't do it full
637 -------------------------------------------------------------------------------
639 ------------------------ ------------------------------------------------------
640 `a\ one\ and\ a\ two$` one `ATOM`, whose `PNAME` has four spaces in it
642 `1234\56789$` an `ATOM` of `PNAME` `123456789`, which `PRINT`s as
645 `123\ $` an `ATOM` of `PNAME` `123space`, which `PRINT`s as
646 `\123\`, with a space on the end
648 `\\$` an `ATOM` whose `PNAME` is a single backslash
649 -------------------------------------------------------------------------------
651 Chapter 3. Built-in Functions
652 =============================
654 3.1. Representation \[1\]
655 -------------------------
657 Up to this point, all the objects we have been concerned with have had
658 no internal structure discernible in Muddle. While the characteristics
659 of objects with internal structure differ greatly, the way `READ` and
660 `PRINT` handle them is uniform, to wit:
662 - `READ`, when applied to the representation of a structured object,
663 builds and returns an object of the indicated `TYPE` with elements
664 formed by applying `READ` to each of their representations in
667 - `PRINT`, when applied to a structured object, produces a
668 representation of the object, with its elements represented as
669 `PRINT` applied to each of them in turn.
671 A Muddle object which is used to represent the application of a
672 function to its arguments is an argument of `TYPE` `FORM`. Its printed
675 < func arg-1 arg-2 ... arg-N >
677 where *func* is an object which designates the function to be applied,
678 and *arg-1* through *arg-N* are object which designate the arguments
679 or "actual parameters" or "inputs". A `FORM` is just a structured
680 object which is stored and can be manipulated like a `LIST` (its
681 "primitive type" is `LIST` -- chapter 6). The application of the
682 function to the arguments is done by `EVAL`. The usual meaning of
683 "function" (uncapitalized) in this document will be anything
684 applicable to arguments.
686 3.2. Evaluation \[1\]
687 ---------------------
689 `EVAL` applied to a `FORM` acts as if following these directions:
691 First, example the *func* (first element) of the `FORM`. If it is an
692 `ATOM`, look at its "value" (global or local, in that order -- see
693 next chapter). If it is not an `ATOM`, `EVAL` it and look at the
694 result of the evaluation. If what you are looking at is not something
695 which can be applied to arguments, complain (via the `ERROR`
696 function). Otherwise, inspect what you are looking at and follow its
697 directions in evaluating or not evaluating the arguments (chapters 9
698 and 19) and then "apply the function" -- that is, `EVAL` the body of
699 the object gotten from *func*.
701 3.3. Built-in Functions (TYPE SUBR, TYPE FSUBR) \[1\]
702 -----------------------------------------------------
704 The built-in functions of Muddle come in two varieties: those which
705 have all their arguments `EVAL`ed before operating on them (`TYPE`
706 `SUBR`, for "subroutine", pronounced "subber") and those which have
707 none of their arguments `EVAL`ed (`TYPE` `FSUBR`, historically from
708 Lisp (Moon, 1974), pronounced "effsubber"). Collectively they will be
709 called `F/SUBR`s, although that term is not meaningful to the
710 interpreter. See appendix 2 for a listing of all `F/SUBR`s and short
711 descriptions. The term "Subroutine" will be used herein to mean both
712 `F/SUBR`s and compiled user programs (`RSUBR`s and `RSUBR-ENTRY`s --
715 Unless otherwise stated, **every** Muddle built-in Subroutine is of
716 `TYPE` **`SUBR`**. Also, when it is stated that an argument of a
717 `SUBR` must be of a particular `TYPE`, note that this means that
718 `EVAL` of what is there must be of the particular `TYPE`.
720 Another convenient abbreviation which will be used is "the `SUBR`
721 *pname*" in place of "the `SUBR` which is initially the 'value' of the
722 `ATOM` of `PNAME` *pname*". "The `FSUBR` *pname*" will be used with a
725 3.4. Examples (+ and FIX; Arithmetic) \[1\]
726 -------------------------------------------
731 The `SUBR` `+` adds numbers. Most of the usual arithmetic functions
732 are Muddle `SUBR`s: `+`, `-`, `*`, `/`, `MIN`, `MAX`, `MOD`, `SIN`,
733 `COS`, `ATAN`, `SQRT`, `LOG`, `EXP`, `ABS`. (See appendix 2 for short
734 descriptions of these.) All except `MOD`, which wants `FIX`es, are
735 indifferent as to whether their arguments are `FLOAT` or `FIX` or a
736 mixture. In the last case they exhibit "contagious `FLOAT`ing": one
737 argument of `TYPE` `FLOAT` forces the result to be of `TYPE` `FLOAT`.
742 The `SUBR` `FIX` explicitly returns a `FIX`ed-point number
743 corresponding to a `FLOAT`ing-point number. `FLOAT` does the opposite.
747 <SQRT <+ <* 3 3> <* 4 4>>>$
758 Note this last result: the division of two `FIX`es gives a `FIX` with
759 truncation, not rounding, of the remainder: the intermediate result
760 remains a `FIX` until a `FLOAT` argument is encountered.
762 3.5. Arithmetic Details
763 -----------------------
765 `+`, `-`, `*`, `/`, `MIN`, and `MAX` all take any number of arguments,
766 doing the operation with the first argument and the second, then with
767 that result and the third argument, etc. If called with no arguments,
768 each returns the identity for its operation (`0`, `0`, `1`, `1`, the
769 greatest `FLOAT`, and the least `FLOAT`, respectively); if called with
770 one argument, each acts as if the identity and the argument has been
771 supplied. They all will cause an overflow or underflow error if any
772 result, intermediate or final, is too large or too small for the
773 machine's capacity. (That error can be disabled if necessary --
776 One arithmetic function that always requires some discussion is the
777 pseudo-random-number generator. Muddle's is named `RANDOM`, and it
778 always returns a `FIX`, uniformly distributed over the whole range of
779 `FIX`es. If `RANDOM` is never called with arguments, it always returns
780 the exact same sequence of numbers, for convenience in debugging.
781 "Debugged" programs should give `RANDOM` two arguments on the first
782 call, which become seeds for a new sequence. Popular choices of new
783 seeds are the numbers given by `TIME` (which see), possibly with bits
784 modified (chapter 18). Example ("pick a number from one to ten"):
786 <+ 1 <MOD <RANDOM> 10>>$
789 Chapter 4. Values of Atoms
790 ==========================
795 There are two kinds of "value" which can be attached to an `ATOM`. An
796 `ATOM` can have either, both, or neither. They interact in no way
797 (except that alternately referring to one and then the other is
798 inefficient). These two values are referred to as the **local value**
799 and the **global value** of an `ATOM`. The terms "local" and "global"
800 are relative to `PROCESS`es (chapter 20), not functions or programs.
801 The `SUBR`s which reference the local and global values of an `ATOM`,
802 and some of the characteristics of local versus global values, follow.
807 ### 4.2.1. SETG \[1\]
809 A global value can be assigned to an `ATOM` by the `SUBR` `SETG` ("set
814 where *atom* must `EVAL` to an `ATOM`, and *any* can `EVAL` to
815 anything. `EVAL` of the second argument becomes the global value of
816 `EVAL` of the first argument. The value returned by the `SETG` is its
817 second argument, namely the new global value of *atom*.
821 <SETG FOO <SETG BAR 500>>$
824 The above made the global values of both the `ATOM` `FOO` and the
825 `ATOM` `BAR` equal to the `FIX`ed-point number 500.
830 That made the global value of the `ATOM` `BAR` equal to the `ATOM`
833 ### 4.2.2. GVAL \[1\]
835 The `SUBR` `GVAL` ("global value") is used to reference the global
840 returns as a value the global value of *atom*. If *atom* does not
841 evaluate to an `ATOM`, or if the `ATOM` to which it evaluates has no
842 global value, an error occurs.
844 `GVAL` applied to an `ATOM` anywhere, in any `PROCESS`, in any
845 function, will return the same value. Any `SETG` anywhere changes the
846 global value for everybody. Global values are context-independent.
848 `READ` understands the character `,` (comma) as an abbreviation for an
849 application of `GVAL` to whatever follows it. `PRINT` always
850 translates an application of `GVAL` into the comma format. The
851 following are absolutely equivalent:
855 Assuming the examples in section 4.2.1 were carried out in the order
856 given, the following will evaluate as indicated:
867 ### 4.2.3. Note on SUBRs and FSUBRs
869 The initial `GVAL`s of the `ATOM`s used to refer to Muddle "built-in"
870 Subroutines are the `SUBR`s and `FSUBR`s which actually get applied
871 when those `ATOM`s are referenced. If you don't like the way those
872 supplied routines work, you are perfectly free to `SETG` the `ATOM`s
873 to your own versions.
879 ("global unassign") causes *atom* to have no assigned global value,
880 whether or not it had one previously. The storage used for the global
881 value can become free for other uses.
888 The `SUBR` `SET` is used to assign a local value to an `ATOM`.
889 Applications of `SET` are of the form
893 `SET` returns `EVAL` of *any* just like `SETG`.
897 <SET BAR <SET FOO 100>>$
900 Both `BAR` and `FOO` have been given local values equal to the
901 `FIX`ed-point number 100.
906 `FOO` has been given the local value `BAR`.
908 Note that neither of the above did anything to any global values `FOO`
909 and `BAR` might have had.
911 ### 4.3.2. LVAL \[1\]
913 The `SUBR` used to extract the local value of an `ATOM` is named
914 `LVAL`. As with `GVAL`, `READ` understands an abbreviation for an
915 application of `LVAL`: the character `.` (period), and `PRINT`
916 produces it. The following two representations are equivalent, and
917 when `EVAL` operates on the corresponding Muddle object, it returns
918 the current local value of *atom*:
922 The local value of an `ATOM` is unique within a `PROCESS`. `SET`ting
923 an `ATOM` in one `PROCESS` has no effect on its `LVAL` in another
924 `PROCESS`, because each `PROCESS` has its own "control stack"
925 (chapters 20 and 22).
927 Assume **all** of the previous examples in this chapter have been
928 done. Then the following evaluate as indicated:
943 causes *atom* to have no assigned local value, whether or not it had
949 `VALUE` is a `SUBR` which takes an `ATOM` as an argument, and then:
951 1. if the `ATOM` has an `LVAL`, returns the `LVAL`;
952 2. if the `ATOM` has no `LVAL` but has a `GVAL`, returns the `GVAL`;
953 3. if the `ATOM` has neither a `GVAL` nor an `LVAL`, calls the
956 This order of seeking a value is the **opposite** of that used when an
957 `ATOM` is the first element of a `FORM`. The latter will be called the
958 G/LVAL, even though that name is not used in Muddle.
975 Chapter 5. Simple Functions
976 ===========================
981 The Muddle equivalent of a "program" (uncompiled) is an object of
982 `TYPE` `FUNCTION`. Actually, full-blown "programs" are usually
983 composed of sets of `FUNCTION`s, with most `FUNCTION`s in the set
984 acting as "subprograms".
986 A `FUNCTION` may be considered to be a `SUBR` or `FSUBR` which you
987 yourself define. It is "run" by using a `FORM` to apply it to
988 arguments (for example, <*function arg-1 arg-2 ...*>), and it
989 always "returns" a single object, which is used as the value of the
990 `FORM` that applied it. The single object may be ignored by whatever
991 "ran" the `FUNCTION` -- equivalent to "returning no value" -- or it
992 may be a structured object containing many objects -- equivalent to
993 "returning many values". Muddle is an "applicative" language, in
994 contrast to "imperative" languages like Fortran. In Muddle it is
995 impossible to return values through arguments in the normal case; they
996 can be returned only as the value of the `FORM` itself, or as side
997 effects to structured objects or global values.
999 In this chapter a simple subset of the `FUNCTION`s you can write is
1000 presented, namely `FUNCTION`s which "act like" `SUBR`s with a fixed
1001 number of arguments. While this class corresponds to about 90% of the
1002 `FUNCTION`s ever written, you won't be able to do very much with them
1003 until you read further and learn more about Muddle's control and
1004 manipulatory machinery. However, all that machinery is just a bunch of
1005 `SUBR`s and `FSUBR`s, and you already know how to "use" them; you just
1006 need to be told what they do. Once you have `FUNCTION`s under your
1007 belt, you can immediately make use of everything presented from this
1008 point on in the document. In fact, we recommend that you do so.
1010 5.2. Representation \[1\]
1011 -------------------------
1013 A `FUNCTION` is just another data object in Muddle, of `TYPE`
1014 `FUNCTION`. It can be manipulated like any other data object. `PRINT`
1015 represents a `FUNCTION` like this:
1017 #FUNCTION (elements)
1019 that is, a number sign, the `ATOM` `FUNCTION`, a left parenthesis,
1020 each of the elements of the `FUNCTION`, and a right parenthesis. Since
1021 `PRINT` represents `FUNCTION`s like this, you can type them in to
1022 `READ` this way. (But there are a few `TYPE`s for which that
1023 implication is false.)
1025 The elements of a `FUNCTION` can be "any number of anythings";
1026 however, when you **use** a `FUNCTION` (apply it with a `FORM`),
1027 `EVAL` will complain if the `FUNCTION` does not look like
1029 #FUNCTION (act:atom arguments:list decl body)
1031 where *act* and *decl* are optional (section 9.8 and chapter 14);
1032 *body* is **at least one** Muddle object -- any old Muddle object;
1033 and, in this simple case, *arguments* is
1035 (any number of ATOMs)
1037 that is, something `READ` and `PRINT`ed as: left parenthesis, any
1038 number -- including zero -- of `ATOM`s, right parenthesis. (This is
1039 actually a normal Muddle object of `TYPE` `LIST`, containing only
1042 Thus, these `FUNCTION`s will cause errors -- but only **when used**:
1045 --------------------------- ----------------------------------
1046 `#FUNCTION ()` -- no argument `LIST` or body
1047 `#FUNCTION ((1) 2 7.3)` -- non-`ATOM` in argument `LIST`
1048 `#FUNCTION ((A B C D))` -- no body
1049 `#FUNCTION (<+ 1 2> A C)` -- no argument `LIST`
1051 These `FUNCTION`s will never cause errors because of format:
1053 #FUNCTION (() 1 2 3 4 5)
1055 #FUNCTION (()()()()()()()())
1056 #FUNCTION ((A B C D EE F G H HIYA) <+ .A .HIYA>)
1057 #FUNCTION ((Q) <SETG C <* .Q ,C>> <+ <MOD ,C 3> .Q>)
1059 and the last two actually do something which might be useful. (The
1060 first three are rather pathological, but legal.)
1062 5.3. Application of FUNCTIONs: Binding \[1\]
1063 --------------------------------------------
1065 `FUNCTION`s, like `SUBR`s and `FSUBR`s, are applied using `FORM`s. So,
1067 <#FUNCTION ((X) <* .X .X>) 5>$
1070 applied the indicated `FUNCTION` to 5 and returned 25.
1072 What `EVAL` does when applying a `FUNCTION` is the following:
1074 1. Create a "world" in which the `ATOM`s of the argument `LIST` have
1075 been **`SET`** to the values applied to the `FUNCTION`, and all
1076 other `ATOM`s have their original values. This is called
1079 - In the above, this is a "world" in which `X` is `SET` to `5`.
1081 2. In that new "world", evaluate all the objects in the body of the
1082 `FUNCTION`, one after the other, from first to last.
1084 - In the above, this means evaluate `<* .X .X>` in a "world" where
1085 `X` is `SET` to `5`.
1087 3. Throw away the "world" created, and restore the `LVAL`s of all
1088 `ATOM`s bound in this application of the `FUNCTION` to their
1089 originals (if any). This is called "unbinding".
1091 - In the above, this simply gives `X` back the local value, if any,
1092 that it had before binding.
1094 4. Return as a value the **last value obtained** when the
1095 `FUNCTION`'s body was evaluated in step (2).
1097 - In the above, this means return `25` as the value.
1099 The "world" mentioned above is actually an object of `TYPE`
1100 `ENVIRONMENT`. The fact that such "worlds" are separate from the
1101 `FUNCTION`s which cause their generation means that **all** Muddle
1102 `FUNCTION`s can be used recursively.
1104 The only thing that is at all troublesome in this sequence is the
1105 effect of creating these new "worlds", in particular, the fact that
1106 the **previous** world is completely restored. This means that if,
1107 inside a `FUNCTION`, you `SET` one of its argument `ATOM`s to
1108 something, that new `LVAL` will **not** be remembered when `EVAL`
1109 leaves the `FUNCTION`. However, if you `SET` an `ATOM` which is
1110 **not** in the argument `LIST` (or `SETG` **any** `ATOM`) the new
1111 local (or global) value **will** be remembered. Examples:
1115 <#FUNCTION ((X) <SET X <* .X .X>>) 5>$
1124 <#FUNCTION ((X) <SET Y <* .X .X>>) 5>$
1129 By using `PRINT` as a `SUBR`, we can "see" that an argument's `LVAL`
1130 really is changed while `EVAL`uating the body of a `FUNCTION`:
1134 <#FUNCTION ((X) <PRINT .X> <+ .X 10>) 3>$
1139 The first number after the application `FORM` was typed out by the
1140 `PRINT`; the second is the value of the application.
1142 Remembering that `LVAL`s of `ATOM`s **not** in argument `LIST`s are
1143 not changed, we can reference them within `FUNCTION`s, as in
1147 <#FUNCTION ((Y) </ .Z .Y>) 5>$
1150 `ATOM`s used like `Z` or `Y` in the above examples are referred to as
1151 "free variables". The use of free variables, while often quite
1152 convenient, is rather dangerous unless you know **exactly** how a
1153 `FUNCTION` will **always** be used: if a `FUNCTION` containing free
1154 variables is used within a `FUNCTION` within a `FUNCTION` within ...,
1155 one of those `FUNCTION`s might just happen to use your free variable
1156 in its argument `LIST`, binding it to some unknown value and possibly
1157 causing your use of it to be erroneous. Please note that "dangerous",
1158 as used above, really means that it may be effectively **impossible**
1159 (1) for other people to use your `FUNCTION`s, and (2) for **you** to
1160 use your `FUNCTION`s a month (two weeks?) later.
1162 5.4. Defining FUNCTIONs (FUNCTION and DEFINE) \[1\]
1163 ---------------------------------------------------
1165 Obviously, typing `#FUNCTION (...)` all the time is neither reasonable
1166 nor adequate for many purposes. Normally, you just want a `FUNCTION`
1167 to be the `GVAL` of some `ATOM` -- the way `SUBR`s and `FSUBR`s are --
1168 so you can use it repeatedly (and recursively). Note that you
1169 generally do **not** want a `FUNCTION` to be the `LVAL` of an `ATOM`;
1170 this has the same problems as free variables. (Of course, there are
1171 always cases where you are being clever and **want** the `ATOM` to be
1174 One way to "name" a `FUNCTION` is
1176 <SETG SQUARE #FUNCTION ((X) <* .X .X>)>$
1177 #FUNCTION ((X) <* .X .X>
1186 Another way, which is somewhat cleaner in its typing:
1188 <SETG SQUARE <FUNCTION (X) <* .X .X>>>$
1189 #FUNCTION ((X) <* .X .X>
1191 `FUNCTION` is an `FSUBR` which simply makes a `FUNCTION` out of its
1192 arguments and returns the created `FUNCTION`.
1194 This, however, is generally the **best** way:
1196 <DEFINE SQUARE (X) <* .X .X>>$
1199 #FUNCTION ((X) <* .X .X>
1201 The last two lines immediately above are just to prove that `DEFINE`
1202 did the "right thing".
1204 `DEFINE` is an `FSUBR` which `SETG`s `EVAL` of its first argument to
1205 the `FUNCTION` it makes from the rest of its arguments, and then
1206 returns `EVAL` of its first argument. `DEFINE` obviously requires the
1207 least typing of the above methods, and is "best" from that standpoint.
1208 However, the real reason for using `DEFINE` is the following: If
1209 `EVAL` of `DEFINE`'s first argument **already has** a `GVAL`, `DEFINE`
1210 produces an error. This helps to keep you from accidentally redefining
1211 things -- like Muddle `SUBR`s and `FSUBR`s. The `SETG` constructions
1212 should be used only when you really do want to redefine something.
1213 `DEFINE` will be used in the rest of this document.
1215 \[Actually, if it is absolutely necessary to use `DEFINE` to
1216 "redefine" things, there is a "switch" which can be used: if the
1217 `LVAL` of the `ATOM` `REDEFINE` is `T` (or anything not of `TYPE`
1218 `FALSE`), `DEFINE` will produce no errors. The normal state can be
1219 restored by evaluating `<SET REDEFINE <>>`. See chapter 8.\]
1221 5.5. Examples (Comments) \[1\]
1222 ------------------------------
1224 Using `SQUARE` as defined above:
1226 <DEFINE HYPOT (SIDE-1 SIDE-2)
1227 ;"This is a comment. This FUNCTION finds the
1228 length of the hypotenuse of a right triangle
1229 of sides SIDE-1 and SIDE-2."
1230 <SQRT <+ <SQUARE .SIDE-1> <SQUARE .SIDE-2>>>>$
1235 Note that carriage-returns, line-feeds, tabs, etc. are just
1236 separators, like spaces. A comment is **any single** Muddle object
1237 which follows a `;` (semicolon). A comment can appear between any two
1238 Muddle objects. A comment is totally ignored by `EVAL` but remembered
1239 and associated by `READ` with the place in the `FUNCTION` (or any
1240 other structured object) where it appeared. (This will become clearer
1241 after chapter 13.) The `"`s (double-quotes) serve to make everything
1242 between them a single Muddle object, whose `TYPE` is `STRING` (chapter
1243 7). (`SQRT` is the `SUBR` which returns the square root of its
1244 argument. It always returns a `FLOAT`.)
1246 A whimsical `FUNCTION`:
1248 <DEFINE ONE (THETA) ;"This FUNCTION always returns 1."
1249 <+ <SQUARE <SIN .THETA>>
1250 <SQUARE <COS .THETA>>>>$
1257 `ONE` always returns (approximately) one, since the sum of the squares
1258 of sin(x) and cos(x) is unity for any x. (`SIN` and `COS` always
1259 return `FLOAT`s, and each takes its argument in radians. `ATAN`
1260 (arctangent) returns its value in radians. Any other trigonometric
1261 function can be compounded from these three.)
1263 Muddle doesn't have a general "to the power" `SUBR`, so let's define
1264 one using `LOG` and `EXP` (log base e, and e to a power, respectively;
1265 again, they return `FLOAT`s).
1267 <DEFINE ** (NUM PWR) <EXP <* .PWR <LOG .NUM>>>>$
1276 Two `FUNCTION`s which use a single global variable (Since the `GVAL`
1277 is used, it cannot be rebound.):
1279 <DEFINE START () <SETG GV 0>>$
1281 <DEFINE STEP () <SETG GV <+ ,GV 1>>>$
1292 `START` and `STEP` take no arguments, so their argument `LIST`s are
1295 An interesting, but pathological, `FUNCTION`:
1297 <DEFINE INC (ATM) <SET .ATM <+ ..ATM 1>>>$
1308 `INC` takes an **`ATOM`** as an argument, and `SET`s that `ATOM` to
1309 its current `LVAL` plus `1`. Note that inside `INC`, the `ATOM` `ATM`
1310 is `SET` to the `ATOM` which is its argument; thus `..ATM` returns the
1311 `LVAL` of the **argument**. However, there is a problem:
1320 LISTENING-AT-LEVEL 2 PROCESS 1
1321 <ARGS <FRAME <FRAME>>>$
1324 The error occurred because `.ATM` was `ATM`, the argument to `INC`,
1325 and thus `..ATM` was `ATM` also. We really want the outermost `.` in
1326 `..ATM` to be done in the "world" (`ENVIRONMENT`) which existed **just
1327 before** `INC` was entered -- and this definition of `INC` does both
1328 applications of `LVAL` in its own "world". Techniques for doing `INC`
1329 "correctly" will be covered below. Read on.
1331 Chapter 6. Data Types
1332 =====================
1337 A Muddle object consists of two parts: its `TYPE` and its "data part"
1338 (appendix 1). The interpretation of the "data part" of an object
1339 depends of course on its `TYPE`. The structural organization of an
1340 object, that is, the way it is organized in storage, is referred to as
1341 its "primitive type". While there are many different `TYPE`s of
1342 objects in Muddle, there are fewer primitive types.
1344 All structured objects in Muddle are ordered sequences of elements. As
1345 such, there are `SUBR`s which operate on all of them uniformly, as
1346 ordered sequences. On the other hand, the reason for having different
1347 primitive types of structured objects is that there are useful
1348 qualities of structured objects which are mutually incompatible. There
1349 are, therefore, `SUBR`s which do not work on all structured objects:
1350 these `SUBR`s exist to take full advantage of those mutually
1351 incompatible qualities. The most-commonly-used primitive types of
1352 structured objects are discussed in chapter 7, along with those
1353 special `SUBR`s operating on them.
1355 It is very easy to make a new Muddle object that differs from an old
1356 one only in `TYPE`, as long as the primitive type is unchanged. It is
1357 relatively difficult to make a new structured object that differs from
1358 an old one in primitive type, even if it has the same elements.
1360 Before talking any more about structured objects, some information
1361 needs to be given about `TYPE`s in general.
1363 6.2. Printed Representation \[1\]
1364 ---------------------------------
1366 There are many `TYPE`s for which Muddle has no specific
1367 representation. There aren't enough different kinds of brackets. The
1368 representation used for `TYPE`s without any special representation is
1370 #type representation-as-if-it-were-its-primitive-type
1372 `READ` will understand that format for **any** `TYPE`, and `PRINT`
1373 will use it by default. This representational format will be referred
1374 to below as "\# notation". It was used above to represent `FUNCTION`s.
1376 6.3. SUBRs Related to TYPEs
1377 ---------------------------
1379 ### 6.3.1. TYPE \[1\]
1383 returns an **`ATOM`** whose `PNAME` corresponds to the `TYPE` of
1384 *any*. There is no `TYPE` "TYPE". To type a `TYPE` (aren't homonyms
1385 wonderful?), just type the appropriate `ATOM`, like `FIX` or `FLOAT`
1386 or `ATOM` etc. However, in this document we will use the convention
1387 that a metasyntactic variable can have *type* for a "data type": for
1388 example, *foo:type* means that the `TYPE` of *foo* is `ATOM`, but the
1389 `ATOM` must be something that the `SUBR` `TYPE` can return.
1404 ### 6.3.2. PRIMTYPE \[1\]
1408 evaluates to the primitive type of *any*. The `PRIMTYPE` of *any* is
1409 an `ATOM` which also represents a `TYPE`. The way an object can be
1410 **manipulated** depends solely upon its `PRIMTYPE`; the way it is
1411 **evaluated** depends upon its `TYPE`.
1424 ### 6.3.3. TYPEPRIM \[1\]
1428 returns the `PRIMTYPE` of an object whose `TYPE` is *type*. *type* is,
1429 as usual, an `ATOM` used to designate a `TYPE`.
1444 ### 6.3.4. CHTYPE \[1\]
1448 ("change type") returns a new object that has `TYPE` *type* and the
1449 same "data part" as *any* (appendix 1).
1451 <CHTYPE (+ 2 2) FORM>$
1454 An error is generated if the `PRIMTYPE` of *any* is not the same as
1455 the `TYPEPRIM` of *type*. An error will also be generated if the
1456 attempted `CHTYPE` is dangerous and/or senseless, for example,
1457 `CHTYPE`ing a `FIX` to a `SUBR`. Unfortunately, there are few useful
1458 examples we can do at this point.
1460 \[`CHTYPE`ing a `FIX` to a `FLOAT` or vice versa produces, in general,
1461 nonsense, since the bit formats for `FIX`es and `FLOAT`s are
1462 different. The `SUBR`s `FIX` and `FLOAT` convert between those
1463 formats. Useful obscurity: because of their internal representations
1464 on the PDP-10, `<CHTYPE <MAX> FIX>` gives the least possible `FIX`,
1465 and analogously for `MIN`.\]
1467 Passing note: "\# notation" is just an instruction to `READ` saying
1468 "`READ` the representation of the `PRIMTYPE` normally and (literally)
1469 `CHTYPE` it to the specified `TYPE`". \[Or, if the `PRIMTYPE` is
1470 `TEMPLATE`, "apply the `GVAL` of the `TYPE` name (which should be a
1471 `TEMPLATE` constructor) to the given elements of the `PRIMTYPE`
1472 `TEMPLATE` as arguments."\]
1474 6.4. More SUBRs Related to TYPEs
1475 --------------------------------
1481 returns a `VECTOR` (chapter 7) containing just those `ATOM`s which can
1482 currently be returned by `TYPE` or `PRIMTYPE`. This is the very
1483 "`TYPE` vector" (section 22.1) that the interpreter uses: look, but
1484 don't touch. No examples: try it, or see appendix 3.
1486 ### 6.4.2. VALID-TYPE?
1490 returns `#FALSE ()` if *atom* is not the name of a `TYPE`, and the
1491 same object that `<TYPE-C atom>` (section 19.5) returns if it is.
1495 Muddle is a type-extensible language, in the sense that the programmer
1496 can invent new `TYPE`s and use them in every way that the predefined
1497 `TYPE`s can be used. A program-defined `TYPE` is called a `NEWTYPE`.
1498 New `PRIMTYPE`s cannot be invented except by changing the interpreter;
1499 thus the `TYPEPRIM` of a `NEWTYPE` must be chosen from those already
1500 available. But the name of a `NEWTYPE` (an `ATOM` of course) can be
1501 chosen freely -- so long as it does not conflict with an existing
1502 `TYPE` name. More importantly, the program that defines a `NEWTYPE`
1503 can be included in a set of programs for manipulating objects of the
1504 `NEWTYPE` in ways that are more meaningful than the predefined `SUBR`s
1507 Typically an object of a `NEWTYPE` is a structure that is a model of
1508 some entity in the real world -- or whatever world the program is
1509 concerned with -- and the elements of the structure are models of
1510 parts or aspects of the real-world entity. A `NEWTYPE` definition is a
1511 convenient way of formalizing this correspondence, of writing it down
1512 for all to see and use rather than keeping it in your head. If the
1513 defining set of programs provides functions for manipulating the
1514 `NEWTYPE` objects in all ways that are meaningful for the intended
1515 uses of the `NEWTYPE`, then any other program that wants to use the
1516 `NEWTYPE` can call the manipulation functions for all its needs, and
1517 it need never know or care about the internal details of the `NEWTYPE`
1518 objects. This technique is a standard way of providing modularity and
1521 For example, suppose you wanted to deal with airline schedules. If you
1522 were to construct a set of programs that define and manipulate a
1523 `NEWTYPE` called `FLIGHT`, then you could make that set into a
1524 standard package of programs and call on it to handle all information
1525 pertaining to scheduled airline flights. Since all `FLIGHT`s would
1526 have the same quantity of information (more or less) and you would
1527 want quick access to individual elements, you would not want the
1528 `TYPEPRIM` to be `LIST`. Since the elements would be of various
1529 `TYPE`s, you would not want the `TYPEPRIM` to be `UVECTOR` -- nor its
1530 variations `STRING` or `BYTES`. The natural choice would be a
1531 `TYPEPRIM` of `VECTOR` (although you could gain space and lose time
1532 with `TEMPLATE` instead).
1534 Now, the individual elements of a `FLIGHT` would, no doubt, have
1535 `TYPE`s and meanings that don't change. The elements of a `FLIGHT`
1536 might be airline code, flight number, originating-airport code, list
1537 of intermediate stops, destination-airport code, type of aircraft,
1538 days of operation, etc. Each and every `FLIGHT` would have the airline
1539 code for its first element (say), the flight number for its second,
1540 and so on. It is natural to invent names (`ATOM`s) for these elements
1541 and always refer to the elements by name. For example, you could
1542 `<SETG AIRLINE 1>` or `<SETG AIRLINE <OFFSET 1 FLIGHT>>` -- and in
1543 either case `<MANIFEST AIRLINE>` so the compiler can generate more
1544 efficient code. Then, if the local value of `F` were a `FLIGHT`,
1545 `<AIRLINE .F>` would return the airline code, and `<AIRLINE .F AA>`
1546 would set the airline code to `AA`. Once that is done, you can forget
1547 about which element comes first: all you need to know are the names of
1550 The next step is to notice that, outside the package of `FLIGHT`
1551 functions, no one needs to know whether `AIRLINE` is just an offset or
1552 in fact a function of some kind. For example, the scheduled duration
1553 of a flight might not be explicitly stored in a `FLIGHT`, just the
1554 scheduled times of departure and arrival. But, if the package had the
1555 proper `DURATION` function for calculating the duration, then the call
1556 `<DURATION .F>` could return the duration, no matter how it is found.
1557 In this way the internal details of the package are conveniently
1558 hidden from view and abstracted away.
1560 The form of `NEWTYPE` definition allows for the `TYPE`s of all
1561 components of a `NEWTYPE` to be declared (chapter 14), for use both by
1562 a programmer while debugging programs that use the `NEWTYPE` and by
1563 the compiler for generating faster code. It is very convenient to have
1564 the type declaration in the `NEWTYPE` definition itself, rather than
1565 replicating it everywhere the `NEWTYPE` is used. (If you think this
1566 declaration might be obtrusive while debugging the programs in the
1567 `NEWTYPE` package, when inconsistent improvements are being made to
1568 various programs, you can either dissociate any declaration from the
1569 `NEWTYPE` or turn off Muddle type-checking completely. Actually this
1570 declaration is typically more useful to a programmer during
1571 development than it is to the compiler.)
1575 returns *atom*, after causing it to become the representation of a
1576 brand-new `TYPE` whose `PRIMTYPE` is `<TYPEPRIM type>`. What `NEWTYPE`
1577 actually does is make *atom* a legal argument to `CHTYPE` and
1578 `TYPEPRIM`. (Note that names of new `TYPE`s can be blocked lexically
1579 to prevent collision with other names, just like any other `ATOM`s --
1580 chapter 15.) Objects of a `NEWTYPE`-created `TYPE` can be generated by
1581 creating an object of the appropriate `PRIMTYPE` and using `CHTYPE`.
1582 They will be `PRINT`ed (initially), and can be directly typed in, by
1583 the use of "\# notation" as described above. `EVAL` of any object
1584 whose `TYPE` was created by `NEWTYPE` is initially the object itself,
1585 and, initially, you cannot `APPLY` something of a generated `TYPE` to
1586 arguments. But see below.
1590 <NEWTYPE GARGLE FIX>$
1594 <SET A <CHTYPE 1 GARGLE>>$
1595 #GARGLE *000000000001*
1596 <SET B #GARGLE 100>$
1597 #GARGLE *000000000144*
1603 ### 6.4.4. PRINTTYPE, EVALTYPE and APPLYTYPE
1605 <PRINTTYPE type how>
1609 <APPLYTYPE type how>
1611 all return *type*, after specifying *how* Muddle is to deal with it.
1613 These three `SUBR`s can be used to make newly-generated `TYPE`s behave
1614 in arbitrary ways, or to change the characteristics of standard Muddle
1615 `TYPE`s. `PRINTTYPE` tells Muddle how to print *type*, `EVALTYPE` how
1616 to evaluate it, and `APPLYTYPE` how to apply it in a `FORM`.
1618 *how* can be either a `TYPE` or something that can be applied to
1621 If *how* is a `TYPE`, Muddle will treat *type* just like the `TYPE`
1622 given as *how*. *how* must have the same `TYPEPRIM` as *type*.
1624 If *how* is applicable, it will be used in the following way:
1626 For `PRINTTYPE`, *how* should take one argument: the object being
1627 output. *how* should output something without formatting
1628 (`PRIN1`-style); its result is ignored. (Note: *how* cannot use an
1629 output `SUBR` on *how*'s own *type*: endless recursion will result.
1630 `OUTCHAN` is bound during the application to the `CHANNEL` in use, or
1631 to a pseudo-internal channel for `FLATSIZE` -- chapter 11.) If *how*
1632 is the `SUBR` `PRINT`, *type* will receive no special treatment in
1633 printing, that is, it will be printed as it was in an initial Muddle
1634 or immediately after its defining `NEWTYPE`.
1636 For `EVALTYPE`, *how* should take one argument: the object being
1637 evaluated. The value returned by *how* will be used as `EVAL` of the
1638 object. If *how* is the `SUBR` `EVAL`, *type* will receive no special
1639 treatment in its evaluation.
1641 For `APPLYTYPE`, *how* should take at least one argument. The first
1642 argument will be the object being applied: the rest will be the
1643 objects it was given as arguments. The result returned by *how* will
1644 be used as the result of the application. If *how* is the `SUBR`
1645 `APPLY`, *type* will receive no special treatment in application to
1648 If any of these `SUBR`s is given only one argument, that is if *how*
1649 is omitted, it returns the currently active *how* (a `TYPE` or an
1650 applicable object), or else `#FALSE ()` if *type* is receiving no
1651 special treatment in that operation.
1653 Unfortunately, these examples are fully understandable only after you
1654 have read through chapter 11.
1656 <DEFINE ROMAN-PRINT (NUMB)
1657 <COND (<OR <L=? .NUMB 0> <G? .NUMB 3999>>
1658 <PRINC <CHTYPE .NUMB TIME>>)
1660 <RCPRINT </ .NUMB 1000> '![!\M]>
1661 <RCPRINT </ .NUMB 100> '![!\C !\D !\M]>
1662 <RCPRINT </ .NUMB 10> '![!\X !\L !\C]>
1663 <RCPRINT .NUMB '![!\I !\V !\X]>)>>$
1666 <DEFINE RCPRINT (MODN V)
1667 <SET MODN <MOD .MODN 10>>
1668 <COND (<==? 0 .MODN>)
1669 (<==? 1 .MODN> <PRINC <1 .V>>)
1670 (<==? 2 .MODN> <PRINC <1 .V>> <PRINC <1 .V>>)
1671 (<==? 3 .MODN> <PRINC <1 .V>> <PRINC <1 .V>> <PRINC <1 .V>>)
1672 (<==? 4 .MODN> <PRINC <1 .V>> <PRINC <2 .V>>)
1673 (<==? 5 .MODN> <PRINC <2 .V>>)
1674 (<==? 6 .MODN> <PRINC <2 .V>> <PRINC <1 .V>>)
1675 (<==? 7 .MODN> <PRINC <2 .V>> <PRINC <1 .V>> <PRINC <1 .V>>)
1681 (<==? 9 .MODN> <PRINC <1 .V>> <PRINC <3 .V>>)>>$
1684 <PRINTTYPE TIME FIX> ;"fairly harmless but necessary here"$
1686 <PRINTTYPE FIX ,ROMAN-PRINT> ;"hee hee!"$
1692 <PRINTTYPE FIX ,PRINT>$
1695 <NEWTYPE GRITCH LIST> ;"a new TYPE of PRIMTYPE LIST"$
1699 <EVALTYPE GRITCH LIST> ;"evaluated like a LIST"$
1703 #GRITCH (A <+ 1 2 3> !<SET A "ABC">) ;"Type in one."$
1704 #GRTICH (A 6 !\A !\B !\C)
1706 <NEWTYPE HARRY VECTOR> ;"a new TYPE of PRIMTYPE VECTOR"$
1708 <EVALTYPE HARRY #FUNCTION ((X) <1 .X>)>
1709 ;"When a HARRY is EVALed, return its first element."$
1714 <NEWTYPE WINNER LIST> ;"a TYPE with funny application"$
1718 <APPLYTYPE WINNER <FUNCTION (W "TUPLE" T) (!.W !.T)>>$
1721 #FUNCTION ((W "TUPLE" T (!.W !.T))
1722 <#WINNER (A B C) <+ 1 2> q>$
1725 The following sequence makes Muddle look just like Lisp. (This example
1726 is understandable only if you know Lisp (Moon, 1974); it is included
1727 only because it is so beautiful.)
1729 <EVALTYPE LIST FORM>$
1731 <EVALTYPE ATOM ,LVAL>$
1743 To complete the job, of course, we would have to do some `SETG`'s:
1744 `car` is `1`, `cdr` is `,REST`, and `lambda` is `,FUNCTION`. If you
1745 really do this example, you should "undo" it before continuing:
1747 <EVALTYPE 'ATOM ,EVAL>$
1749 <EVALTYPE LIST ,EVAL>$
1752 Chapter 7. Structured Objects
1753 =============================
1755 This chapter discusses structured objects in general and the five
1756 basic structured `PRIMTYPE`s. \[We defer detailed discussion of the
1757 structured `PRIMTYPE`s `TUPLE` (section 9.2) and `STORAGE` (section
1763 The following `SUBR`s operate uniformly on all structured objects and
1764 generate an error if not applied to a structured object. Hereafter,
1765 *structured* represents a structured object.
1767 ### 7.1.1. LENGTH \[1\]
1771 evaluates to the number of elements in *structured*.
1773 ### 7.1.2. NTH \[1\]
1775 <NTH structured fix>
1777 evaluates to the *fix*'th element of *structured*. An error occurs if
1778 *fix* is less than 1 or greater than `<LENGTH structured>`. *fix* is
1779 optional, 1 by default.
1781 ### 7.1.3. REST \[1\]
1783 <REST structured fix>
1785 evaluates to *structured* without its first *fix* elements. *fix* is
1786 optional, 1 by default.
1788 Obscure but important side effect: `REST` actually returns
1789 *structured* "`CHTYPE`d" (but not through application of `CHTYPE`) to
1790 its `PRIMTYPE`. For example, `REST` of a `FORM` is a `LIST`. `REST`
1791 with an explicit second argument of `0` has no effect except for this
1794 ### 7.1.4. PUT \[1\]
1796 <PUT structured fix anything-legal>
1798 first makes *anything-legal* the *fix*'th element of *structured*,
1799 then evaluates to *structured*. *anything-legal* is anything which can
1800 legally be an element of *structured*; often, this is synonymous with
1801 "any Muddle object", but see below. An error occurs if *fix* is less
1802 than 1 or greater than `<LENGTH structured>`. (`PUT` is actually more
1803 general than this -- chapter 13.)
1807 <GET structured fix>
1809 evaluates the same as `<NTH structured fix>`. It is more general than
1810 `NTH`, however (chapter 13), and is included here only for symmetry
1813 ### 7.1.6. APPLYing a FIX \[1\]
1815 `EVAL` understands the application of an object of `TYPE` `FIX` as a
1816 "shorthand" call to `NTH` or `PUT`, depending on whether it is given
1817 one or two arguments, respectively \[unless the `APPLYTYPE` of `FIX`
1818 is changed\]. That is, `EVAL` considers the following two to be
1822 <NTH structured fix>
1826 <fix structured object>
1827 <PUT structured fix object>
1829 \[However, the compiler (Lebling, 1979) cannot generate efficient code
1830 from the longer forms unless it is sure that *fix* is a `FIX` (section
1831 9.10). The two constructs are not identical even to `EVAL`, if the
1832 order of evaluation is significant: for example, these two:
1834 <NTH .X <LENGTH <SET X .Y>>> <<LENGTH <SET X .Y>> .X>
1836 are **not** identical.\]
1840 `SUBSTRUC` ("substructure") facilitates the construction of structures
1841 that are composed of sub-parts of existing structures. A special case
1842 of this would be a "substring" function.
1844 <SUBSTRUC from:structured rest:fix amount:fix to:structured>
1846 copies the first *amount* elements of `<REST from rest>` into another
1847 object and returns the latter. All arguments are optional except
1848 *from*, which must be of `PRIMTYPE` `LIST`, `VECTOR`, `TUPLE` (treated
1849 like a `VECTOR`), `STRING`, `BYTES`, or `UVECTOR`. *rest* is `0` by
1850 default, and *amount* is all the elements by default. *to*, if given,
1851 receives the copied elements, starting at its beginning; it must be an
1852 object whose `TYPE` is the `PRIMTYPE` of *from* (a `VECTOR` if *from*
1853 is a `TUPLE`). If *to* is not given, a new object is returned, of
1854 `TYPE` `<PRIMTYPE from>` (a `VECTOR` if *from* is a `TUPLE`), which
1855 **never** shares with *from*. The copying is done in one fell swoop,
1856 not an element at a time. Note: due to an implementation restriction,
1857 if *from* is of `PRIMTYPE` `LIST`, it must not share any elements with
1860 7.2. Representation of Basic Structures
1861 ---------------------------------------
1863 ### 7.2.1. LIST \[1\]
1865 ( element-1 element-2 ... element-N )
1867 represents a `LIST` of *N* elements.
1869 ### 7.2.2. VECTOR \[1\]
1871 [ element-1 element-2 ... element-N ]
1873 represents a `VECTOR` of *N* elements. \[A `TUPLE` is just like a
1874 `VECTOR`, but it lives on the control stack.\]
1876 ### 7.2.3. UVECTOR \[1\]
1878 ![ element-1 element-2 ... element-N !]
1880 represents a `UVECTOR` (uniform vector) of *N* elements. The second
1881 `!` (exclamation-point) is optional for input. \[A `STORAGE` is an
1882 archaic kind of `UVECTOR` that is not garbage-collected.\]
1884 ### 7.2.4. STRING \[1\]
1888 represents a `STRING` of ASCII text. A `STRING` containing the
1889 character `"` (double-quote) is represented by placing a `\`
1890 (backslash) before the double-quote inside the `STRING`. A `\` in a
1891 `STRING` is represented by two consecutive backslashes.
1895 #n {element-1 element-2 ... element-N}
1897 represents a string of *N* uniformly-sized bytes of size *n* bits.
1901 { element-1 element-2 ... element-N }
1903 represents a `TEMPLATE` of *N* elements when output, not input -- when
1904 input, a `#` and a `TYPE` must precede it.
1906 7.3. Evaluation of Basic Structures
1907 -----------------------------------
1909 This section and the next two describe how `EVAL` treats the basic
1910 structured `TYPE`s \[in the absence of any modifying `EVALTYPE` calls
1913 `EVAL` of a `STRING` \[or `BYTES` or `TEMPLATE`\] is just the original
1916 `EVAL` acts exactly the same with `LIST`s, `VECTOR`s, and `UVECTOR`s:
1917 it generates a **new** object with elements equal to `EVAL` of the
1918 elements it is given. This is one of the simplest means of
1919 constructing a structure. However, see section 7.7.
1926 <SET FOO [5 <- 3> <TYPE "ABC">]>$
1932 <SET BAR ![("meow") (.FOO)]>$
1933 ![("meow") ([5 -3 STRING])!]
1936 <REST <1 <2 .BAR>>>$
1938 [<SUBSTRUC <1 <2 .BAR>> 0 2>]$
1940 <PUT .FOO 1 SNEAKY> ;"Watch out for .BAR !"$
1943 ![("meow") ([SNEAKY -3 STRING])!]
1944 <SET FOO <REST <1 <1 .BAR>> 2>>$
1947 ![("meow") ([SNEAKY -3 STRING])!]
1949 7.5. Generation of Basic Structures
1950 -----------------------------------
1952 Since `LIST`s, `VECTOR`s, `UVECTOR`s, and `STRING`s \[and `BYTES`es\]
1953 are all generated in a fairly uniform manner, methods of generating
1954 them will be covered together here. \[`TEMPLATE`s cannot be generated
1955 by the interpreter itself: see Lebling (1979).\]
1957 ### 7.5.1. Direct Representation \[1\]
1959 Since `EVAL` of a `LIST`, `VECTOR`, or `UVECTOR` is a new `LIST`,
1960 `VECTOR`, or `UVECTOR` with elements which are `EVAL` of the original
1961 elements, simply evaluating a representation of the object you want
1962 will generate it. (Care must be taken when representing a `UVECTOR`
1963 that all elements have the same `TYPE`.) This method of generation was
1964 exclusively used in the examples of section 7.4. Note that new
1965 `STRING`s \[and `BYTES`es\] will not be generated in this manner,
1966 since the contents of a `STRING` are not interpreted or copied by
1967 `EVAL`. The same is true of any other `TYPE` whose `TYPEPRIM` happens
1968 to be `LIST`, `VECTOR`, or `UVECTOR` \[again, assuming it neither has
1969 been `EVALTYPE`d nor has a built-in `EVALTYPE`, as do `FORM` and
1972 ### 7.5.2. QUOTE \[1\]
1974 `QUOTE` is an `FSUBR` of one argument which returns its argument
1975 unevaluated. `READ` and `PRINT` understand the character `'`
1976 (single-quote) as an abbreviation for a call to `QUOTE`, the way
1977 period and comma work for `LVAL` and `GVAL`. Examples:
1984 Any `LIST`, `VECTOR`, or `UVECTOR` in a program that is constant and
1985 need not have its elements evaluated should be represented directly
1986 and **inside a call to `QUOTE`.** This technique prevents the
1987 structure from being copied each time that portion of the program is
1988 executed. Examples hereafter will adhere to this dictum. (Note: one
1989 should **never** modify a `QUOTE`d object. The compiler will one day
1990 put it in read-only (pure) storage.)
1992 ### 7.5.3. LIST, VECTOR, UVECTOR, and STRING (the SUBRs) \[1\]
1994 Each of the `SUBR`s `LIST`, `VECTOR`, `UVECTOR`, and `STRING` takes
1995 any number of arguments and returns an object of the appropriate
1996 `TYPE` whose elements are `EVAL` of its arguments. There are
1997 limitations on what the arguments to `UVECTOR` and `STRING` may `EVAL`
1998 to, due to the nature of the objects generated. See sections 7.6.5 and
2001 `LIST`, `VECTOR`, and `UVECTOR` are generally used only in special
2002 cases, since Direct Representation usually produces exactly the same
2003 effect (in the absence of errors), and the intention is more apparent.
2004 \[Note: if `.L` is a `LIST`, `<LIST !.L>` makes a copy of `.L` whereas
2005 `(!.L)` doesn't; see section 7.7.\] `STRING`, on the other hand,
2006 produces effect very different from literal `STRING`s.
2010 <LIST 1 <+ 2 3> ABC>$
2014 <STRING "A" <2 "QWERT"> <REST "ABC"> "hello">$
2019 ### 7.5.4. ILIST, IVECTOR, IUVECTOR, and ISTRING \[1\]
2021 Each of the `SUBR`s `ILIST`, `IVECTOR`, `IUVECTOR`, and `ISTRING`
2022 ("implicit" or "iterated" whatever) creates and returns an object of
2023 the obvious `TYPE`. The format of an application of any of them is
2025 < Ithing number-of-elements:fix expression:any >
2027 where *Ithing* is one of `ILIST`, `IVECTOR`, `IUVECTOR`, or `ISTRING`.
2028 An object of `LENGTH` *number-of-elements* is generated, whose
2029 elements are `EVAL` of *expression*.
2031 *expression* is optional. When it is not specified, `ILIST`,
2032 `IVECTOR`, and `IUVECTOR` return objects filled with objects of `TYPE`
2033 `LOSE` (`PRIMTYPE` `WORD`) as place holders, a `TYPE` which can be
2034 passed around and have its `TYPE` checked, but otherwise is an illegal
2035 argument. If *expression* is not specified in `ISTRING`, you get a
2036 `STRING` made up of `^@` characters.
2038 When *expression* is supplied as an argument, it is re-`EVAL`uated
2039 each time a new element is generated. (Actually, `EVAL` of
2040 *expression* is re-`EVAL`uated, since all of these are `SUBR`s.) See
2041 the last example for how this argument may be used.
2043 \[By the way, in a construct like `<IUVECTOR 9 '.X>`, even if the
2044 `LVAL` of `X` evaluates to itself, so that the `'` could be omitted
2045 without changing the result, the compiler is much happier with the `'`
2048 `IUVECTOR` and `ISTRING` again have limitations on what *expression*
2049 may `EVAL` to; again, see sections 7.6.5 and 7.6.6.
2056 [#LOSE *000000000000* #LOSE *000000000000*]
2060 <IUVECTOR 9 '<SET A <+ .A 1>>>$
2061 ![1 2 3 4 5 6 7 8 9!]
2063 ### 7.5.5. FORM and IFORM
2065 Sometimes the need arises to create a `FORM` without `EVAL`ing it or
2066 making it the body of a `FUNCTION`. In such cases the `SUBR`s `FORM`
2067 and `IFORM` ("implicit form") can be used (or `QUOTE` can be used).
2068 They are entirely analogous to `LIST` and `ILIST`. Example:
2070 <DEFINE INC-FORM (A)
2071 <FORM SET .A <FORM + 1 <FORM LVAL .A>>>>$
2074 <SET FOO <+ 1 .FOO>>
2076 7.6. Unique Properties of Primitive TYPEs
2077 -----------------------------------------
2079 ### 7.6.1. LIST (the PRIMTYPE) \[1\]
2081 An object of `PRIMTYPE` `LIST` may be considered as a "pointer chain"
2082 (appendix 1). Any Muddle object may be an element of a `PRIMTYPE`
2083 `LIST`. It is easy to add and remove elements of a `PRIMTYPE` `LIST`,
2084 but the higher N is, the longer it takes to refer to the Nth element.
2085 The `SUBR`s which work only on objects of `PRIMTYPE` `LIST` are these:
2087 #### 7.6.1.1. PUTREST \[1\]
2089 <PUTREST head:primtype-list tail:primtype-list>
2091 changes *head* so that `<REST head>` is *tail* (actually
2092 `<CHTYPE tail LIST>`), then evaluates to *head*. Note that this
2093 actually changes *head*; it also changes anything having *head* as an
2094 element or a value. For example:
2096 <SET BOW [<SET ARF (B W)>]>$
2098 <PUTREST .ARF '(3 4)>$
2103 `PUTREST` is probably most often used to splice lists together. For
2104 example, given that `.L` is of `PRIMTYPE` `LIST`, to leave the first
2105 *m* elements of it intact and take out the next *n* elements of it,
2106 `<PUTREST <REST .L <- m 1>> <REST .L <+ m n>>>`. Specifically,
2108 <SET NUMS (1 2 3 4 5 6 7 8 9)>$
2110 <PUTREST <REST .NUMS 3> <REST .NUMS 7>>$
2119 ("construct") adds *new* to the front of *list*, without copying
2120 *list*, and returns the resulting `LIST`. References to *list* are not
2123 \[Evaluating `<CONS .E .LIST>` is equivalent to evaluating
2124 `(.E !.LIST)` (section 7.7) but is less preferable to the compiler
2127 ### 7.6.2. "Array" PRIMTYPEs \[1\]
2129 `VECTORS`, `UVECTOR`s, and `STRING`s \[and `BYTES`es and `TEMPLATE`s\]
2130 may be considered as "arrays" (appendix 1). It is easy to refer to the
2131 Nth element irrespective of how large N is, and it is relatively
2132 difficult to add and delete elements. The following `SUBR`s can be
2133 used only with an object of `PRIMTYPE` `VECTOR`, `UVECTOR`, or
2134 `STRING` \[or `BYTES` or `TEMPLATE`\]. (In this section *array*
2135 represents an object of such a `PRIMTYPE`.)
2137 #### 7.6.2.1. BACK \[1\]
2141 This is the opposite of `REST`. It evaluates to *array*, with *fix*
2142 elements put back onto its front end, and changed to its `PRIMTYPE`.
2143 *fix* is optional, 1 by default. If *fix* is greater than the number
2144 of elements which have been `REST`ed off, an error occurs. Example:
2146 <SET ZOP <REST '![1 2 3 4] 3>>$
2150 <SET S <REST "Right is might." 15>>$
2155 #### 7.6.2.2. TOP \[1\]
2159 "`BACK`s up all the way" -- that is, evaluates to *array*, with all
2160 the elements which have been `REST`ed off put back onto it, and
2161 changed to its `PRIMTYPE`. Example:
2166 ### 7.6.3. "Vector" PRIMTYPEs
2170 <GROW vu end:fix beg:fix>
2172 adds/removes elements to/from either or both ends of *vu*, and returns
2173 the entire (`TOP`ped) resultant object. *vu* can be of `PRIMTYPE`
2174 `VECTOR` or `UVECTOR`. *end* specifies a lower bound for the number of
2175 elements to be added to the **end** of *vu*; *beg* specifies the same
2176 for the **beginning**. A negative *fix* specifies removal of elements.
2178 The number of elements added to each respective end is *end* or *beg*
2179 **increased** to an integral multiple of *X*, where *X* is 32 for
2180 `PRIMTYPE` `VECTOR` and 64 for `PRIMTYPE` `UVECTOR` (`1` produces 32
2181 or 64; `-1` produces 0). The elements added will be `LOSE`s if *vu* is
2182 of `PRIMTYPE` `VECTOR`, and "empty" whatever-they-are's if *vu* is of
2183 `PRIMTYPE` `UVECTOR`. An "empty" object of `PRIMTYPE` `WORD` contains
2184 zero. An "empty" object of any other `PRIMTYPE` has zero in its "value
2185 word" (appendix 1) and is not safe to play with: it should be replaced
2188 Note that, if elements are added to the beginning of *vu*,
2189 previously-existing references to *vu* will have to use `TOP` or
2190 `BACK` to get at the added elements.
2192 **Caution:** `GROW` is a **very** expensive operation; it **requires**
2193 a garbage collection (section 22.4) **every** time it is used. It
2194 should be reserved for **very special** circumstances, such as where
2195 the pattern of shared elements is terribly important.
2202 ![0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
2203 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
2204 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1!]
2210 This `SUBR` will sort `PRIMTYPE`s `VECTOR`, `UVECTOR` and `TUPLE`
2211 (section 9.2). It works most efficiently if the sort keys are of
2212 `PRIMTYPE` `WORD`, `ATOM` or `STRING`. However, the keys may be of any
2213 `TYPE`, and `SORT` will still work. `SORT` acts on fixed-length
2214 records which consist of one or more contiguous elements in the
2215 structure being sorted. One element in the record is declared to be
2216 the sort key. Also, any number of additional structures can be
2217 rearranged based on how the main structure is sorted.
2219 <SORT pred s1 l1 off s2 l2 s3 l3 sN lN>
2223 *pred* is either (see chapter 8 for information about predicates):
2225 1. `TYPE` `FALSE`, in which case the `TYPE`s of all the sort keys
2226 must be the same; they must be of `PRIMTYPE` `WORD`, `STRING` or
2227 `ATOM`; and a radix-exchange sort is used; or
2228 2. something applicable to two sort keys which returns `TYPE` `FALSE`
2229 if the first is not bigger than the second, in which case a shell
2230 sort is used. For example, `,G?` sorts numbers in ascending order,
2231 `,L?` in descending order. Note: if your *pred* is buggy, the
2232 `SORT` may never terminate.
2234 *s1* ... *sN* are the (`PRIMTYPE`) `VECTOR`s, `UVECTOR`s or `TUPLE`s
2235 being sorted, and *s1* contains the sort keys;
2237 *l1* ... *lN* are the corresponding lengths of sort records (optional,
2238 one by default); and
2240 *off* is the offset from start of record to sort key (optional, zero
2243 `SORT` returns the sorted *s1* as a value.
2245 Note: the `SUBR` `SORT` calls the `RSUBR` (chapter 19) `SORTX`; if the
2246 `RSUBR` must be loaded, you may see some output from the loader on
2251 <SORT <> <SET A <IUVECTOR 500 '<RANDOM>>>>$
2254 sorts a `UVECTOR` of random integers.
2256 <SET V [1 MONEY 2 SHOW 3 READY 4 GO]>$
2259 [4 GO 1 MONEY 3 READY 2 SHOW]
2262 [4 GO 3 READY 2 SHOW 1 MONEY]
2264 [4 GO 3 READY 2 SHOW 1 MONEY]
2266 <SORT <> ![2 1 4 3 6 5 8 7] 1 0 .V>$
2269 [GO 4 READY 3 SHOW 2 MONEY 1]
2271 The first sort was based on the `ATOM`s' `PNAME`s, considering records
2272 to be two elements. The second one sorted based on the `FIX`es. The
2273 third interchanged pairs of elements of each of its structured
2276 ### 7.6.4. VECTOR (the PRIMTYPE) \[1\]
2278 Any Muddle object may be an element of a `PRIMTYPE` `VECTOR`. A
2279 `PRIMTYPE` `VECTOR` takes two words of storage more than an equivalent
2280 `PRIMTYPE` `LIST`, but takes it all in a contiguous chunk, whereas a
2281 `PRIMTYPE` `LIST` may be physically spread out in storage (appendix
2282 1). There are no `SUBR`s or `FSUBR`s which operate only on `PRIMTYPE`
2285 ### 7.6.5. UVECTOR (the PRIMTYPE) \[1\]
2287 The difference between `PRIMTYPE`s `UVECTOR` and `VECTOR` is that
2288 every element of a `PRIMTYPE` `UVECTOR` must be of the same `TYPE`. A
2289 `PRIMTYPE` `UVECTOR` takes approximately half the storage of a
2290 `PRIMTYPE` `VECTOR` or `PRIMTYPE` `LIST` and, like a `PRIMTYPE`
2291 `VECTOR`, takes it in a contiguous chunk (appendix 1).
2293 \[Note: due to an implementation restriction (appendix 1), `PRIMTYPE`
2294 `STRING`s, `BYTES`es, `LOCD`s (chapter 12), and objects on the control
2295 stack (chapter 22) may **not** be elements of `PRIMTYPE` `UVECTOR`s.\]
2297 The "same `TYPE`" restriction causes an equivalent restriction to
2298 apply to `EVAL` of the arguments to either of the `SUBR`s `UVECTOR` or
2299 `IUVECTOR`. Note that attempting to say
2303 will cause `READ` to produce an error, since you're attempting to put
2304 a `FORM` and a `FIX` into the same `UVECTOR`. On the other hand,
2308 is legal, and will `EVAL` to the appropriate `UVECTOR` without error
2309 if `.A` `EVAL`s to a `TYPE` `FIX`.
2311 The following `SUBR`s work on `PRIMTYPE` `UVECTOR`s along.
2313 #### 7.6.5.1. UTYPE \[1\]
2315 <UTYPE primtype-uvector>
2317 ("uniform type") evaluates to the `TYPE` of every element in its
2323 #### 7.6.5.2. CHUTYPE \[1\]
2325 <CHUTYPE uv:primtype-uvector type>
2327 ("change uniform type") changes the `UTYPE` of *uv* to *type*,
2328 simultaneously changing the `TYPE` of all elements of *uv*, and
2329 returns the new, changed, *uv*. This works only when the `PRIMTYPE` of
2330 the elements of *uv* can remain the same through the whole procedure.
2331 (Exception: a *uv* of `UTYPE` `LOSE` can be `CHUTYPE`d to any *type*
2332 (legal in a `UVECTOR` of course); the resulting elements are "empty",
2335 `CHUTYPE` actually changes *uv*; hence **all** references to that
2336 object will reflect the change. This is quite different from `CHTYPE`.
2340 <SET LOST <IUVECTOR 2>>$
2341 ![#LOSE *000000000000* #LOSE *000000000000*!]
2344 <CHUTYPE .LOST FORM>$
2348 <CHUTYPE .LOST LIST>$
2351 ### 7.6.6. STRING (the PRIMTYPE) and CHARACTER \[1\]
2353 The best mental image of a `PRIMTYPE` `STRING` is a `PRIMTYPE`
2354 `UVECTOR` of `CHARACTER`s -- where `CHARACTER` is the Muddle `TYPE`
2355 for a single ASCII character. The representation of a `CHARACTER`, by
2358 !\any-ASCII-character
2360 That is, the characters `!\` (exclamation-point backslash) preceding a
2361 single ASCII character represent the corresponding object of `TYPE`
2362 `CHARACTER` (`PRIMTYPE` `WORD`). (The characters `!"`
2363 (exclamation-point double-quote) preceding a character are also
2364 acceptable for inputting a `CHARACTER`, for historical reasons.)
2366 The `SUBR` `ISTRING` will produce an error if you give it an argument
2367 that produces a non-`CHARACTER`. `STRING` can take either `CHARACTER`s
2370 There are no `SUBR`s which uniquely manipulate `PRIMTYPE` `STRING`s,
2371 but some are particularly useful in connection with them:
2373 #### 7.6.6.1. ASCII \[1\]
2375 <ASCII fix-or-character>
2377 If its argument is of `TYPE` `FIX`, `ASCII` evaluates to the
2378 `CHARACTER` with the 7-bit ASCII code of its argument. Example:
2379 `<ASCII 65>` evaluates to `!\A`.
2381 If its argument is of `TYPE` `CHARACTER`, `ASCII` evaluates to the
2382 `FIX`ed-point number which is its argument's 7-bit ASCII code.
2383 Example: `<ASCII !\Z>` evaluates to `90`.
2385 \[Actually, a `FIX` can be `CHTYPE`d to a `CHARACTER` (or vice versa)
2386 directly, but `ASCII` checks in the former case that the `FIX` is
2387 within the permissible range.\]
2389 #### 7.6.6.2. PARSE \[1\]
2391 <PARSE string radix:fix>
2393 `PARSE` applies to its argument `READ`'s algorithm for converting
2394 ASCII representations to Muddle objects and returns the **first**
2395 object created. The remainder of *string*, after the first object
2396 represented, is ignored. *radix* (optional, ten by default) is used
2397 for converting any `FIX`es that occur. \[See also sections 15.7.2 and
2398 17.1.3 for additional arguments.\]
2400 #### 7.6.6.3. LPARSE \[1\]
2402 `LPARSE` ("list parse") is exactly like `PARSE` (above), except that
2403 it parses the **entire** *string* and returns a `LIST` of **all**
2404 objects created. If given an empty `STRING` or one containing only
2405 separators, `LPARSE` returns an empty `LIST`, whereas `PARSE` gets an
2408 #### 7.6.6.4. UNPARSE \[1\]
2410 <UNPARSE any radix:fix>
2412 `UNPARSE` applies to its argument `PRINT`'s algorithm for converting
2413 Muddle objects to ASCII representations and returns a `STRING` which
2414 contains the `CHARACTER`s `PRINT` would have typed out. \[However,
2415 this `STRING` will **not** contain any of the gratuitous
2416 carriage-returns `PRINT` adds to accommodate a `CHANNEL`'s finite
2417 line-width (section 11.2.8).\] *radix* (optional, ten by default) is
2418 used for converting any `FIX`es that occur.
2422 A (`PRIMTYPE`) `BYTES` is a string of uniformly-sized bytes. The bytes
2423 can be any size between 1 and 36 bits inclusive. A `BYTES` is similar
2424 in some ways to a `UVECTOR` of `FIX`es and in some ways to a `STRING`
2425 of non-seven-bit bytes. The elements of a `BYTES` are always of `TYPE`
2428 The `SUBR`s `BYTES` and `IBYTES` are similar to `STRING` and
2429 `ISTRING`, respectively, except that each of the former takes a first
2430 argument giving the size of the bytes in the generated `BYTES`.
2431 `BYTES` takes one required argument which is a `FIX` specifying a byte
2432 size and any number of `PRIMTYPE` `WORD`s. It returns an object of
2433 `TYPE` `BYTES` with that byte size containing the objects as elements.
2434 These objects will be `ANDB`ed with the appropriate mask of 1-bits to
2435 fit in the byte size. `IBYTES` takes two required `FIX`es and one
2436 optional argument. It uses the first `FIX` to specify the byte size
2437 and the second to specify the number of elements. The third argument
2438 is repeatedly evaluated to generate `FIX`es that become elements of
2439 the `BYTES` (if it is omitted, bytes filled with zeros are generated).
2440 The analog to `UTYPE` is `BYTE-SIZE`. Examples:
2442 <BYTES 3 <+ 2 2> 9 -1>$
2446 <IBYTES 3 9 '<SET A <+ .A 1>>>$
2447 #3 {1 2 3 4 5 6 7 0 1}
2450 <BYTE-SIZE <BYTES 1>>$
2455 A `TEMPLATE` is similar to a PL/I "structure" of one level: the
2456 elements are packed together and reduced in size to save storage
2457 space, while an auxiliary internal data structure describes the
2458 packing format and the elements' real `TYPE`s (appendix 1). The
2459 interpreter is not able to create objects of `PRIMTYPE` `TEMPLATE`
2460 (Lebling, 1979); however, it can apply the standard built-in
2461 Subroutines to them, with the same effects as with other "arrays".
2466 Objects of `TYPE` `SEGMENT` (whose `TYPEPRIM` is `LIST`) look very
2467 much like `FORM`s. `SEGMENT`s, however, undergo a non-standard
2468 evaluation designed to ease the construction of structured objects
2469 from elements of other structured objects.
2471 ### 7.7.1. Representation \[1\]
2473 The representation of an object of `TYPE` `SEGMENT` is the following:
2475 !< func arg-1 arg-2 ... arg-N !>
2477 where the second `!` (exclamation-point) is optional, and *fun* and
2478 *arg-1* through *arg-N* are any legal constituents of a `FORM` (that
2479 is, anything). The pointed brackets can be implicit, as in the period
2480 and comma notation for `LVAL` and `GVAL`.
2482 All of the following are `SEGMENT`s:
2484 !<3 .FOO> !.FOO !,FOO
2486 ### 7.7.2. Evaluation \[1\]
2488 A `SEGMENT` is evaluated in exactly the same manner as a `FORM`, with
2489 the following three exceptions:
2491 1. It had better be done inside an `EVAL` of a structure; otherwise
2492 an error occurs. (See special case of `FORM`s in section 7.7.5.)
2493 2. It had better `EVAL` to a structured object; otherwise an error
2495 3. What actually gets inserted into the structure being built are the
2496 elements of the structure returned by the `FORM`-like evaluation.
2498 ### 7.7.3 Examples \[1\]
2500 <SET ZOP '![2 3 4]>$
2506 ![!.ZOP !<REST .ARF>!]$
2512 (!\S !\T !\R !\U !\N !\G !\.)
2519 ### 7.7.4. Note on Efficiency \[1\]
2521 Most of the cases in which is is possible to use `SEGMENT`s require
2522 `EVAL` to generate an entire new object. Naturally, this uses up both
2523 storage and time. However, there is one case which it is possible to
2524 handle without copying, and `EVAL` uses it. When the structure being
2525 built is a `PRIMTYPE` `LIST`, and the segment value of a `PRIMTYPE`
2526 `LIST` is the last (rightmost) element being concatenated, that last
2527 `PRIMTYPE` `LIST` is not copied. This case is similar to `CONS` and is
2528 the principle reason why `PRIMTYPE` `LIST`s have their structures more
2529 easily varied than `PRIMTYPE` `VECTOR` or `UVECTOR`.
2536 This does not copy ARF:
2543 (1 !.ARF 2) ;"not last element"$
2545 [1 2 !.ARF] ;"not PRIMTYPE LIST"$
2547 (1 2 !.ARF !<REST '(1)>) ;"still not last element"$
2550 Note the following, which occurs because copying does **not** take
2553 <SET DOG (A !.ARF)>$
2555 <PUT .ARF 1 "BOWOW">$
2559 <PUT .DOG 3 "WOOF">$
2560 (A "BOWOW" "WOOF" 4)
2564 Since `ARF` was not copied, it was literally part of `DOG`. Hence,
2565 when an element of `ARF` was changed, `DOG` was changed. Similarly,
2566 when an element of `DOG` which `ARF` shared was changed, `ARF` was
2569 ### 7.7.5. SEGMENTs in FORMs \[1\]
2571 When a `SEGMENT` appears as an element of a `FORM`, the effect is
2572 approximately the same as if the elements of the `EVAL` of the
2573 `SEGMENT` were in the `FORM`. Example:
2575 <SET A '![1 2 3 4]>$
2580 Note: the elements of the structure segment-evaluated in a `FORM` are
2581 **not** re-evaluated if the thing being applied is a `SUBR`. Thus if
2582 `.A` were `(1 2 <+ 3 4> 5)`, the above example would produce an error:
2583 you can't add up `FORM`s.
2585 You could perform the same summation of `5` and the elements of `A` by
2588 <EVAL <CHTYPE (+ !.A 5) FORM>>
2590 (Note that `EVAL` must be explicitly called as a `SUBR`; if it were
2591 not so called, you would just get the `FORM` `<+ 1 2 3 4 5>` -- not
2592 its "value".) However, the latter is more expensive both in time and
2593 in storage: when you use the `SEGMENT` directly in the `FORM`, a new
2594 `FORM` is, in fact, **not** generated as it is in the latter case.
2595 (The elements are put on "the control stack" with the other
2598 7.8. Self-referencing Structures
2599 --------------------------------
2601 It is possible for a structured object to "contain" itself, either as
2602 a subset or as an element, as an element of a structured element, etc.
2603 Such an object cannot be `PRINT`ed, because recursion begins and never
2604 terminates. Warning: if you try the examples in this section with a
2605 live Muddle, be sure you know how to use `^S` (section 1.2) to save
2606 `PRINT` from endless agony. (Certain constructs with `ATOM`s can give
2607 `PRINT` similar trouble: see chapters 12 and 15.)
2609 ### 7.8.1. Self-subset
2611 <PUTREST head:primtype-list tail:primtype-list>
2613 If *head* is a subset of *tail*, that is, if `<REST tail fix>` is the
2614 same object as `<REST head 0>` for some *fix*, then both *head* and
2615 *tail* will be "circular" (and this self-referencing) after the
2618 <SET WALTZ (1 2 3)>$
2620 <PUTREST <REST .WALTZ 2> .WALTZ>$
2621 (3 1 2 3 1 2 3 1 2 3 1 2 3 ...
2623 ### 7.8.2. Self-element
2625 <PUT s1:structured fix s2:structured>
2627 If *s1* is the same object as *s2*, then it will "contain" itself (and
2628 thus be self-referencing) after the `PUT`. Examples:
2630 <SET S <LIST 1 2 3>> ;"or VECTOR"$
2633 (1 2 (1 2 (1 2 (1 2 ...
2639 Test your reaction time or your terminal's bracket-maker. Amaze your
2645 8.1. Truth Values \[1\]
2646 -----------------------
2648 Muddle represents "false" with an object of a particular `TYPE`:
2649 `TYPE` `FALSE` (unsurprisingly). `TYPE` `FALSE` is structured: its
2650 `PRIMTYPE` is `LIST`. Thus, you can give reasons or excuses by making
2651 them elements of a `FALSE`. (Again, `EVAL`ing a `FALSE` neither copies
2652 it nor `EVAL`s its elements, so it is not necessary to `QUOTE` a
2653 `FALSE` appearing in a program.) Objects of `TYPE` `FALSE` are
2654 represented in "\# notation":
2656 #FALSE list-of-its-elements
2658 The empty `FORM` evaluates to the empty `FALSE`:
2663 Anything which is not `FALSE`, is, reasonably enough, true. In this
2664 document the "data type" *false-or-any* in metasyntactic variables
2665 means that the only significant attribute of the object in that
2666 context is whether its `TYPE` is `FALSE` or not.
2668 8.2. Predicates \[1\]
2669 ---------------------
2671 There are numerous Muddle F/SUBRs which can return a `FALSE` or a
2672 true. See appendix 2 to find them all. Most return either `#FALSE ()`
2673 or the `ATOM` with `PNAME` `T`. (The latter is for historical reasons,
2674 namely Lisp (Moon, 1974).) Some predicates which are meaningful now
2677 ### 8.2.1. Arithmetic \[1\]
2681 evaluates to `T` only if its argument is identically equal to `0` or
2686 evaluates to `T` only if its argument is identically equal to `1` or
2689 <G? n:fix-or-float m:fix-or-float>
2691 evaluates to `T` only if *n* is algebraically greater than *m*. `L=?`
2692 is the Boolean complement of `G?`; that is, it is `T` only if *n* is
2693 not algebraically greater than *m*.
2695 <L? n:fix-or-float m:fix-or-float>
2697 evaluates to `T` only if *n* is algebraically less than *m*. `G=?` is
2698 the Boolean complement of `L?`.
2700 ### 8.2.2. Equality and Membership \[1\]
2704 evaluates to `T` only if *e1* is the **same object** as *e2* (appendix
2705 1). Two objects that look the same when `PRINT`ed may not be `==?`.
2706 Two `FIX`es of the same "value" are "the same object"; so are two
2707 `FLOAT`s of **exactly** the same "value". Empty objects of `PRIMTYPE`
2708 `LIST` (and no other structured `PRIMTYPE`) are `==?` if their `TYPE`s
2709 are the same. Example:
2711 <==? <SET X "RANDOM STRING"> <TOP <REST .X 6>>>$
2713 <==? .X "RANDOM STRING">$
2716 `N==?` is the Boolean complement of `==?`.
2720 evaluates to `T` if *e1* and *e2* have the same `TYPE` and are
2721 structurally equal -- that is, they "look the same", their printed
2722 representations are the same. `=?` is much slower than `==?`. `=?`
2723 should be used only when its characteristics are necessary: they are
2724 not in any comparisons of unstructured objects. `==?` and `=?` always
2725 return the same value for `FIX`es, `FLOAT`s, `ATOM`s, etc.
2726 (Mnemonically, `==?` tests for "more equality" than `=?`; in fact, it
2727 tests for actual physical identity.)
2729 Example, illustrating non-copying of a `SEGMENT` in Direct
2730 Representation of a `LIST`:
2736 <==? .A <SET B <LIST !.A>>>$
2741 `N=?` is the Boolean complement of `=?`.
2743 <MEMBER object:any structured>
2745 runs down *structured* from first to last element, comparing each
2746 element of *structured* with *object*. If it finds an element of
2747 *structured* which is `=?` to *object*, it returns
2748 `<REST structured i>` (which is of `TYPE` `<PRIMTYPE structured>`),
2749 where the (*i*+1)th element of *structured* is `=?` to *object*. That
2750 is, the first element of what it returns is the **first** element of
2751 *structured* that is `=?` to *object*.
2753 If no element of *structured* is `=?` to *object*, `MEMBER` returns
2756 The search is more efficient if *structured* is of `PRIMTYPE` `VECTOR`
2757 (or `UVECTOR`, if possible) than if it is of `PRIMTYPE` `LIST`. As
2758 usual, if *structured* is constant, it should be `QUOTE`d.
2760 If *object* and *structured* are of `PRIMTYPE` `STRING` \[or
2761 `BYTES`\], `MEMBER` does a substring search. Example:
2763 <MEMBER "PART" "SUM OF PARTS">$
2766 `<MEMQ object:any structured>` ("member quick") is exactly the same as
2767 `MEMBER`, except that the comparison test is `==?`.
2771 ("string comparison") can be given either two `STRING`s or two `ATOM`s
2772 as arguments. In the latter case the `PNAME`s are used. It actually
2773 isn't a predicate, since it can return three possible values: `0` if
2774 *s1* is `=?` to *s2*; `1` if *s1* sorts alphabetically after *s2*; and
2775 `-1` if *s1* sorts alphabetically before *s2*. "Alphabetically" means,
2776 in this case, according to the numeric order of ASCII, with the
2777 standard alphabetizing rules.
2779 \[A predicate suitable for an ascending `SORT` (which see) is
2780 `<G? <STRCOMP .ARG1 .ARG2> 0>`.\]
2782 ### 8.2.3. Boolean Operators \[1\]
2784 <NOT e:false-or-any>
2786 evaluates to `T` only if *e* evaluates to a `FALSE`, and to
2787 `#FALSE ()` otherwise.
2791 `AND` is an `FSUBR`. It evaluates its arguments from first to last as
2792 they appear in the `FORM`. As soon as one of them evaluates to a
2793 `FALSE`, it returns that `FALSE`, ignoring any remaining arguments. If
2794 none of them evaluate to `FALSE`, it returns `EVAL` of its last
2795 argument. `<AND>` returns `T`. `AND?` is the `SUBR` equivalent to
2796 `AND`, that is, all its arguments are evaluated before any of them is
2801 `OR` is an `FSUBR`. It evaluates its arguments from first to last as
2802 they appear in the `FORM`. As soon as one of them evaluates to a
2803 non-`FALSE`, it returns that non-`FALSE` value, ignoring any remaining
2804 arguments. If this never occurs, it returns the last `FALSE` it saw.
2805 `<OR>` returns `#FALSE ()`. `OR?` is the `SUBR` equivalent to `OR`.
2807 ### 8.2.4. Object Properties \[1\]
2809 <TYPE? any type-1 ... type-N>
2811 evaluates to *type-i* only if `<==? type-i <TYPE any>>` is true. It is
2812 faster and gives more information than `OR`ing tests for each `TYPE`.
2813 If the test fails for all *type-i*'s, `TYPE?` returns `#FALSE ()`.
2817 evaluates to `T` only if *e* is of a `TYPE` that can legally be
2818 applied to arguments in a `FORM`, that is, be (`EVAL` of) the first
2819 element of a `FORM` being evaluated (appendix 3).
2823 evaluates to `#FALSE ()` only if `NTH` and `REST` (with non-zero
2824 second argument) can be performed on its argument without error. An
2825 unstructured or empty structured object will cause `MONAD?` to return
2830 evaluates to `T` only if *e* is a structured object. It is **not** the
2831 inverse of `MONAD?`, since each returns `T` if its argument is an
2836 evaluates to `T` only if its argument, which must be a structured
2837 object, has no elements.
2839 <LENGTH? structured fix>
2841 evaluates to `<LENGTH structured>` only if that is less than or equal
2842 to *fix*; otherwise, it evaluates to `#FALSE ()`. Mnemonically, you
2843 can think of the first two letters of `LENGTH?` as signifying the
2844 "less than or equal to" sense of the test.
2846 This `SUBR` was invented to use on lists, because Muddle can determine
2847 their lengths only by stepping along the list, counting the elements.
2848 If a program needs to know only how the length compares with a given
2849 number, `LENGTH?` will tell without necessarily stepping all the way
2850 to the end of the list, in contrast to `LENGTH`.
2852 \[If *structured* is a circular `PRIMTYPE` `LIST`, `LENGTH?` will
2853 return a value, whereas `LENGTH` will execute forever. To see if you
2854 can do `<REST structured <+ 1 fix>>` without error, do the test
2855 `<NOT <LENGTH? structured fix>>`.\]
2860 The Muddle Subroutine which is most used for varying evaluation
2861 depending on a truth value is the `FSUBR` `COND` ("conditional"). A
2862 call to `COND` has this format:
2864 <COND clause-1:list ... clause-N:list>
2866 where *N* is at least one.
2868 `COND` always returns the result of the **last** evaluation it
2869 performs. The following rules determine the order of evaluations
2872 1. Evaluate the first element of each clause (from first to last)
2873 until either a non-`FALSE` object results or the clauses are
2875 2. If a non-`FALSE` object is found in (1), immediately evaluate the
2876 remaining elements (if any) of that clause and ignore any
2879 In other words, `COND` goes walking down its clauses, `EVAL`ing the
2880 first element of each clause, looking for a non-`FALSE` result. As
2881 soon as it finds a non-`FALSE`, it forgets about all the other clauses
2882 and evaluates, in order, the other elements of the current clause and
2883 returns the last thing it evaluates. If it can't find a non-`FALSE`,
2884 it returns the last `FALSE` it saw.
2890 <COND (<EMPTY? .F> EMP) (<1? <LENGTH .F>> ONE)>$
2894 <COND (<EMPTY? .F> EMP) (<1? <LENGTH .F>> ONE)>$
2898 <COND (<EMPTY? .F> EMP) (<1? <LENGTH .F>> ONE)>$
2900 <COND (<LENGTH? .F 2> SMALL) (BIG)>$
2903 <DEFINE FACT (N) ;"the standard recursive factorial"
2905 (ELSE <* .N <FACT <- .N 1>>>)>>$
2910 8.4. Shortcuts with Conditionals
2911 --------------------------------
2913 ### 8.4.1. AND and OR as Short CONDs
2915 Since `AND` and `OR` are `FSUBR`s, they can be used as miniature
2916 `COND`s. A construct of the form
2918 <AND pre-conditions action(s)>
2922 <OR pre-exclusions action(s)>
2924 will allow *action(s)* to be evaluated only if all the
2925 *pre-conditions* are true or only if all the *pre-exclusions* are
2926 false, respectively. By nesting and using both `AND` and `OR`, fairly
2927 powerful constructs can be made. Of course, if *action(s)* are more
2928 than one thing, you must be careful that none but the last returns
2929 false or true, respectively. Watch out especially for `TERPRI`
2930 (chapter 11). Examples:
2932 <AND <ASSIGNED? FLAG> .FLAG <FCN .ARG>>
2934 applies `FCN` only if someone else has `SET` `FLAG` to true.
2935 (`ASSIGNED?` is true if its argument `ATOM` has an `LVAL`.) No error
2936 can occur in the testing of `FLAG` because of the order of evaluation.
2938 <AND <SET C <OPEN "READ" "A FILE">> <LOAD .C> <CLOSE .C>>
2940 effectively `FLOAD`s the file (chapter 11) without the possibility of
2941 getting an error if the file cannot be opened.
2943 ### 8.4.2. Embedded Unconditionals
2945 One of the disadvantages of `COND` is that there is no straightforward
2946 way to do things unconditionally in between tests. One way around this
2947 problem is to insert a dummy clause that never succeeds, because its
2948 only `LIST` element is an `AND` that returns a `FALSE` for the test.
2951 <COND (<0? .N> <F0 .N>)
2953 (<AND <SET N <* 2 <FIX </ .N 2>>>>
2954 ;"Round .N down to even number."
2956 (<LENGTH? .VEC .N> '[])
2957 (T <REST .VEC <+ 1 .N>>)>
2959 A variation is to make the last `AND` argument into the test for the
2960 `COND` clause. (That is, the third and fourth clauses in the above
2961 example can be combined.) Of course, you must be careful that no other
2962 `AND` argument evaluates to a `FALSE`; most Subroutines do not return
2963 a `FALSE` without a very good reason for it. (A notable exception is
2964 `TERPRI` (which see).) Even safer is to use `PROG` (section 10.1)
2967 Another variation is to increase the nesting with a new `COND` after
2968 the unconditional part. At least this method does not make the code
2969 appear to a human reader as though it does something other than what
2970 it really does. The above example could be done this way:
2972 <COND (<0? .N> <F0 .N>)
2975 <SET N <* 2 <FIX </ .N 2>>>>
2976 <COND (<LENGTH? .VEC .N> '[])
2977 (T <REST .VEC <+ 1 .N>>)>)>
2979 Chapter 9. Functions
2980 ====================
2982 This chapter could be named "fun and games with argument `LIST`s". Its
2983 purpose is to explain the more complicated things which can be done
2984 with `FUNCTION`s, and this involves, basically, explaining all the
2985 various tokens which can appear in the argument `LIST` of a
2986 `FUNCTION`. Topics are covered in what is approximately an order of
2987 increasing complexity. This order has little to do with the order in
2988 which tokens can actually appear in an argument `LIST`, so what an
2989 argument `LIST` "looks like" overall gets rather lost in the shuffle.
2990 To alleviate this problem, section 9.9 is a summary of everything that
2991 can go into an argument `LIST`, in the correct order. If you find
2992 yourself getting lost, please refer to that summary.
2994 9.1. "OPTIONAL" \[1\]
2995 ---------------------
2997 Muddle provides very convenient means for allowing optional arguments.
2998 The `STRING` `"OPTIONAL"` (or `"OPT"` -- they're totally equivalent)
2999 in the argument `LIST` allows the specification of optional arguments
3000 with values to be assigned by default. The syntax of the `"OPTIONAL"`
3001 part of the argument `LIST` is as follows:
3003 "OPTIONAL" al-1 al-2 ... al-N
3005 First, there is the `STRING` `"OPTIONAL"`. Then there is any number of
3006 either `ATOM`s or two-element `LIST`s, intermixed, one per optional
3007 argument. The first element of each two-element `LIST` must be an
3008 `ATOM`; this is the dummy variable. The second element is an arbitrary
3009 Muddle expression. If there are required arguments, they must come
3010 before the `"OPTIONAL"`.
3012 When `EVAL` is binding the variables of a `FUNCTION` and sees
3013 `"OPTIONAL"`, the following happens:
3015 - If an explicit argument was given in the position of an optional
3016 one, the explicit argument is bound to the corresponding dummy
3018 - If there is no explicit argument and the `ATOM` stands alone, that
3019 is, it is not the first element of a two-element `LIST`, that
3020 `ATOM` becomes "bound", but no local value is assigned to it \[see
3021 below\]. A local value can be assigned to it by using `SET`.
3022 - If there is no explicit argument and the `ATOM` is the first
3023 element of a two-element `LIST`, the Muddle expression in the
3024 `LIST` with the `ATOM` is evaluated and bound to the `ATOM`.
3026 \[Until an `ATOM` is assigned, any attempt to reference its `LVAL`
3027 will produce an error. The predicate `SUBR`s `BOUND?` and `ASSIGNED?`
3028 can be used to check for such situations. `BOUND?` returns `T` if its
3029 argument is currently bound via an argument `LIST` or has ever been
3030 `SET` while not bound via an argument `LIST`. The latter kind of
3031 binding is called "top-level binding", because it is done outside all
3032 active argument-`LIST` binding. `ASSIGNED?` will return `#FALSE ()` if
3033 its argument is **either** unassigned **or** unbound. By the way,
3034 there are two predicates for global values similar to `BOUND?` and
3035 `ASSIGNED?`, namely `GBOUND?` and `GASSIGNED?`. Each returns `T` only
3036 if its argument, which (as in `BOUND?` and `ASSIGNED?`) must be an
3037 `ATOM`, has a global value "slot" (chapter 22) or a global value,
3042 <DEFINE INC1 (A "OPTIONAL" (N 1)) <SET .A <+ ..A .N>>>$
3051 Here we defined another (not quite working) increment `FUNCTION`. It
3052 now takes an optional argument specifying how much to increment the
3053 `ATOM` it is given. If not given, the increment is `1`. Now, `1` is a
3054 pretty simple Muddle expression: there is no reason why the optional
3055 argument cannot be complicated -- for example, a call to a `FUNCTION`
3056 which reads a file on an I/O device.
3061 ### 9.2.1. "TUPLE" and TUPLE (the TYPE) \[1\]
3063 There are also times when you want to be able to have an arbitrary
3064 number of arguments. You can always do this by defining the `FUNCTION`
3065 as having a structure as its argument, with the arbitrary number of
3066 arguments as elements of the structure. This can, however, lead to
3067 inelegant-looking `FORM`s and extra garbage to be collected. The
3068 `STRING` `"TUPLE"` appearing in the argument `LIST` allows you to
3069 avoid that. It must follow explicit and optional dummy arguments (if
3070 there are any of either) and must be followed by an `ATOM`.
3072 The effect of `"TUPLE"` appearing in an argument `LIST` is the
3073 following: any arguments left in the `FORM`, after satisfying explicit
3074 and optional arguments, are `EVAL`ed and made sequential elements of
3075 an object of `TYPE` and `PRIMTYPE` `TUPLE`. The `TUPLE` is the bound
3076 to the `ATOM` following `"TUPLE"` in the argument `LIST`. If there
3077 were no arguments left by the time the `"TUPLE"` was reached, an empty
3078 `TUPLE` is bound to the `ATOM`.
3080 An object of `TYPE` `TUPLE` is exactly the same as a `VECTOR` except
3081 that a `TUPLE` is not held in garbage-collected storage. It is instead
3082 held with `ATOM` bindings in a control stack. This does not affect
3083 manipulation of the `TUPLE` within the function generating it or any
3084 function called within that one: it can be treated just like a
3085 `VECTOR`. Note, however, that a `TUPLE` ceases to exist when the
3086 function which generated it returns. Returning a `TUPLE` as a value is
3087 a good way to generate an error. (A copy of a `TUPLE` can easily be
3088 generated by segment-evaluating the `TUPLE` into something; that copy
3089 can be returned.) The predicate `LEGAL?` returns `#FALSE ()` if it is
3090 given a `TUPLE` generated by an `APPLICABLE` object which has already
3091 returned, and `T` if it is given a `TUPLE` which is still "good".
3095 <DEFINE NTHARG (N "TUPLE" T)
3096 ;"Get all but first argument into T."
3097 <COND (<==? 1 .N> 1)
3098 ;"If N is 1, return 1st arg, i.e., .N,
3099 i.e., 1. Note that <1? .N> would be
3100 true even if .N were 1.0."
3101 (<L? <LENGTH .T> <SET N <- .N 1>>>
3103 ;"Check to see if there is an Nth arg,
3104 and make N a good index into T while
3106 If there isn't an Nth arg, complain."
3107 (ELSE <NTH .T .N>)>>
3109 `NTHARG`, above, takes any number of arguments. Its first argument
3110 must be of `TYPE` `FIX`. It returns `EVAL` of its Nth argument, if it
3111 has an Nth argument. If it doesn't, it returns `#FALSE ("DUMMY")`.
3112 (The `ELSE` is not absolutely necessary in the last clause. If the Nth
3113 argument is a `FALSE`, the `COND` will return that `FALSE`.) Exercise
3114 for the reader: `NTHARG` will generate an error if its first argument
3115 is not `FIX`. Where and why? (How about `<NTHARG 1.5 2 3>`?) Fix it.
3117 ### 9.2.2. TUPLE (the SUBR) and ITUPLE
3119 These `SUBR`s are the same as `VECTOR` and `IVECTOR`, except that they
3120 build `TUPLE`s (that is, vectors on the control stack). They can be
3121 used only at top level in an `"OPTIONAL"` list or `"AUX"` list (see
3122 below). The clear advantage of `TUPLE` and `ITUPLE` ("implicit tuple")
3123 is in storage-management efficiency. They produce no garbage, since
3124 they are flushed automatically upon function return.
3128 <DEFINE F (A B "AUX" (C <ITUPLE 10 3>)) ...>
3130 creates a 10-element `TUPLE` and `SET`s `C` to it.
3132 <DEFINE H ("OPTIONAL" (A <ITUPLE 10 '<I>>)
3133 "AUX" (B <TUPLE !.A 1 2 3>))
3136 These are valid uses of `TUPLE` and `ITUPLE`. However, the following
3137 is **not** a valid use of `TUPLE`, because it is not called at top
3138 level of the `"AUX"`:
3140 <DEFINE NO (A B "AUX" (C <REST <TUPLE !.A>>)) ...>
3142 However, the desired effect could be achieved by
3144 <DEFINE OK (A B "AUX" (D <TUPLE !.A>) (C <REST .D>)) ...>
3149 `"AUX"` (or `"EXTRA"` -- they're totally equivalent) are `STRING`s
3150 which, placed in an argument `LIST`, serve to dynamically allocate
3151 temporary variables for the use of a Function.
3153 `"AUX"` must appear in the argument `LIST` after any information about
3154 explicit arguments. It is followed by `ATOM`s or two-element `LIST`s
3155 as if it were `"OPTIONAL"`. `ATOM`s in the two-element `LIST`s are
3156 bound to `EVAL` of the second element in the `LIST`. Atoms not in such
3157 `LIST`s are initially **unassigned**: they are explicitly given "no"
3160 All binding specified in an argument `LIST` is done sequentially from
3161 first to last, so initialization expressions for `"AUX"` (or
3162 `"OPTIONAL"`) can refer to objects which have just been bound. For
3163 example, this works:
3165 <DEFINE AUXEX ("TUPLE" T
3166 "AUX" (A <LENGTH .T>) (B <* 2 .A>))
3172 9.4. QUOTEd arguments
3173 ---------------------
3175 If an `ATOM` in an argument `LIST` which is to be bound to a required
3176 or optional argument is surrounded by a call to `QUOTE`, that `ATOM`
3177 is bound to the **unevaluated** argument. Example:
3179 <DEFINE Q2 (A 'B) (.A .B)>$
3181 <Q2 <+ 1 2> <+ 1 2>>$
3184 It is not often appropriate for a function to take its arguments
3185 unevaluated, because such a practice makes it less modular and harder
3186 to maintain: it and the programs that call it tend to need to know
3187 more about each other, and a change in its argument structure would
3188 tend to require more changes in the programs that call it. And, since
3189 few functions, in practice, do take unevaluated arguments, users tend
3190 to assume that no functions do (except `FSUBR`s of course), and
3191 confusion inevitably results.
3196 The indicator `"ARGS"` can appear in an argument `LIST` with precisely
3197 the same syntax as `"TUPLE"`. However, `"ARGS"` causes the `ATOM`
3198 following it to be bound to a `LIST` of the remaining **unevaluated**
3201 `"ARGS"` does not cause any copying to take place. It simply gives you
3203 <REST application:form fix>
3205 with an appropriate *fix*. The `TYPE` change to `LIST` is a result of
3206 the `REST`. Since the `LIST` shares all its elements with the original
3207 `FORM`, `PUT`s into the `LIST` will change the calling program,
3208 however dangerous that may be.
3212 <DEFINE QIT (N "ARGS" L) <.N .L>>$
3214 <QIT 2 <+ 3 4 <LENGTH ,QALL> FOO>$
3217 <DEFINE FUNCT1 ("ARGS" ARGL-AND-BODY)
3218 <CHTYPE .ARGL-AND-BODY FUNCTION>>$
3220 <FUNCT1 (A B) <+ .A .B>>$
3221 #FUNCTION ((A B) <+ .A .B>)
3223 The last example is a perfectly valid equivalent of the `FSUBR`
3229 The indicator `"CALL"` is an ultimate `"ARGS"`. If it appears in an
3230 argument `LIST`, it must be followed by an `ATOM` and must be the only
3231 thing used to gather arguments. `"CALL"` causes the `ATOM` which
3232 follows it to become bound to the actual `FORM` that is being
3233 evaluated -- that is, you get the "function call" itself. Since
3234 `"CALL"` binds to the `FORM` itself, and not a copy, `PUT`s into that
3235 `FORM` will change the calling code.
3237 `"CALL"` exists as a Catch-22 for argument manipulation. If you can't
3238 do it with `"CALL"`, it can't be done.
3240 9.7. EVAL and "BIND"
3241 --------------------
3243 Obtaining unevaluated arguments, for example, for `QUOTE` and
3244 `"ARGS"`, very often implies that you wish to evaluate them at some
3245 point. You can do this by explicitly calling `EVAL`, which is a
3253 `EVAL` can take a second argument, of `TYPE` `ENVIRONMENT` (or others,
3254 see section 20.8). An `ENVIRONMENT` consists basically of a state of
3255 `ATOM` bindings; it is the "world" mentioned in chapter 5. Now, since
3256 binding changes the `ENVIRONMENT`, if you wish to use `EVAL` within a
3257 `FUNCTION`, you probably want to get hold of the environment which
3258 existed **before** that `FUNCTION`'s binding took place. The indicator
3259 `"BIND"`, which must, if it is used, be the first thing in an argument
3260 `LIST`, provides this information. It binds the `ATOM` immediately
3261 following it to the `ENVIRONMENT` existing "at call time" -- that is,
3262 just before any binding is done for its `FUNCTION`. Example:
3266 <DEFINE WRONG ('B "AUX" (A 1)) <EVAL .B>>$
3270 <DEFINE RIGHT ("BIND" E 'B "AUX" (A 1)) <EVAL .B .E>>$
3275 ### 9.7.1. Local Values versus ENVIRONMENTs
3277 `SET`, `LVAL`, `VALUE`, `BOUND?`, `ASSIGNED?`, and `UNASSIGN` all take
3278 a final optional argument which has not previously been mentioned: an
3279 `ENVIRONMENT` (or other `TYPE`s, see section 20.8). If this argument
3280 is given, the `SET` or `LVAL` is done in the `ENVIRONMENT` specified.
3281 `LVAL` cannot be abbreviated by `.` (period) if it is given an
3282 explicit second argument.
3284 This feature is just what is needed to cure the `INC` bug mentioned in
3285 chapter 5. A "correct" `INC` can be defined as follows:
3287 <DEFINE INC ("BIND" OUTER ATM)
3288 <SET .ATM <+ 1 <LVAL .ATM .OUTER>> .OUTER>>
3290 9.8. ACTIVATION, "NAME", "ACT", "AGAIN", and RETURN \[1\]
3291 ---------------------------------------------------------
3293 `EVAL`uation of a `FUNCTION`, after the argument `LIST` has been taken
3294 care of, normally consists of `EVAL`uating each of the objects in the
3295 body in the order given, and returning the value of the last thing
3296 `EVAL`ed. If you want to vary this sequence, you need to know, at
3297 least, where the `FUNCTION` begins. Actually, `EVAL` normally hasn't
3298 the foggiest idea of where its current `FUNCTION` began. "Where'd I
3299 start" information is bundled up with a `TYPE` called `ACTIVATION`. In
3300 "normal" `FUNCTION` `EVAL`uation, `ACTIVATION`s are not generated: one
3301 can be generated, and bound to an `ATOM`, in either of the two
3304 1. Put an `ATOM` immediately before the argument `LIST`. The
3305 `ACTIVATION` of the Function will be bound to that `ATOM`.
3306 2. As the last thing in the argument `LIST`, insert either of the
3307 `STRING`s `"NAME"` or `"ACT"` and follow it with an `ATOM`. The
3308 `ATOM` will be bound to the `ACTIVATION` of the Function.
3310 In this document "Function" (capitalized) will designate anything that
3311 can generate an `ACTIVATION`; besides `TYPE` `FUNCTION`, this class
3312 includes the `FSUBR`s `PROG`, `BIND`, and `REPEAT`, yet to be
3315 Each `ACTIVATION` refers explicitly to a particular evaluation of a
3316 Function. For example, if a recursive `FUNCTION` generates an
3317 `ACTIVATION`, a new `ACTIVATION` referring explicitly to each
3318 recursion step is generated on every recursion.
3320 Like `TUPLE`s, `ACTIVATION`s are held in a control stack. Unlike
3321 `TUPLE`s, there is **no way** to get a copy of an `ACTIVATION` which
3322 can usefully be returned as a value. (This is a consequence of the
3323 fact that `ACTIVATION`s refer to evaluations; when the evaluation is
3324 finished, the `ACTIVATION` no longer exists.) `ACTIVATION`s can be
3325 tested, like `TUPLE`s, by `LEGAL?` for legality. They are used by the
3326 `SUBR`s `AGAIN` and `RETURN`.
3328 `AGAIN` can take one argument: an `ACTIVATION`. It means "start doing
3329 this again", where "this" is specified by the `ACTIVATION`.
3330 Specifically, `AGAIN` causes `EVAL` to return to where it started
3331 working on the **body** of the Function in the evaluation specified by
3332 the `ACTIVATION`. The evaluation is not redone completely: in
3333 particular, no re-binding (of arguments, `"AUX"` variables, etc.) is
3336 `RETURN` can take two arguments: an arbitrary expression and an
3337 `ACTIVATION`, in that order. It causes the Function evaluation whose
3338 `ACTIVATION` it is given to terminate and return `EVAL` of `RETURN`'s
3339 first argument. That is, `RETURN` means "quit doing this and return
3340 that", where "this" is the `ACTIVATION` -- its second argument -- and
3341 "that" is the expression -- its first argument. Example:
3343 <DEFINE MY+ ("TUPLE" T "AUX" (M 0) "NAME" NM)
3344 <COND (<EMPTY? .T> <RETURN .M .NM>)>
3345 <SET M <+ .M <1 .T>>>
3349 <MY+ 1 3 <LENGTH "FOO">>$
3354 Note: suppose an `ACTIVATION` of one Function (call it `F1`) is passed
3355 to another Function (call it `F2`) -- for example, via an application
3356 of `F2` within `F1` with `F1`'s `ACTIVATION` as an argument. If `F2`
3357 `RETURN`s to `F1`'s `ACTIVATION`, `F2` **and** `F1` terminate
3358 immediately, and **`F1`** returns the `RETURN`'s first argument. This
3359 technique is suitable for error exits. `AGAIN` can clearly pull a
3360 similar trick. In the following example, `F1` computes the sum of `F2`
3361 applied to each of its arguments; `F2` computes the product of the
3362 elements of its structured argument, but it aborts if it finds an
3363 element that is not a number.
3365 <DEFINE F1 ACT ("TUPLE" T "AUX" (T1 .T))
3366 <COND (<NOT <EMPTY? .T1>>
3367 <PUT .T1 1 <F2 <1 .T1> .ACT>>
3372 <DEFINE F2 (S A "AUX" (S1 .S))
3373 <REPEAT MY-ACT ((PRD 1))
3374 <COND (<NOT <EMPTY? .S1>>
3375 <COND (<NOT <TYPE? 1 .S1> FIX FLOAT>>
3376 <RETURN #FALSE ("NON-NUMBER") .A>)
3377 (ELSE <SET PRD <* .PRD <1 .S1>>>)>
3378 <SET S1 <REST .S1>>)
3379 (ELSE <RETURN .PRD>)>>>$
3385 #FALSE ("NON-NUMBER")
3387 9.9. Argument List Summary
3388 --------------------------
3390 The following is a listing of all the various tokens which can appear
3391 in the argument `LIST` of a `FUNCTION`, in the order in which they can
3392 occur. Short descriptions of their effects are included. **All** of
3393 them are **optional** -- that is, any of them (in any position) can be
3394 left out or included -- but the order in which they appear **must** be
3395 that of this list. "`QUOTE`d `ATOM`", "matching object", and "2-list"
3400 must be followed by an `ATOM`. It binds that `ATOM` to the
3401 `ENVIRONMENT` which existed when the `FUNCTION` was applied.
3403 (2) `ATOM`s and `QUOTE`d `ATOM`s (any number)
3405 are required arguments. `QUOTE`d `ATOM`s are bound to the matching
3406 object. `ATOM`s are bound to `EVAL` of the matching object in the
3407 `ENVIRONMENT` existing when the `FUNCTION` was applied.
3409 (3) `"OPTIONAL"` or `"OPT"` (they're equivalent)
3411 is followed by any number of `ATOM`s, `QUOTE`d `ATOM`s, or 2-lists.
3412 These are optional arguments. If a matching object exists, an `ATOM`
3413 -- either standing alone or the first element of a 2-list -- is bound
3414 to `EVAL` of the object, performed in the `ENVIRONMENT` existing when
3415 the `FUNCTION` was applied. A `QUOTE`d `ATOM` -- alone or in a 2-list
3416 -- is bound to the matching object itself. If no such object exists,
3417 `ATOM`s and `QUOTE`d `ATOM`s are left unbound, and the first element
3418 of each 2-list is bound to `EVAL` of the corresponding second element.
3419 (This `EVAL` is done in the new `ENVIRONMENT` of the Function as it is
3422 (4) `"ARGS"` (and **not** `"TUPLE"`)
3424 must be followed by an `ATOM`. The `ATOM` is bound to a `LIST` of
3425 **all** the remaining arguments, **unevaluated**. (If there are no
3426 more arguments, the `LIST` is empty.) This `LIST` is actually a `REST`
3427 of the `FORM` applying the `FUNCTION`. If `"ARGS"` appears in the
3428 argument `LIST`, `"TUPLE"` should not appear.
3430 (4) `"TUPLE"` (and **not** `"ARGS"`)
3432 must be followed by an `ATOM`. The `ATOM` is bound to a `TUPLE`
3433 ("`VECTOR` on the control stack") of all the remaining arguments,
3434 **evaluated** in the environment existing when the `FUNCTION` was
3435 applied. (If no arguments remain, the `TUPLE` is empty.) If `"TUPLE"`
3436 appears in the argument `LIST`, `"ARGS"` should not appear.
3438 (5) `"AUX"` or `"EXTRA"` (they're equivalent)
3440 is followed by any number of `ATOM`s or 2-lists. These are auxiliary
3441 variables, bound away from the previous environment for the use of
3442 this Function. `ATOM`s are bound in the `ENVIRONMENT` of the Function,
3443 but they are unassigned; the first element of each 2-list is both
3444 bound and assigned to `EVAL` of the corresponding second element.
3445 (This `EVAL` is done in the new `ENVIRONMENT` of the Function as it is
3448 (6) `"NAME"` or `"ACT"` (they're equivalent)
3450 must be followed by an `ATOM`. The `ATOM` is bound to the `ACTIVATION`
3451 of the current evaluation of the Function.
3453 **ALSO** -- in place of sections (2) (3) **and** (4), you can have
3457 which must be followed by an `ATOM`. The `ATOM` is bound to the `FORM`
3458 which caused application of this `FUNCTION`.
3460 The special terms used above mean this:
3462 "`QUOTE`d `ATOM`" -- a two-element `FORM` whose first element is the
3463 `ATOM` `QUOTE`, and whose second element is any `ATOM`. (Can be typed
3464 -- and will be `PRINT`ed -- as `'atom`.)
3466 "Matching object" -- that element of a `FORM` whose position in the
3467 `FORM` matches the position of a required or optional argument in an
3470 "2-list" -- a two-element `LIST` whose first element is an `ATOM` (or
3471 `QUOTE`d `ATOM`: see below) and whose second element can be anything
3472 but a `SEGMENT`. `EVAL` of the second element is assigned to a new
3473 binding of the first element (the `ATOM`) as the "value by default" in
3474 `"OPTIONAL"` or the "initial value" in `"AUX"`. In the case of
3475 `"OPTIONAL"`, the first element of a 2-list can be a `QUOTE`d `ATOM`;
3476 in this case, an argument which is supplied is not `EVAL`ed, but if it
3477 is not supplied the second element of the `LIST` **is** `EVAL`ed and
3478 assigned to the `ATOM`.
3483 Occasionally there is a valid reason for the first element of a `FORM`
3484 not to be an `ATOM`. For example, the object to be applied to
3485 arguments may be chosen at run time, or it may depend on the arguments
3486 in some way. While `EVAL` is perfectly happy in this case to
3487 `EVAL`uate the first element and go on from there, the compiler
3488 (Lebling, 1979) can generate more efficient code if it knows whether
3489 the result of the evaluation will (1) always be of `TYPE` `FIX`, (2)
3490 always be an applicable non-`FIX` object that evaluates all its
3491 arguments, or (3) neither. The easiest way to tell the compiler if (1)
3492 or (2) is true is to use the `ATOM` `NTH` (section 7.1.2) or `PUT`
3493 (section 7.1.4) in case (1) or `APPLY` in case (2) as the first
3494 element of the `FORM`. (Note: case (1) can compile into in-line code,
3495 but case (2) compiles into a fully mediated call into the
3498 <APPLY object arg-1 ... arg-N>
3500 evaluates *object* and all the *arg-i*'s and then applies the former
3501 to all the latter. An error occurs if *object* evaluates to something
3502 not applicable, or to an `FSUBR`, or to a `FUNCTION` (or user
3503 Subroutine -- chapter 19) with `"ARGS"` or `"CALL"` or `QUOTE`d
3508 <APPLY <NTH .ANALYZERS
3509 <LENGTH <MEMQ <TYPE .ARG> .ARGTYPES>>>
3512 calls a function to analyze `.ARG`. Which function is called depends
3513 on the `TYPE` of the argument; this represents the idea of a dispatch
3519 <CLOSURE function a1 ... aN>
3521 where *function* is a `FUNCTION`, and *a1* through *aN* are any number
3522 of `ATOM`s, returns an object of `TYPE` `CLOSURE`. This can be applied
3523 like any other function, but, whenever it is applied, the `ATOM`s
3524 given in the call to `CLOSURE` are **first** bound to the `VALUE`s
3525 they had when the `CLOSURE` was generated, then the *function* is
3526 applied as normal. This is a "poor man's `funarg`".
3528 A `CLOSURE` is useful when a `FUNCTION` must have state information
3529 remembered between calls to it, especially in these two cases: when
3530 the `LVAL`s of external state `ATOM`s might be compromised by other
3531 programs, or when more than one distinct sequence of calls are active
3532 concurrently. Example of the latter: each object of a structured
3533 `NEWTYPE` might have an associated `CLOSURE` that coughs up one
3534 element at a time, with a value in the `CLOSURE` that is a structure
3535 containing all the relevant information.
3540 10.1. PROG and REPEAT \[1\]
3541 ---------------------------
3543 `PROG` and `REPEAT` are almost identical `FSUBR`s which make it
3544 possible to vary the order of `EVAL`uation arbitrarily -- that is, to
3545 have "jumps". The syntax of `PROG` ("program") is
3547 <PROG act:atom aux:list body>
3551 - *act* is an optional `ATOM`, which is bound to the `ACTIVATION` of
3553 - *aux* is a `LIST` which looks exactly like that part of a
3554 `FUNCTION`'s argument `LIST` which follows an `"AUX"`, and serves
3555 exactly the same purpose. It is not optional. If you need no
3556 temporary variables of `"ACT"`, make it `()`.
3557 - *body* is a non-zero number of arbitrary Muddle expressions.
3559 The syntax of `REPEAT` is identical, except that, of course, `REPEAT`
3560 is the first element of the `FORM`, not `PROG`.
3562 ### 10.1.1. Basic EVALuation \[1\]
3564 Upon entering a `PROG`, an `ACTIVATION` is **always** generated. If
3565 there is an `ATOM` in the right place, the `ACTIVATION` is also bound
3566 to that `ATOM`. The variables in the *aux* (if any) are then bound as
3567 indicated in the *aux*. All of the expressions in *body* are then
3568 `EVAL`uated in their order of occurrence. If nothing untoward happens,
3569 you leave the `PROG` upon evaluating the last expression in *body*,
3570 returning the value of that last expression.
3572 `PROG` thus provides a way to package together a group of things you
3573 wish to do, in a somewhat more limited way than can be done with a
3574 `FUNCTION`. But `PROG`s are generally used for their other properties.
3576 `REPEAT` acts in all ways **exactly** like a `PROG` whose last
3577 expression is `<AGAIN>`. The only way to leave a `REPEAT` is to
3578 explicitly use `RETURN` (or `GO` with a `TAG` -- section 10.4).
3580 ### 10.1.2. AGAIN and RETURN in PROG and REPEAT \[1\]
3582 Within a `PROG` or `REPEAT`, you always have a defined `ACTIVATION`,
3583 whether you bind it to an `ATOM` or not. \[In fact the interpreter
3584 binds it to the `ATOM` `LPROG\ !-INTERRUPTS` ("last PROG"). The
3585 `FSUBR` `BIND` is identical to `PROG` except that `BIND` does not bind
3586 that `ATOM`, so that `AGAIN` and `RETURN` with no `ACTIVATION`
3587 argument will not refer to it. This feature could be useful within
3590 If `AGAIN` is used with no arguments, it uses the `ACTIVATION` of the
3591 closest surrounding `PROG` or `REPEAT` **within the current function**
3592 (an error occurs if there is none) and re-starts the `PROG` or
3593 `REPEAT` without rebinding the *aux* variables, just the way it works
3594 in a `FUNCTION`. With an argument, it can of course re-start any
3595 Function (`PROG` or `REPEAT` or `FUNCTION`) within which it is
3596 embedded at run time.
3598 As with `AGAIN`, if `RETURN` is given no `ACTIVATION` argument, it
3599 uses the `ACTIVATION` of the closest surrounding `PROG` or `REPEAT`
3600 within the current function and causes that `PROG` or `REPEAT` to
3601 terminate and return `RETURN`'s first argument. If `RETURN` is given
3602 **no** arguments, it causes the closest surrounding `PROG` or `REPEAT`
3603 to return the `ATOM` `T`. Also like `AGAIN`, it can, with an
3604 `ACTIVATION` argument, terminate any Function within which it is
3605 embedded at run time.
3607 ### 10.1.3. Examples \[1\]
3609 Examples of the use of `PROG` are difficult to find, since it is
3610 almost never necessary, and it slows down the interpreter (chapter
3611 24). `PROG` can be useful as a point of return from the middle of a
3612 computation, or inside a `COND` (which see), but we won't exemplify
3613 those uses. Instead, what follows is an example of a typically poor
3614 use of `PROG` which has been observed among Lisp (Moon, 1974)
3615 programmers using Muddle. Then, the same thing is done using `REPEAT`.
3616 In both cases, the example `FUNCTION` just adds up all its arguments
3617 and returns the sum. (The `SUBR` `GO` is discussed in section 10.4.)
3620 <DEFINE MY+ ("TUPLE" TUP)
3623 LP <COND (<EMPTY? .TUP> <RETURN .SUM>)>
3624 <SET SUM <+ .SUM <1 .TUP>>>
3625 <SET TUP <REST .TUP>>
3629 <DEFINE MY+ ("TUPLE" TUP)
3631 <COND (<EMPTY? .TUP> <RETURN .SUM>)>
3632 <SET SUM <+ .SUM <1 .TUP>>
3633 <SET TUP <REST .TUP>>>>
3635 Of course, neither of the above is optimal Muddle code for this
3636 problem, since `MY+` can be written using `SEGMENT` evaluation as
3638 <DEFINE MY+ ("TUPLE" TUP) <+ !.TUP>>
3640 There are, of course, lots of problems which can't be handled so
3641 simply, and lots of uses for `REPEAT`.
3643 10.2. MAPF and MAPR: Basics \[1\]
3644 ---------------------------------
3646 `MAPF` ("map first") and `MAPR` ("map rest") are two `SUBR`s which
3647 take care of a majority of cases which require loops over data. The
3648 basic idea is the following:
3650 Suppose you have a `LIST` (or other structure) of data, and you want
3651 to apply a particular function to each element. That is exactly what
3652 `MAPF` does: you give it the function and the structure, and it
3653 applies the function to each element of the structure, starting with
3656 On the other hand, suppose you want to **change** each element of a
3657 structure according to a particular algorithm. This can be done only
3658 with great pain using `MAPF`, since you don't have easy access to the
3659 **structure** inside the function: you have only the structure's
3660 elements. `MAPR` solves the problem by applying a function to `REST`s
3661 of a structure: first to `<REST structure 0>`, then to
3662 `<REST structure 1>`, etc. Thus, the function can change the structure
3663 by changing its argument, for example, by a
3664 `<PUT argument 1 something>`. It can even `PUT` a new element farther
3665 down the structure, which will be seen by the function on subsequent
3668 Now suppose, in addition to applying a function to a structure, you
3669 want to record the results -- the values returned by the function --
3670 in another structure. Both `MAPF` and `MAPR` can do this: they both
3671 take an additional function as an argument, and, when the looping is
3672 over, apply the additional function to **all** the results, and then
3673 return the results of that application. Thus, if the additional
3674 function is `,LIST`, you get a `LIST` of the previous results; if it
3675 is `.VECTOR`, you get a `VECTOR` of results; etc.
3677 Finally, it might be the case that you really want to loop a function
3678 over more than one structure simultaneously. For instance, consider
3679 creating a `LIST` whose elements are the element-by-element sum of the
3680 contents of two other `LIST`s. Both `MAPF` and `MAPR` allow this; you
3681 can, in fact, give each of them any number of structures full of
3682 arguments for your looping function.
3684 This was all mentioned because `MAPF` and `MAPR` appear to be complex
3685 when seen baldly, due to the fact that the argument descriptions must
3686 take into account the general case. Simpler, degenerate cases are
3687 usually the ones used.
3689 ### 10.2.1. MAPF \[1\]
3691 <MAPF finalf loopf s1 s2 ... sN>
3693 where (after argument evaluation)
3695 - *finalf* is something applicable that evaluates all its arguments,
3697 - *loopf* is something applicable to *N* arguments that evaluates
3698 all its arguments; and
3699 - *s1* through *sN* are structured objects (any `TYPE`)
3703 1. First, it applies *loopf* to *N* arguments: the first element of
3704 each of the structures. Then it `REST`s each of the structures,
3705 and does the application again, looping until **any** of the
3706 structures runs out of elements. Each of the values returned by
3707 *loopf* is recorded in a `TUPLE`.
3708 2. Then, it applies *finalf* to all the recorded values
3709 simultaneously, and returns the result of that application. If
3710 *finalf* is a `FALSE`, the recorded values are "thrown away"
3711 (actually never recorded in the first place) and the `MAPF`
3712 returns only the last value returned by *loopf*. If any of the
3713 *si* structures is empty, to that *loopf* is never invoked,
3714 *finalf* is applied to **no** arguments; if *finalf* is a `FALSE`,
3715 `MAPF` returns `#FALSE ()`.
3717 ### 10.2.2 MAPR \[1\]
3719 <MAPR finalf loopf s1 s2 ... sN>
3721 acts just like `MAPF`, but, instead of applying *loopf* to `NTH`s of
3722 the structures -- that is, `<NTH si 1>`, `<NTH si 2>`, etc. -- it
3723 applies it to `REST`s of the structures -- that is, `<REST si 0>`,
3726 ### 10.2.3. Examples \[1\]
3728 Make the element-wise sum of two `LIST`s:
3730 <MAPF .LIST .+ '(1 2 3 4) '(10 11 12 13)>$
3733 Change a `UVECTOR` to contain double its values:
3735 <SET UV '![5 6 7 8 9]>$
3738 #FUNCTION ((L) <PUT .L 1 <* <1 .L> 2>>)
3744 Create a `STRING` from `CHARACTER`s:
3746 <MAPF ,STRING 1 '["MODELING" "DEVELOPMENT" "LIBRARY"]>$
3749 Sum the squares of the elements of a `UVECTOR`:
3751 <MAPF ,+ #FUNCTION ((N) <* .N .N>) '![3 4]>$
3754 A parallel assignment `FUNCTION` (Note that the arguments to `MAPF`
3755 are of different lengths.):
3757 <DEFINE PSET ("TUPLE" TUP)
3761 <REST .TUP </ <LENGTH .TUP> 2>>>>$
3772 Note: it is easy to forget that *finalf* **must** evaluate its
3773 arguments, which precludes the use of an `FSUBR`. It is primarily for
3774 this reason that the `SUBR`s `AND?` and `OR?` were invented. As an
3775 example, the predicate `=?` could have been defined this way:
3778 <COND (<MONAD? .A> <==? .A .B>)
3779 (<AND <NOT <MONAD? .B>>
3780 <==? <TYPE .A> <TYPE .B>>
3781 <==? <LENGTH .A> <LENGTH .B>>>
3782 <MAPF ,AND? ,=? .A .B>)>>
3784 \[By the way, the following shows how to construct a value that has
3785 the same `TYPE` as an argument.
3788 <COND (<MEMQ <PRIMTYPE .S> '![LIST VECTOR UVECTOR STRING]>
3789 <CHTYPE <MAPF ,<PRIMTYPE .S> ,NOT .S>
3792 It works because the `ATOM`s that name the common `STRUCTURED`
3793 `PRIMTYPS`s (`LIST`, `VECTOR`, `UVECTOR` and `STRING`) have as `GVAL`s
3794 the corresponding `SUBR`s to build objects of those `TYPE`s.\]
3796 10.3. More on MAPF and MAPR
3797 ---------------------------
3801 `MAPRET` is a `SUBR` that enables the *loopf* being used in a `MAPR`
3802 or `MAPF` (and lexically within it, that is, not separated from it by
3803 a function call) to return from zero to any number of values as
3804 opposed to just one. For example, suppose a `MAPF` of the following
3807 <MAPF ,LIST <FUNCTION (E) ...> ...>
3809 Now suppose that the programmer wants to add no elements to the final
3810 `LIST` on some calls to the `FUNCTION` and add many on other calls to
3811 the `FUNCTION`. To accomplish this, the `FUNCTION` simply calls
3812 `MAPRET` with the elements it wants added to the `LIST`. More
3813 generally, `MAPRET` causes its arguments to be added to the final
3814 `TUPLE` of arguments to which the *finalf* will be applied.
3816 Warning: `MAPRET` is guaranteed to work only if it is called from an
3817 explicit `FUNCTION` which is the second argument to a `MAPF` or
3818 `MAPR`. In other words, the second argument to `MAPF` or `MAPR` must
3819 be `#FUNCTION (...)` or `<FUNCTION ...>` if `MAPRET` is to be used.
3821 Example: the following returns a `LIST` of all the `ATOM`s in an
3822 `OBLIST` (chapter 15):
3826 <FUNCTION (BKT) <MAPRET !.BKT>>
3831 `MAPSTOP` is the same as `MAPRET`, except that, after adding its
3832 arguments, if any, to the final `TUPLE`, it forces the application of
3833 *finalf* to occur, whether or not the structured objects have run out
3834 of objects. Example: the following copies the first ten (or all)
3835 elements of its argument into a `LIST`:
3837 <DEFINE FIRST-TEN (STRUC "AUX" (I 10))
3840 <COND (<0? <SET I <- .I 1>>> <MAPSTOP .E>)>
3844 ### 10.3.3. MAPLEAVE
3846 `MAPLEAVE` is analogous to `RETURN`, except that it works in
3847 (lexically within) `MAPF` or `MAPR` instead of `PROG` or `REPEAT`. It
3848 flushes the accumulated `TUPLE` of results and returns its argument
3849 (optional, `T` by default) as the value of the `MAPF` or `MAPR`. (It
3850 finds the MAPF/R that should returns in the current binding of the
3851 `ATOM` `LMAP\ !-INTERRUPTS` ("last map").) Example: the following
3852 finds and returns the first non-zero element of its argument, or
3853 `#FALSE ()` if there is none:
3855 <DEFINE FIRST-N0 (STRUC)
3858 <COND (<N==? .X 0> <MAPLEAVE .X>)>>
3861 ### 10.3.4. Only two arguments
3863 If `MAPF` or `MAPR` is given only two arguments, the iteration
3864 function *loopf* is applied to no arguments each time, and the looping
3865 continues indefinitely until a `MAPLEAVE` or `MAPSTOP` is invoked.
3866 Example: the following returns a `LIST` of the integers from one less
3867 than its argument to zero.
3872 <COND (<=? <SET N <- .N 1>>> <MAPSTOP 0>)
3875 One principle use of this form of MAPF/R involves processing input
3876 characters, in cases where you don't know how many characters are
3877 going to arrive. The example below demonstrates this, using `SUBR`s
3878 which are more fully explained in chapter 11. Another example can be
3879 found in chapter 13.
3881 Example: the following `FUNCTION` reads characters from the current
3882 input channel until an `$` (`ESC`) is read, and then returns what was
3883 read as one `STRING`. (The `SUBR` `READCHR` reads one character from
3884 the input channel and returns it. `NEXTCHR` returns the next
3885 `CHARACTER` which `READCHR` will return -- chapter 11.)
3889 <FUNCTION () <COND (<NOT <==? <NEXTCHR> <ASCII 27>>>
3895 <PROG () <READCHR> ;"Flush the ESC ending this input."
3897 ABC123<+ 3 4>$"ABC123<+ 3 4>"
3899 ### 10.3.5. STACKFORM
3901 The `FSUBR` `STACKFORM` is archaic, due to improvements in the
3902 implementation of MAPF/R, and it should not be used in new programs.
3904 <STACKFORM function arg pred>
3906 is exactly equivalent to
3909 <FUNCTION () <COND (pred arg) (T <MAPSTOP>)>>>
3911 In fact MAPF/R is more powerful, because `MAPRET`, `MAPSTOP`, and
3912 `MAPLEAVE` provide flexibility not available with `STACKFORM`.
3917 `GO` is provided in Muddle for people who can't recover from a
3918 youthful experience with Basic, Fortran, PL/I, etc. The `SUBR`s
3919 previously described in this chapter are much more tasteful for making
3920 good, clean, "structured" programs. `GO` just bollixes things.
3922 `GO` is a `SUBR` which allows you to break the normal order of
3923 evaluation and re-start just before any top-level expression in a
3924 `PROG` or `REPEAT`. It can take two `TYPE`s of arguments: `ATOM` or
3927 Given an `ATOM`, `GO` searches the *body* of the immediately
3928 surrounding `PROG` or `REPEAT` within the current Function, starting
3929 after *aux*, for an occurrence of that `ATOM` at the top level of
3930 *body*. (This search is effectively a `MEMQ`.) If it doesn't find the
3931 `ATOM`, an error occurs. If it does, evaluation is resumed at the
3932 expression following the `ATOM`.
3934 The `SUBR` `TAG` generates and returns objects of `TYPE` `TAG`. This
3935 `SUBR` takes one argument: an `ATOM` which would be a legal argument
3936 for a `GO`. An object of `TYPE` `TAG` contains sufficient information
3937 to allow you to `GO` to any top-level position in a `PROG` or `REPEAT`
3938 from within any function called inside the `PROG` or `REPEAT`. `GO`
3939 with a `TAG` is vaguely like `AGAIN` with an `ACTIVATION`; it allows
3940 you to "go back" to the middle of any `PROG` or `REPEAT` which called
3941 you. Also like `ACTIVATION`s, `TAG`s into a `PROG` or `REPEAT` can no
3942 longer be used after the `PROG` or `REPEAT` has returned. `LEGAL?` can
3943 be used to see if a `TAG` is still valid.
3945 10.5. Looping versus Recursion
3946 ------------------------------
3948 Since any program in Muddle can be called recursively, champions of
3949 "pure Lisp" (Moon, 1974) or somesuch may be tempted to implement any
3950 repetitive algorithm using recursion. The advantage of the looping
3951 techniques described in this chapter over recursion is that the
3952 overhead of calls is eliminated. However, a long program (say, bigger
3953 than half a printed page) may be more difficult to write iteratively
3954 than recursively and hence more difficult to maintain. A program whose
3955 repetition is controlled by a structured object (for example, "walking
3956 a tree" to visit each monad in the object) often should use looping
3957 for covering one "level" of the structure and recursion to change
3960 Chapter 11. Input/Output
3961 ========================
3963 The Muddle interpreter can transmit information between an object in
3964 Muddle and an external device in three ways. Historically, the first
3965 way was to **convert** an object into a string of characters, or vice
3966 versa. The transformation is nearly one-to-one (although some Muddle
3967 objects, for example `TUPLE`s, cannot be input in this way) and is
3968 similar in style to Fortran's formatted I/O. It is what `READ` and
3969 `PRINT` do, and it is the normal method for terminal I/O.
3971 The second way is used for the contents of Muddle objects rather than
3972 the objects themselves. Here an **image** of numbers or characters
3973 within an object is transmitted, similar in style to Fortran's
3976 The third way is to **dump** an object in a clever format so that it
3977 can be reproduced exactly when input the next time. Exact reproduction
3978 means that any sharing between structures or self-reference is
3979 preserved: only the garbage collector itself can do I/O in this way.
3981 11.1. Conversion I/O
3982 --------------------
3984 All conversion-I/O `SUBR`s in Muddle take an optional argument which
3985 directs their attention to a specific I/O channel. This section will
3986 describe `SUBR`s without their optional arguments. In this situation,
3987 they all refer to a particular channel by default, initially the
3988 terminal running the Muddle. When given an optional argument, that
3989 argument follows any arguments indicated here. Some of these `SUBR`s
3990 also have additional optional arguments, relevant to conversion,
3991 discussion of which will be deferred until later.
3995 All of the following input Subroutines, when directed at a terminal,
3996 hang until `$` (`ESC`) is typed and allow normal use of `rubout`,
3997 `^D`, `^L` and `^@`.
4003 This returns the entire Muddle object whose character representation
4004 is next in the input stream. Successive `<READ>`s return successive
4005 objects. This is precisely the `SUBR` `READ` mentioned in chapter 2.
4006 See also sections 11.3, 15.7.1, and 17.1.3 for optional arguments.
4008 #### 11.1.1.2. READCHR
4012 ("read character") returns the next `CHARACTER` in the input stream.
4013 Successive `<READCHR>`s return successive `CHARACTER`s.
4015 #### 11.1.1.3. NEXTCHR
4019 ("next character") returns the `CHARACTER` which `READCHR` will return
4020 the next time `READCHR` is called. Multiple `<NEXTCHR>`s, with no
4021 input operations between them, all return the same thing.
4025 If an object to be output requires (or can tolerate) separators within
4026 it (for example, between the elements in a structured object or after
4027 the `TYPE` name in "\# notation"), these conversion-output `SUBR`s
4028 will use a carriage-return/line-feed separator to prevent overflowing
4029 a line. Overflow is detected in advance from elements of the `CHANNEL`
4030 in use (section 11.2.8).
4032 #### 11.1.2.1. PRINT
4036 This outputs, in order,
4038 1. a carriage-return line-feed,
4039 2. the character representation of `EVAL` of its argument (`PRINT` is
4043 and then returns `EVAL` of its argument. This is precisely the `SUBR`
4044 `PRINT` mentioned in chapter 2.
4046 #### 11.1.2.2. PRIN1
4050 outputs just the representation of, and returns, `EVAL` of *any*.
4052 #### 11.1.2.3. PRINC
4056 ("print characters") acts exactly like `PRIN1`, except that
4058 1. if its argument is a `STRING` or a `CHARACTER`, it suppresses the
4059 surrounding `"`s or initial `!\` respectively; or
4060 2. if its argument is an `ATOM`, it suppresses any `\`s or `OBLIST`
4061 trailers (chapter 15) which would otherwise be necessary.
4063 If `PRINC`'s argument is a structure containing `STRING`s,
4064 `CHARACTER`s, or `ATOM`s, the service mentioned will be done for all
4065 of them. Ditto for the `ATOM` used to name the `TYPE` in "\#
4068 #### 11.1.2.4. TERPRI
4072 ("terminate printing") outputs a carriage-return line-feed and then
4073 returns `# FALSE ()`!
4077 ("carriage-return line-feed") outputs a carriage-return line-feed and
4080 #### 11.1.2.6. FLATSIZE
4082 <FLATSIZE any max:fix radix:fix>
4084 does not actually cause any output to occur and does not take a
4085 `CHANNEL` argument. Instead, or compares *max* with the number of
4086 characters `PRIN1` would take to print *any*. If *max* is less than
4087 the number of characters needed (including the case where *any* is
4088 self-referencing, `FLATSIZE` returns `#FALSE ()`; otherwise, it
4089 returns the number of characters needed by `PRIN1` *any*. *radix*
4090 (optional, ten by default) is used for converting any `FIX`es that
4093 This `SUBR` is especially useful in conjunction with (section 11.2.8)
4094 those elements of a `CHANNEL` which specify the number of characters
4095 per output line and the current position on an input line.
4100 I/O channels are dynamically assigned in Muddle, and are represented
4101 by an object of `TYPE` `CHANNEL`, which is of `PRIMTYPE` `VECTOR`. The
4102 format of a `CHANNEL` will be explained later, in section 11.2.8.
4103 First, how to generate and use them.
4107 <OPEN mode file-spec>
4111 <OPEN mode name1 name2 device dir>
4113 `OPEN` is a `SUBR` which creates and returns a `CHANNEL`. All its
4114 arguments must be of `TYPE` `STRING`, and **all** are optional. The
4115 preceding statement is false when the *device* is `"INT"` or `"NET"`;
4116 see sections 11.9 and 11.10. If the attempted opening of an
4117 operating-system I/O channel fails, `OPEN` returns
4118 `#FALSE (reason:string file-spec:string status:fix)`, where the
4119 *reason* and the *status* are supplied by the operating system, and
4120 the `file-spec` is the standard name of the file (after any name
4121 transformations by the operating system) that Muddle was trying to
4124 The choice of *mode* is usually determined by which `SUBR`s will be
4125 used on the `CHANNEL`, and whether or not the *device* is a terminal.
4126 The following table tells which `SUBR`s can be used with which modes,
4127 where `OK` indicates an allowed use:
4129 -------------------------------------------------------------------------------------------------------------------------------------------------
4130 "READ" "PRINT" "READB" "PRINTB", "PRINTO" mode / SUBRs
4131 -------------------- --------------------- --------------------- -------------------------------------------- -----------------------------------
4132 OK OK `READ` `READCHR` `NEXTCHR`
4133 `READSTRING` `FILECOPY`
4136 OK OK\* `PRINT` `PRIN1` `PRINC` `IMAGE`
4137 `CRLF` `TERPRI` `FILECOPY`
4138 `PRINTSTRING` `BUFOUT` `NETS`
4141 OK `READB` `GC-READ`
4143 OK `PRINTB` `GC-DUMP`
4152 -------------------------------------------------------------------------------------------------------------------------------------------------
4154 `*` PRINTing (or `PRIN1`ing) an `RSUBR` (chapter 19) on a `"PRINTB"`
4155 or `"PRINTO"` `CHANNEL` has special effects.
4157 `"PRINTB"` differs from `"PRINTO"` in that the latter mode is used to
4158 update a `"DSK"` file without copying it. `"READB"` and `"PRINTB"` are
4159 not used with terminals. `"READ"` is the mode used by default.
4161 The next one to four arguments to `OPEN` specify the file involved. If
4162 only one `STRING` is used, it can contain the entire specification,
4163 according to standard operating-system syntax. Otherwise, the
4164 string(s) are interpreted as follows:
4166 *name1* is the first file name, that part to the left of the space (in
4167 the ITS version) or period (in the Tenex and Tops-20 versions). The
4168 name used by default is `<VALUE NM1>`, if any, otherwise `"INPUT"`.
4170 *name2* is the second fail name, that part to the right of the space
4171 (ITS) or period (Tenex and Tops-20). The name used by default is
4172 `<VALUE NM2>`, if any, otherwise `">"` or `"MUD"` and highest version
4173 number (Tenex) or generation number (Tops-20).
4175 *device* is the device name. The name used by default is
4176 `<VALUE DEV>`, if any, otherwise `"DSK"`. (Devices about which Muddle
4177 has no special knowledge are assumed to behave like `"DSK"`.)
4179 *dir* is the disk-directory name. The name used by default is
4180 `<VALUE SNM>`, if any, otherwise the "working-directory" name as
4181 defined by her operating system.
4185 `<OPEN "PRINT" "TPL:">` opens a conversion-output channel to the TPL
4188 `<OPEN "PRINT" "DUMMY" "NAMES" "IPL">` does the same.
4190 `<OPEN "PRINT" "TPL">` opens a `CHANNEL` to the file `DSK:TPL >` (ITS
4191 version) or `DSK:TPL.MUD` (Tenex and Tops-20 versions).
4193 `<OPEN "READ" "FOO" ">" "DSK" "GUEST">` opens up a conversion-input
4194 `CHANNEL` to the given file.
4196 `<OPEN "READ" "GUEST;FOO">` does the same in the ITS version.
4200 `OPEN-NR` is the same as `OPEN`, except that the date and time of last
4201 reference of the opened file are not changes.
4203 ### 11.2.3. CHANNEL (the SUBR)
4205 `CHANNEL` is called exactly like `OPEN`, but it **always** return an
4206 unopened `CHANNEL`, which can later be opened by `RESET` (below) just
4207 as if it had once been open.
4209 ### 11.2.4. FILE-EXISTS?
4211 `FILE-EXISTS?` tests for the existence of a file without creating a
4212 `CHANNEL`, which occupies about a hundred machine words of storage. It
4213 takes file-name arguments just like `OPEN` (but no *mode* argument)
4214 and returns either T, \`\#FALSE (reason:string status:fix),
4220 closes *channel* and returns its argument, with its "state" changed to
4221 "closed". If *channel* is for output, all buffered output is written
4222 out first. No harm is done if *channel* is already `CLOSE`d.
4224 ### 11.2.6. CHANLIST
4228 returns a `LIST` whose elements are all the currently open `CHANNEL`s.
4229 The first two elements are usually `.INCHAN` and `.OUTCHAN` (see
4230 below). A `CHANNEL` not referenced by anything except `<CHANLIST>`
4231 will be `CLOSEd` during garbage collection.
4233 ### 11.2.7. INCHAN and OUTCHAN
4235 The channel used by default for input `SUBR`s is the local value of
4236 the `ATOM` `INCHAN`. The channel used by default for output SUBRs is
4237 the local value of the `ATOM` `OUTCHAN`.
4239 You can direct I/O to a `CHANNEL` by `SET`ting `INCHAN` or `OUTCHAN`
4240 (remembering their old values somewhere), or by giving the `SUBR` you
4241 with to use an argument of `TYPE` `CHANNEL`. (These actually have the
4242 same effect, because `READ` binds `INCHAN` to an explicit argument,
4243 and `PRINT` binds `OUTCHAN` similarly. Thus the `CHANNEL` being used
4244 is available for `READ` macros (section 17.1), or by giving the `SUBR`
4245 you wish to use an argument of `TYPE` `CHANNEL`. Thus the `CHANNEL`
4246 being used is available for `READ` macros (section 17.1) and
4247 `PRINTTYPE`s (section 6.4.4).)
4249 By the way, a good trick for playing with `INCHAN` and `OUTCHAN`
4250 values within a function is to use the `ATOM`s `INCHAN` and `OUTCHAN`
4251 as `"AUX"` variables, re-binding their local values to the `CHANNEL`
4252 you want. When you leave , of course, the old `LVAL`s are expanded
4253 (which is the whole point). The `ATOM`s must be declared `SPECIAL`
4254 (chapter 14) for this trick to compile correctly.
4256 `INCHAN` and `OUTCHAN` also have global values, initially the
4257 `CHANNEL`s directed at the terminal running `Muddle`. Initially,
4258 `INCHAN`'s and `OUTCHAN`s local and global values are the same.
4260 ### 11.2.8. Contents of CHANNELs
4262 The contents of an object of `TYPE` `CHANNEL` are referred to by the
4263 I/O `SUBR`s each time such a `SUBR` is used. If you change the
4264 contents of a `CHANNEL` (for example, with `PUT`), the next use of
4265 that `CHANNEL` will be changed accordingly. Some elements of
4266 `CHANNEL`s, however, should be played with seldom, if ever, and only
4267 at your own peril. These are marked below with an `*` (asterisk).
4270 There follows a table of the contents of a `CHANNEL`, the `TYPE` of
4271 each element, and an interpretation. The format used is the following:
4273 *element-number: type interpretation*
4275 ----------------------------------------------------------------------------------------------------
4276 element-number type interpretation
4277 -------------------------- ------------------ ------------------------------------------------------
4278 -1 `LIST` transcript channel(s) (see below)
4280 \* 0 varies device-dependent information
4282 \* 1 `FIX` channel number (ITS) or JFN (Tenex and Tops-20), `0`
4283 for internal or closed
4287 \* 3 `STRING` first file name argument
4289 \* 4 `STRING` second file name argument
4291 \* 5 `STRING` device name argument
4293 \* 6 `STRING` directory name argument
4295 \* 7 `STRING` real first file name
4297 \* 8 `STRING` real second file name
4299 \* 9 `STRING` real device name
4301 \* 10 `STRING` real directory name
4303 \* 11 `FIX` various status bits
4305 \* 12 `FIX` PDP-10 instruction used to do one I/O operation
4307 13 `FIX` number of characters per line of output
4309 14 `FIX` current character position on a line
4311 15 `FIX` number of lines per page
4313 16 `FIX` current line number on a page
4315 17 `FIX` access pointer for file-oriented devices
4317 18 `FIX` radix for `FIX` conversion
4319 19 `FIX` sink for an internal `CHANNEL`
4320 ----------------------------------------------------------------------------------------------------
4322 N.B.: The elements of a `CHANNEL` below number 1 are usually invisible
4323 but are obtainable via `<NTH <TOP channel> fix>`, for some appropriate
4326 The transcript-channels slot has this meaning: if this slot contains a
4327 `LIST` of `CHANNEL`s, then anything input or output on the original
4328 `CHANNEL` is output on these `CHANNEL`s. Caution: do not use a
4329 `CHANNEL` as its own transcript channel; you probably won't live to
4332 #### 11.2.8.2. Input CHANNELs
4334 The contents of the elements up to number 12 of a `CHANNEL` used for
4335 input are the same as that for output. The remaining elements are as
4336 follows ((same) indicates that the use is the same as that for
4339 element-number type interpretation
4340 ---------------- ---------- ---------------------------------------------------
4341 13 varies object evaluated when end of file is reached
4342 \* 14 `FIX` one "look-ahead" character, used by `READ`
4343 \* 15 `FIX` PDP-10 instruction executed waiting for input
4344 16 `LIST` queue of buffers for input from a terminal
4345 17 `FIX` access pointer for file-oriented devices (same)
4346 18 `FIX` radix for `FIX` conversion (same)
4347 19 `STRING` buffer for input or source for internal `CHANNEL`
4349 11.3. End-of-File "Routine"
4350 ---------------------------
4352 As mentioned above, an explicit `CHANNEL` is the first optional
4353 argument of all `SUBR`s used for conversion I/O. The second optional
4354 argument for conversion-**input** `SUBR`s is an "end-of-file routine"
4355 -- that is, something for the input `SUBR` to `EVAL` and return, if it
4356 reaches the end of the file it is reading. A typical end-of-file
4357 argument is a `QUOTE`d `FORM` which applies a function of yours. The
4358 value of this argument used by default is a call to `ERROR`. Note: the
4359 `CHANNEL` has been `CLOSE`d by the time this argument is evaluated.
4361 Example: the following `FUNCTION` counts the occurrences of a
4362 character in a file, according to its arguments. The file names,
4363 device, and directory are optional, with the usual names used by
4367 (CHAR "TUPLE" FILE "AUX" (CNT 0) (CHN <OPEN "READ" !.FILE>))
4368 <COND (.CHN ;"If CHN is FALSE, bad OPEN: return the FALSE
4369 so result can be tested by another FUNCTION."
4371 <AND <==? .CHAR <READCHR .CHN '<RETURN>>>
4372 <SET CNT <+ 1 .CNT>>>>
4373 ;"Until EOF, keep reading and testing a character at a time."
4374 .CNT ;"Then return the count.")>>
4381 #### 11.4.1.1. READB
4383 <READB buffer:uvector-or-storage channel eof:any>
4385 The *channel* must be open in `"READB"` mode. `READB` will read as
4386 many 36-bit binary words as necessary to fill the *buffer* (whose
4387 `UTYPE` must be of `PRIMTYPE` `WORD`), unless it hits the end of the
4388 file. `READB` returns the number of words actually read, as a
4389 `FIX`ed-point number. This will normally be the length of the
4390 *buffer*, unless the end of file was read, in which case it will be
4391 less, and only the beginning of *buffer* will have been filled
4392 (`SUBSTRUC` may help). An attempt to `READB` again, after *buffer* is
4393 not filled, will evaluate the end-of-file routine *eof*, which is
4394 optional, a call to `ERROR` by default.
4396 #### 11.4.1.2. READSTRING
4398 <READSTRING buffer:string channel stop:fix-or-string eof>
4400 is the `STRING` analog to `READB`, where *buffer* and *eof* are as in
4401 `READB`, and *channel* is any input `CHANNEL` (`.INCHAN` by default).
4402 *stop* tells when to stop inputting: if a `FIX`, read this many
4403 `CHARACTER`s (fill up *buffer* by default); if a `STRING`, stop
4404 reading if any `CHARACTER` in this `STRING` is read (don't include
4405 this `CHARACTER` in final `STRING`).
4409 #### 11.4.2.1. PRINTB
4411 <PRINTB buffer:uvector-or-storage channel>
4413 This call writes the entire contents of the *buffer* into the
4414 specified channel open in `"PRINTB"` or `"PRINTO"` mode. It returns
4417 #### 11.4.2.2. PRINTSTRING
4419 <PRINTSTRING buffer:string channel count:fix>
4421 is analogous to `READSTRING`. It outputs *buffer* on *channel*, either
4422 the whole thing or the first *count* characters, and returns the
4423 number of characters output.
4425 #### 11.4.2.3. IMAGE
4429 is a rather special-purpose `SUBR`. When any conversion-output routine
4430 outputs an ASCII control character (with special exceptions like
4431 carriage-returns, line-feeds, etc.), it actually outputs two
4432 characters: `^` (circumflex), followed by the upper-case character
4433 which has been control-shifted. `IMAGE`, on the other hand, always
4434 outputs the real thing: that ASCII character whose ASCII 7-bit code is
4435 *fix*. It is guaranteed not to give any gratuitous linefeeds or such.
4436 *channel* is optional, `.OUTCHAN` by default, and its slots for
4437 current character position (number 14) and current line number (16)
4438 are not updated. `IMAGE` returns *fix*.
4443 ### 11.5.1. Output: GC-DUMP
4445 <GC-DUMP any printb:channel-or-false>
4447 dumps *any* on *printb* in a clever format so that `GC-READ` (below)
4448 can reproduce *any* exactly, including sharing. *any* cannot live on
4449 the control stack, not can it be of `PRIMTYPE` `PROCESS` or `LOCD` or
4450 `ASOC` (which see). *any* is returned as a value.
4452 If *printb* is a `CHANNEL`, it must be open in `"PRINTB"` or
4453 `"PRINTO"` mode. If *printb* is a `FALSE`, `GC-DUMP` instead returns a
4454 `UVECTOR` (of `UTYPE` `PRIMTYPE` `WORD`) that contains what it would
4455 have output on a `CHANNEL`. This `UVECTOR` can be `PRINTB`ed anywhere
4456 you desire, but, if it is changed **in any way**, `GC-READ` will not
4457 be able to input it. Probably the only reason to get it is to check
4458 its length before output.
4460 Except for the miniature garbage collection required, `GC-DUMP` is
4461 about twice as fast as `PRINT`, but the amount of external storage
4462 used is two or three times as much.
4464 ### 11.5.2. Input: GC-READ
4466 <GC-READ readb:channel eof:any>
4468 returns one object from the *channel*, which must be open in `"READB"`
4469 mode. The file must have been produced by `GC-DUMP`. *eof* is
4470 optional. `GC-READ` is about ten times faster than `READ`.
4475 The entire state of Muddle can be saved away in a file for later
4476 restoration: this is done with the `SUBR`s `SAVE` and `RESTORE`. This
4477 is a very different form of I/O from any mentioned up to now; the file
4478 used contains an actual image of your Muddle address space and is not,
4479 in general, "legible" to other Muddle routines. `RESTORE`ing a `SAVE`
4480 file is **much** faster than re-`READ`ing the objects it contains.
4482 Since a `SAVE` file does not contain all extant Muddle objects, only
4483 the impure and `PURIFY`ed (section 22.9.2) ones, a change to the
4484 interpreter has the result of making all previous `SAVE` files
4485 unusable. To prevent errors from arising from this, the interpreter
4486 has a release number, which is incremented whenever changes are
4487 installed. The current release number is printed out on initially
4488 starting up the program and is available as the `GVAL` of the `ATOM`
4489 `MUDDLE`. This release number is written out as the very first part of
4490 each `SAVE` file. If `RESTORE` attempts to re-load a `SAVE` file whose
4491 release number is not the same as the interpreter being used, an error
4492 is produced. If desired, the release number of a `SAVE` file can be
4493 obtained by doing a `READ` of that file. Only that initial `READ` will
4494 work; the rest of the file is not ASCII.
4498 <SAVE file-spec:string gc?:false-or-any>
4502 <SAVE name1 name2 device dir gc?:false-or-any>
4504 saves the entire state of your Muddle away in the file specified by
4505 its arguments, and then returns `"SAVED"`. All `STRING` arguments are
4506 optional, with `"MUDDLE"`, `"SAVE"`, `"DSK"`, and `<VALUE SNM>` used
4507 by default. *gc?* is optional and, if supplied and of `TYPE` `FALSE`,
4508 causes no garbage collection to occur before `SAVE`ing. (`FSAVE` is an
4509 alias for `SAVE` that may be seen in old programs.)
4511 If, after restoring, `RESTORE` finds that `<VALUE SNM>` is the null
4512 `STRING` (`""`), it will ask the operating system for the name of the
4513 "working directory" and call `SNAME` with the result. This mechanism
4514 is handy for "public" `SAVE` files, which should not point the user at
4515 a particular disk directory.
4517 In the ITS version, the file is actually written with the name
4518 `_MUDS_ >` and renamed to the argument(s) only when complete, to
4519 prevent losing a previous `SAVE` file if a crash occurs. In the Tenex
4520 and Tops-20 versions, version/generation numbers provide the same
4525 <DEFINE SAVE-IT ("OPTIONAL"
4526 (FILE '("PUBLIC" "SAVE" "DSK" "GUEST"))
4529 <COND (<=? "SAVED" <SAVE !.FILE>> ;"See below."
4534 <PRINC "Amazing program at your service.">
4544 <RESTORE name1 name2 device dir>
4546 **replaces** the entire current state of your Muddle with that `SAVE`d
4547 in the file specified. All arguments are optional, with the same
4548 values used by default as by `SAVE`.
4550 `RESTORE` completely replaces the contents of the Muddle, including
4551 the state of execution existing when the `SAVE` was done and the state
4552 of all open I/O `CHANNEL`s. If a file which was open when the `SAVE`
4553 was done does not exist when the `RESTORE` is done, a message to that
4554 effect will appear on the terminal.
4556 A `RESTORE` **never** returns (unless it gets an error): it causes a
4557 `SAVE` done some time ago to return **again** (this time with the
4558 value `"RESTORED"`), even if the `SAVE` was done in the midst of
4559 running a program. In the latter case, the program will continue its
4560 execution upon `RESTORE`ation.
4562 11.7. Other I/O Functions
4563 -------------------------
4567 <LOAD input:channel look-up>
4569 eventually returns `"DONE"`. First, however, it `READ`s and `EVAL`s
4570 every Muddle object in the file pointed to by *input*, and then
4571 `CLOSE`s *input*. Any occurrences of `rubout`, `^@`, `^D`, `^L`, etc.,
4572 in the file are given no special meaning; they are simply `ATOM`
4575 *look-up* is optional, used to specify a `LIST` of `OBLIST`s for the
4576 `READ`. `.OBLIST` is used by default (chapter 15).
4580 <FLOAD file-spec look-up>
4584 <FLOAD name1 name2 device dir look-up>
4586 ("file load") acts just like `LOAD`, except that it takes arguments
4587 (with values used by default) like `OPEN`, `OPEN`s the `CHANNEL`
4588 itself for reading, and `CLOSE`s the `CHANNEL` when done. *look-up* is
4589 optional, as in `LOAD`. If the `OPEN` fails, an error occurs, giving
4590 the reason for failure.
4594 `<SNAME string>` ("system name", a hangover from ITS) is identical in
4595 effect with `<SETG SNM string>`, that is, it causes *string* to become
4596 the *dir* argument used by default by all `SUBR`s which want file
4597 specifications (in the absence of a local value for `SNM`). `SNAME`
4598 returns its argument.
4600 `<SNAME>` is identical in effect with `<GVAL SNM>`, that is, it
4601 returns the current *dir* used by default.
4605 <ACCESS channel fix>
4607 returns *channel*, after making the next character or binary word
4608 (depending on the mode of *channel*, which should not be `"PRINT"`)
4609 which will be input from or output to *channel* the (*fix*+1)st one
4610 from the beginning of the file. *channel* must be open to a randomly
4611 accessible device (`"DSK"`, `"USR"`, etc.). A *fix* of `0` positions
4612 *channel* at the beginning of the file.
4614 ### 11.7.5. FILE-LENGTH
4616 <FILE-LENGTH input:channel>
4618 returns a `FIX`, the length of the file open on *input*. This
4619 information is supplied by the operating system, and it may not be
4620 available, for example, with the `"NET"` device (section 11.10). If
4621 *input*'s mode is `"READ"`, the length is in characters (rounded up to
4622 a multiple of five); if `"READB"`, in binary words. If `ACCESS` is
4623 applied to *input* and this length or more, then the next input
4624 operation will detect the end of file.
4626 ### 11.7.6. FILECOPY
4628 <FILECOPY input:channel output:channel>
4630 copies characters from *input* to *output* until the end of file on
4631 *input* (thus closing *input*) and returns the number of characters
4632 copied. Both arguments are optional, with `.INCHAN` and `.OUTCHAN`
4633 used by default, respectively. The operation is essentially a
4634 `READSTRING` -- `PRINTSTRING` loop. Neither `CHANNEL` need be freshly
4635 `OPEN`ed, and *output* need not be immediately `CLOSE`d. Restriction:
4636 internally a `<FILE-LENGTH input>` is done, which must succeed; thus
4637 `FILECOPY` might lose if *input* is a `"NET"` `CHANNEL`.
4643 returns *channel*, after "resetting" it. Resetting a `CHANNEL` is like
4644 `OPEN`ing it afresh, with only the file-name slots preserved. For an
4645 input `CHANNEL`, this means emptying all input buffers and, if it is a
4646 `CHANNEL` to a file, doing an `ACCESS` to `0` on it. For an output
4647 `CHANNEL`, this means returning to the beginning of the file -- which
4648 implies, if the mode is not `"PRINTO"`, destroying any output done to
4649 it so far. If the opening fails (for example, if the mode slot of
4650 *channel* says input, and if the file specified in its real-name slots
4651 does not exist), `RESET` (like `OPEN`) returns
4652 `#FALSE (reason:string file-spec:string status:fix)`.
4656 <BUFOUT output:channel>
4658 causes all internal Muddle buffers for *output* to be written out and
4659 returns its argument. This is helpful if the operating system or
4660 Muddle is flaky and you want to attempt to minimize your losses. The
4661 output may be padded with up to four extra spaces, if *output*'s mode
4666 `RENAME` is for renaming and deleting files. It takes three kinds of
4669 - (a) two file names, in either single- or multi-`STRING` format,
4670 separated by the `ATOM` `TO`,
4672 - (b) one file name in either format, or
4674 - (c) a `CHANNEL` and a file name in either format (only in the ITS
4677 Omitted file-name parts use the same values by default as does `OPEN`.
4678 If the operation is successful, `RENAME` returns `T`, otherwise
4679 `#FALSE (reason:string status:fix)`.
4681 In case (a) the file specified by the first argument is renamed to the
4682 second argument. For example:
4684 <RENAME "FOO 3" TO "BAR"> ;"Rename FOO 3 to BAR >."
4686 In case (b) the single file name specifies a file to be deleted. For
4689 <RENAME "FOO FOO DSK:HARRY;"> ;"Rename FOO 3 to BAR >."
4691 In case (c) the `CHANNEL` must be open in either `"PRINT"` or
4692 `"PRINTB"` mode, and a rename while open for writing is attempted. The
4693 real-name slots in the `CHANNEL` are updated to reflect any successful
4696 11.8. Terminal CHANNELs
4697 -----------------------
4699 Muddle behaves like the ITS version of the text editor Teco with
4700 respect to typing in carriage-return, in that it automatically adds a
4701 line-feed. In order to type in a lone carriage-return, a
4702 carriage-return followed by a rubout must be typed. Also `PRINT`,
4703 `PRINT1` and `PRINC` do not automatically add a line-feed when a
4704 carriage-return is output. This enables overstriking on a terminal
4705 that lacks backspacing capability. It also means that what goes on a
4706 terminal and what goes in a file are more likely to look the same.
4708 In the ITS version, Muddle's primary terminal output channel (usually
4709 `,OUTCHAN`) is normally not in "display" mode, except when `PRINC`ing
4710 a `STRING`. Thus errors will rarely occur when a user is typing in
4711 text containing display-mode control codes.
4713 In the ITS version, Muddle can start up without a terminal, give
4714 control of the terminal away to an inferior operating-system process
4715 or get it back while running. Doing a `RESET` on either of the
4716 terminal channels causes Muddle to find out if it now has the
4717 terminal; if it does, the terminal is reopened and the current screen
4718 size and device parameters are updated. If it doesn't have the
4719 terminal, an internal flag is set, causing output to the terminal to
4720 be ignored and attempted input from the terminal to make the
4721 operating-system process go to sleep.
4723 In the ITS version, there are some peculiarities associated with
4724 pseudo-terminals (`"STY"` and `"STn"` devices). If the `CHANNEL` given
4725 to `READCHR` is open in `"READ"` mode to a pseudo-terminal, and if no
4726 input is available, `READCHR` returns `-1`, `TYPE` `FIX`. If the
4727 `CHANNEL` given to `READSTRING` is open in `"READ"` mode to a
4728 pseudo-terminal, reading also stops if and when no more characters are
4729 available, that is, when `READCHR` would return `-1`.
4734 <ECHOPAIR terminal-in:channel terminal-out:channel>
4736 returns its first argument, after making the two `CHANNEL`s "know
4737 about each other" so that `rubout`, `^@`, `^D` and `^L` on
4738 *terminal-in* will cause the appropriate output on *terminal-out*.
4742 <TTYECHO terminal-input:channel pred>
4744 turns the echoing of typed characters on *channel* off or on,
4745 according to whether or not *pred* is `TYPE` `FALSE`, and returns
4746 *channel*. It is useful in conjunction with `TYI` (below) for a
4747 program that wants to do character input and echoing in its own
4752 <TYI terminal-input:channel>
4754 returns one `CHARACTER` from *channel* (optional, `.INCHAN` by
4755 default) when it is typed, rather than after `$` (`ESC`) is typed, as
4756 is the case with `READCHR`. The following example echos input
4757 characters as their ASCII values, until a carriage-return is typed:
4759 <REPEAT ((FOO <TTYECHO .INCHAN <>>))
4760 <AND <==? 13 <PRINC <ASCII <TYI .INCHAN>>>>
4761 <RETURN <TTYECHO .INCHAN T>>>>
4763 11.9. Internal CHANNELs
4764 -----------------------
4766 If the *device* specified in an `OPEN` is `"INT"`, a `CHANNEL` is
4767 created which does not refer to any I/O device outside Muddle. In this
4768 case, the mode must be `"READ"` or `"PRINT"`, and there is another
4769 argument, which must be a function.
4771 For a `"READ"` `CHANNEL`, the function must take no arguments.
4772 Whenever a `CHARACTER` is desired from this `CHANNEL`, the function
4773 will be applied to no arguments and must return a `CHARACTER`. This
4774 will occur once per call to `READCHR` using this `CHANNEL`, and
4775 several times per call to `READ`. In the ITS version, the function can
4776 signal that its "end-of-file" has been reached by returning
4777 `<CHTYPE *777777000003* CHARACTER>` (-1 in left half, control-C in
4778 right), which is the standard ITS end-of-file signal. In the Tenex and
4779 Tops-20 versions, the function should return either that or
4780 `<CHTYPE *777777000032* CHARACTER>` (-1 and control-Z), the latter
4781 being their standard end-of-file signal.
4783 For a `"PRINT"` `CHANNEL`, the function must take one argument, which
4784 will be a `CHARACTER`. It can dispose of its argument in any way it
4785 pleases. The value returned by the function is ignored.
4787 Example: `<OPEN "PRINT" "INT:" ,FCN>` opens an internal output
4788 `CHANNEL` with `,FCN` as its character-gobbler.
4790 11.10. The "NET" Device: the ARPA Network
4791 -----------------------------------------
4793 The `"NET"` device is different in many ways from conventional
4794 devices. In the ITS version, it is the only device besides `"INT"`
4795 that does not take all strings as its arguments to `OPEN`, and it must
4796 take an additional optional argument to specify the byte size of the
4797 socket. The format of a call to open a network socket is
4799 <OPEN mode:string local-socket:fix "NET" foreign-host:fix byte-size:fix>
4803 - *mode* is the mode of the desired `CHANNEL`. This must be either
4804 `"READ"`, `"PRINT"`, `"READB"` or `"PRINTB"`.
4805 - *local-socket* is the local socket number. If it is `-1`, the
4806 operating system will generate a unique local socket number. If it
4807 is not, in the Tenex and Tops-20 versions, the socket number is
4809 - *foreign-socket* is the foreign socket number. If it is `-1`, this
4810 is an `OPEN` for "listening".
4811 - *foreign-host* is the foreign host number. If it is an `OPEN` for
4812 listening, this argument is ignored.
4813 - *byte-size* is the optional byte size. For `"READ"` or `"PRINT"`
4814 this must be either `7` (used by default) or `8`. For `"READB"` or
4815 `"PRINTB"`, it can be any integer from `1` to `36` (used by
4818 In the Tenex and Tops-20 versions, `OPEN` can instead be given a
4819 `STRING` argument of the form `"NET:..."`. In this case the local
4820 socket number can be "directory-relative".
4822 Like any other `OPEN`, either a `CHANNEL` or a `FALSE` is returned.
4823 Once open, a network `CHANNEL` can be used like any other `CHANNEL`,
4824 except that `FILE-LENGTH`, `ACCESS`, `RENAME`, etc., cannot be done.
4825 The "argument" first-name, second-name, and directory-name slots in
4826 the `CHANNEL` are used for local socket, foreign socket, and foreign
4827 host (as specified in the call to `OPEN`), respectively. The
4828 corresponding "real" slots are used somewhat differently. If a channel
4829 is `OPEN`ed with local socket `-1`, the "real" first-name slot will
4830 contain the unique socket number generated by the operating system. If
4831 a listening socket is `OPEN`ed, the foreign socket and host numbers of
4832 the answering host are stored in the "real" second-name and
4833 directory-name slots of the `CHANNEL` when the Request For Connection
4836 An interrupt (chapter 21) can be associated with a `"NET"`-device
4837 `CHANNEL`, so that a program will know that the `CHANNEL` has or needs
4838 data, according to its *mode*.
4840 There also exist several special-purpose `SUBR`s for the `"NET"`
4841 device. These are described next.
4843 ### 11.10.1. NETSTATE
4845 <NETSTATE network:channel>
4847 returns a `UVECTOR` of three `FIX`es. The first is the state of the
4848 connection, the second is a code specifying why a connection was
4849 closed, and the last is the number of bits available on the connection
4850 for input. The meaning of the state and close codes are
4851 installation-dependent and so are not included here.
4855 <NETACC network:channel>
4857 accepts a connection to a socket that is open for listening and
4858 returns its argument. It will return a `FALSE` if the connection is in
4863 <NETS network:channel>
4865 returns its argument, after forcing any system-buffered network output
4866 to be sent. ITS normally does this every half second anyway. Tenex and
4867 Tops-20 do not do it unless and until `NETS` is called. `NETS` is
4868 similar to `BUFOUT` for normal `CHANNEL`s, except that even
4869 operating-system buffers are emptied **now**.
4871 Chapter 12. Locatives
4872 =====================
4874 There is in Muddle a facility for obtaining and working directly with
4875 objects which roughly correspond to "pointers" in assembly language or
4876 "lvals" in BCPL or PAL. In Muddle, these are generically known as
4877 **locatives** (from "location") and are of several `TYPE`s, as
4878 mentioned below. Locatives exist to provide efficient means for
4879 altering structures: direct replacement as opposed to re-copying.
4881 Locatives **always** refer to elements in structures. It is not
4882 possible to obtain a locative to something (for example, an `ATOM`)
4883 which is not part of any structured. It is possible to obtain a
4884 locative to any element in any structured object in Muddle -- even to
4885 associations (chapter 13) and to the values of `ATOM`s, structurings
4886 which are normally "hidden".
4888 In the following, the object occupying the structured position to
4889 which you have obtained a locative will be referred to as the object
4890 **pointed to** by the locative.
4892 12.1. Obtaining Locatives
4893 -------------------------
4899 returns a locative (`TYPE` `LOCD`, "locative to iDentifier") to the
4900 `LVAL` of *atom* in *env*. If *atom* is not bound in *env*, an error
4901 occurs. *env* is optional, with the current `ENVIRONMENT` used by
4902 default. The locative returned by `LLOC` is **independent of future
4903 re-bindings** of *atom*. That is, `IN` (see below) of that locative
4904 will return the same thing even if *atom* is re-bound to something
4905 else; `SETLOC` (see below) will affect only that particular binding of
4908 Since bindings are kept on a stack (tra la), any attempt to use a
4909 locative to an `LVAL` which has become unbound will fetch up an error.
4910 (It breaks just like a `TUPLE`....) `LEGAL?` can, once again, be used
4911 to see if a `LOCD` is valid. Caution: `<SET A <LLOC A>>` creates a
4912 self-reference and can make `PRINT` very unhappy.
4918 returns a locative (`TYPE` `LOCD`) to the `GVAL` of *atom*. If *atom*
4919 has no `GVAL` **slot**, an error occurs, unless *pred* (optional) is
4920 given and not `FALSE`, in which case a slot is created (chapter 22).
4921 Caution: `<SETG A <GLOC A>>` creates a self-reference and can make
4922 `PRINT` very unhappy.
4926 <AT structured N:fix-or-offset>
4928 returns a locative to the <em>N</em>th element in *structured*. *N* is
4929 optional, `1` by default. The exact `TYPE` of the locative returned
4930 depends on the `PRIMTYPE` of *structured*: `LOCL` for `LIST`, `LOCV`
4931 for `VECTOR`, `LOCU` for `UVECTOR`, `LOCS` for `STRING`, `LOCB` for
4932 `BYTES`, `LOCT` for `TEMPLATE`, and `LOCA` for `TUPLE`. If *N* is
4933 greater than `<LENGTH structured>` or less than `1`, or an `OFFSET`
4934 with a Pattern that doesn't match *structured*, an error occurs. The
4935 locative is unaffected by applications of `REST`, `BACK`, `TOP`,
4936 `GROW`, etc. to *structured*.
4938 ### 12.1.4. GETPL and GETL
4940 <GETPL item:any indicator:any default:any>
4942 returns a locative (`TYPE` `LOCAS`) to the association of *item* under
4943 *indicator*. (See chapter 13 for information about associations.) If
4944 no such association exists, `GETPL` returns `EVAL` of *default*.
4945 *default* is optional, `#FALSE ()` by default.
4947 `GETPL` corresponds to `GETPROP` amongst the association machinery.
4948 There also exists `GETL`, which corresponds to `GET`, returning either
4949 a `LOCAS` or a locative to the *indicator*th element of a structured
4950 *item*. `GETL` is like `AT` if *item* is a structure and *indicator*
4951 is a `FIX` or `OFFSET`, and like `GETPL` if not.
4956 This `SUBR` is a predicate that tells whether or not is argument is a
4957 locative. It is cheaper than
4958 `<MEMQ <PRIMTYPE arg> '![LOCD LOCL ...]>`.
4960 12.3. Using Locatives
4961 ---------------------
4963 The following two `SUBR`s provide the means for working with
4964 locatives. They are independent of the specific `TYPE` of the
4965 locative. The notation *locative* indicates anything which could be
4966 returned by `LLOC`, `GLOC`, `AT`, `GETPL` or `GETL`.
4972 returns the object to which *locative* points. The only way you can
4973 get an error using `IN` is when *locative* points to an `LVAL` which
4974 has become unbound from an `ATOM`. This is the same as the problem in
4975 referencing `TUPLE`s as mentioned in section 9.2, and it can be
4976 avoided by first testing `<LEGAL? locd>`.
4987 <SETLOC locative any>
4989 returns *any*, after having made *any* the contents of that position
4990 in a structure pointed to by *locative*. The structure itself is not
4991 otherwise disturbed. An error occurs if *locative* is to a
4992 non-`LEGAL?` `LVAL` or if you try to put an object of the wrong `TYPE`
4993 into a `PRIMTYPE` `UVECTOR`, `STRING`, `BYTES`, or `TEMPLATE`.
4999 <SETLOC <AT .A 2> HI>$
5004 12.4. Note on Locatives
5005 -----------------------
5007 You may have noticed that locatives are, strictly speaking,
5008 unnecessary; you can do everything locatives allow by appropriate use
5009 of, for example, `SET`, `LVAL`, `PUT`, `NTH`, etc. What locatives
5010 provide is generality.
5012 Basically, how you obtained a locative is irrelevant to `SETLOC` and
5013 `IN`; thus the same program can play with `GVAL`s, `LVAL`s, object in
5014 explicit structures, etc., without being bothered by what function it
5015 should use to do so. This is particularly true with respect to
5016 locatives to `LVAL`s; the fact that they are independent of changes in
5017 binding can save a lot of fooling around with `EVAL` and
5020 Chapter 13. Association (Properties)
5021 ====================================
5023 There is an "associative" data storage and retrieval system embedded
5024 in Muddle which allows the construction of data structures with
5025 arbitrary selectors. It is used via the `SUBR`s described in this
5028 13.1. Associative Storage
5029 -------------------------
5033 <PUTPROP item:any indicator:any value:any>
5035 ("put property") returns *item*, having associated *value* with *item*
5036 under the indicator *indicator*.
5040 <PUT item:any indicator:any value:any>
5042 is identical to `PUTPROP`, except that, if *item* is structured
5043 **and** *indicator* is of `TYPE` `FIX` or `OFFSET`, it does
5044 `<SETLOC <AT item indicator> value>`. In other words, an element with
5045 an integral selector is stored in the structure itself, instead of in
5046 association space. `PUT` (like `AT`) will get an error if *indicator*
5047 is out of range; `PUTPROP` will not.
5049 ### 13.1.3. Removing Associations
5051 If `PUTPROP` is used **without** its *value* argument, it removes any
5052 association existing between its *item* argument and its *indicator*
5053 argument. If an association did exist, using `PUTPROP` in this way
5054 returns the *value* which was associated. If no association existed,
5055 it returns `#FALSE ()`.
5057 `PUT`, with arguments which refer to association, can be used in the
5060 If either *item* or *indicator* cease to exist (that is, no one was
5061 pointing to them, so they were garbage-collected), and no locatives to
5062 the association exist, then the association between them ceases to
5063 exist (is garbage-collected).
5065 13.2. Associative Retrieval
5066 ---------------------------
5070 <GETPROP item:any indicator:any exp:any>
5072 ("get property") returns the *value* associated with *item* under
5073 *indicator*, if any. If there is no such association, `GETPROP`
5074 returns `EVAL` of *exp* (that is, *exp* gets `EVAL`ed both at call
5077 *exp* is optional. If not given, `GETPROP` returns `#FALSE ()` if it
5078 cannot return a *value*.
5080 Note: *item* and *indicator* in `GETPROP` must be the **same Muddle
5081 objects** used to establish the association; that is, they must be
5082 `==?` to the objects used by `PUTPROP` or `PUT`.
5086 <GET item:any indicator:any exp:any>
5088 is the inverse of `PUT`, using `NTH` or `GETPROP` depending on the
5089 test outlined in section 13.1.2. *exp* is optional and used as in
5092 13.3. Examples of Association
5093 -----------------------------
5097 <PUT .L FOO "L is a list.">$
5101 <PUTPROP .L 3 '![4]>$
5109 <PUT .N .L "list on a zero">$
5111 <GET .N '(1 2 3 4)>$
5114 The last example failed because `READ` generated a new `LIST` -- not
5115 the one which is `L`'s `LVAL`. However,
5120 works because `<==? .N 0>` is true.
5122 To associate something with the Nth **position** in a structure, as
5123 opposed to its Nth **element**, associate it with
5124 `<REST structure N-1>`, as in the following:
5126 <PUT <REST .L 3> PERCENT 0.3>$
5128 <GET <2 .L> PERCENT>$
5130 <GET <REST .L 2> PERCENT>$
5135 <SET N '![A B C ;"third element" D E]>$
5137 <GET <REST .N 2> COMMENT>$
5140 The `'` in the `<SET N ... >` is to keep `EVAL` from generating a new
5141 `UVECTOR` ("Direct Representation"), which would not have the comment
5142 on it (and which would be a needless duplicate). A "top-level" comment
5143 -- one attached to the entire object returned by `READ` -- is `PUT` on
5144 the `CHANNEL` in use, since there is no position in any structure for
5145 it. If no top-level comment follows the object, `READ` removes the
5146 value (`<PUT channel COMMENT>`); so anybody that wants to see a
5147 top-level comment must look for it after each `READ`.
5149 If you need to have a structure with selectors in more than one
5150 dimension (for example, a sparse matrix that does not deserve to be
5151 linearized), associations can be cascaded to achieve the desired
5152 result. In effect an extra level of indirection maps two indicators
5153 into one. For example, to associate *value* with *item* under
5154 *indicator-1* and *indicator-2* simultaneously:
5156 <PUTPROP indicator-1 indicator-2 T>
5157 <PUTPROP item <GETPL indicator-1 indicator-2> value>
5159 13.4. Examining Associations
5160 ----------------------------
5162 Associations (created by `PUT` and `PUTPROP`) are chained together in
5163 a doubly-linked list, internal to Muddle. The order of associations in
5164 the chain is their order of creation, newest first. There are several
5165 `SUBR`s for examining the chain of associations. `ASSOCIATIONS`
5166 returns the first association in the chain, or `#FALSE ()` if there
5167 are none. `NEXT` takes an association as an argument and returns the
5168 next association in the chain, or `#FALSE ()` if there are no more.
5169 `ITEM`, `INDICATOR` and `AVALUE` all take an association as an
5170 argument and return the item, indicator and value, respectively.
5171 Associations print as:
5173 #ASOC (item indicator value)
5175 (sic: only one `S`). Example: the following gathers all the existing
5176 associations into a `LIST`.
5178 <PROG ((A <ASSOCIATIONS>))
5179 <COND (<NOT .A> '())
5181 <FUNCTION () <COND (<SET A <NEXT .A>> .A)
5182 (T <MAPSTOP>)>>>))>>
5184 Chapter 14. Data-type Declarations
5185 ==================================
5187 In Muddle, it is possible to declare the permissible range of "types"
5188 and/or structures that an `ATOM`'s values or a function's arguments or
5189 value may have. This is done using a special `TYPE`, the `DECL`
5190 ("declaration"). A `DECL` is of `PRIMTYPE` `LIST` but has a
5191 complicated internal structure. `DECL`s are used by the interpreter to
5192 find `TYPE` errors in function calling and by the compiler to generate
5193 more efficient code.
5195 There are two kinds of `DECL`s. The first kind of `DECL` is the most
5196 common. It is called the `ATOM` `DECL` and is used most commonly to
5197 specify the type/structure of the `LVAL`s of the `ATOM`s in the
5198 argument `LIST` of a `FUNCTION` or *aux* `LIST` of a `PROG` or
5199 `REPEAT`. This `DECL` has the form:
5201 #DECL (atoms:list Pattern ...)
5203 where the pairing of a `LIST` of `ATOM`s and a "Pattern" can be
5204 repeated indefinitely. This declares the `ATOM`s in a *list* to be of
5205 the type/structure specified in the following *Pattern*. The special
5206 `ATOM` `VALUE`, if it appears, declares the result of a `FUNCTION`
5207 call or `PROG` or `REPEAT` evaluation to satisfy the Pattern
5208 specified. An `ATOM` `DECL` is useful in only one place: immediately
5209 following the argument `LIST` of a `FUNCTION`, `PROG`, or `REPEAT`. It
5210 normally includes `ATOM`s in the argument `LIST` and `ATOM`s whose
5211 `LVAL`s are otherwise used in the Function body.
5213 The second kind of `DECL` is rarely seen by the casual Muddle user,
5214 except in appendix 2. It is called the `RSUBR` `DECL`. It is used to
5215 specify the type/structure of the arguments and result of an `RSUBR`
5216 or `RSUBR-ENTRY` (chapter 19). It is of the following form:
5218 #DECL ("VALUE" Pattern Pattern ...)
5220 where the `STRING` `"VALUE"` precedes the specification of the
5221 type/structure of the value of the call to the `RSUBR`, and the
5222 remaining *Patterns* specify the arguments to the `RSUBR` in order.
5223 The full specification of the `RSUBR` `DECL` will be given in section
5224 14.9. The `RSUBR` `DECL` is useful in only one place: as an element of
5225 an `RSUBR` or `RSUBR-ENTRY`.
5230 The simplest possible Pattern is to say that a value is exactly some
5231 other object, by giving that object, `QUOTE`d. For example, to declare
5232 that a variable is a particular `ATOM`:
5236 declares that `.X` is always the `ATOM` `T`. When variables are
5237 `DECL`ed as "being" some other object in this way, the test used is
5238 `=?`, not `==?`. The distinction is usually not important, since
5239 `ATOM`s, which are most commonly used in this construction, are `==?`
5240 to each other is `=?` anyway.
5242 It is more common to want to specify that a value must be of a given
5243 `TYPE`. This is done with the simplest non-specific Pattern, a `TYPE`
5246 #DECL ((X) FIX (Y) FLOAT)
5248 declares `.X` to be of `TYPE` `FIX`, and `.Y` of `TYPE` `FLOAT`. In
5249 addition to the names of all of the built-in and created `TYPE`s, such
5250 as `FIX`, `FLOAT` and `LIST`, a few "compound" type names are allowed:
5252 - `ANY` allows any `TYPE`.
5253 - `STRUCTURED` allows any structured `TYPE`, such as `LIST`,
5254 `VECTOR`, `FALSE`, `CHANNEL`, etc. (appendix 3).
5255 - `LOCATIVE` allows any locative `TYPE`, such as are returned by
5256 `LLOC`, `GLOC`, `AT`, and so on (chapter 12).
5257 - `APPLICABLE` allows any applicable `TYPE`, such as `FUNCTION`,
5258 `SUBR`, `FIX` (!), etc. (appendix 3).
5259 - Any other `ATOM` can be used to stand for a more complex
5260 construct, if an association is established on that `ATOM` and the
5261 `ATOM` `DECL`. A common example is to
5262 `<PUT NUMBER DECL '<OR FIX FLOAT>>` (see below), so that `NUMBER`
5263 can be used as a "compound type name".
5265 The single `TYPE` name can be generalized slightly, allowing anything
5266 of a given `PRIMTYPE`, using the following construction:
5268 #DECL ((X) <PRIMTYPE WORD> (Y) <PRIMTYPE LIST>)
5270 This construction consists of a two-element `FORM`, where the first
5271 element is the `ATOM` `PRIMTYPE`, and the second the name of a
5274 The next step is to specify the elements of a structure. This is done
5275 in the simplest way as follows:
5277 < structured:type Pattern Pattern ...>
5279 where there is a one-to-one correspondence between the *Pattern* and
5280 the elements of the structure. For example:
5282 #DECL ((X) <VECTOR FIX FLOAT>)
5284 declares `.X` to be a `VECTOR` having **at least** two elements, the
5285 first of which is a `FIX` and the second a `FLOAT`. It is often
5286 convenient to allow additional elements, so that only the elements
5287 being used in the local neighborhood of the `DECL` need to be
5288 declared. To disallow additional elements, a `SEGMENT` is used instead
5289 of a `FORM` (the "excl-ed" brackets make it look more emphatic). For
5292 #DECL ((X) !<VECTOR FIX FLOAT>)
5294 declares `.X` to be a `VECTOR` having **exactly** two elements, the
5295 first of which is a `FIX` and the second a `FLOAT`. Note that the
5296 *Patterns* given for elements can be any legal Pattern:
5298 #DECL ((X) <VECTOR <VECTOR FIX FLOAT>> (Y) <<PRIMTYPE LIST> LIST>)
5300 declares `.X` to be a `VECTOR` containing another `VECTOR` of at least
5301 two elements, and `.Y` to be of `PRIMTYPE LIST`, containing a `LIST`.
5302 In the case of a `BYTES`, the individual elements cannot be declared
5303 (they must be `FIX`es anyway), only the size and number of the bytes:
5305 #DECL ((B) <BYTES 7 3>)
5307 declares `.B` to be a `BYTES` with `BYTE-SIZE` 7 and at least three
5310 It is possible to say that some number of elements of a structure
5311 satisfy a given Pattern (or sequence of Patterns). This is called an
5312 "`NTH` construction".
5314 [ number:fix Pattern Pattern ... ]
5316 states that the sequence of *Patterns* which is `REST` of the `VECTOR`
5317 is repeated the *number* of times given. For example:
5319 #DECL ((X) <VECTOR [3 FIX] FLOAT> (Y) <LIST [3 FIX FLOAT]>)
5321 `.X` is declared to contain three `FIX`es and a `FLOAT`, perhaps
5322 followed by other elements. `.Y` is declared to repeat the sequence
5323 `FIX`-`FLOAT` three times. Note that there may be more repetitions of
5324 the sequence in `.Y` (but not in `.X`): the `DECL` specifies only the
5327 For indefinite repetition, the same construction is used, but, instead
5328 of the number of repetitions of the sequence of Patterns, the `ATOM`
5329 `REST` is given. This allows any number of repetitions, from zero on
5332 #DECL ((X) <VECTOR [REST FIX]> (Y) <LIST [3 FIX] [REST FIX]>)
5334 A "`REST` construction" can contain any number of Patterns, just like
5335 an `NTH` construction:
5337 #DECL ((X) <VECTOR [REST FIX FLOAT LIST]>)
5339 declares that `.X` is a `VECTOR` wherein the sequence
5340 `FIX`-`FLOAT`-`LIST` repeats indefinitely. It does not declare that
5341 `<LENGTH .X>` is an even multiple of three: the `VECTOR` can end at
5344 A variation on `REST` is `OPT` (or `OPTIONAL`), which is similar to
5345 `REST` except that the construction is scanned once at most instead of
5346 indefinitely, and further undeclared elements can follow. For example:
5348 #DECL ((X) <VECTOR [OPT FIX]>)
5350 declares that `.X` is a `VECTOR` which is empty or whose first element
5351 is a `FIX`. Only a `REST` construction can follow an "`OPT`
5354 Note that the `REST` construction must always be the last element of
5355 the structure declaration, since it gives a Pattern for the rest of
5356 the structure. Thus, the `REST` construction is different from all
5357 others in that it has an unlimited range. No matter how many times the
5358 Pattern it gives is `REST`ed off of the structure, the remainder of
5359 the structure still has that Pattern.
5361 This exhausts the possible single Patterns that can be given in a
5362 declaration. However, there is also a compound Pattern defined. It
5363 allows specification of several possible Patterns for one value:
5365 <OR Pattern Pattern ... >
5367 Any non-compound Pattern can be included as one of the elements of the
5368 compound Pattern. Finally, compound Patterns can be used as Patterns
5369 for elements of structures, and so on.
5371 #DECL ((X) <OR FIX FLOAT>
5372 (Y) <OR FIX <UVECTOR [REST <OR FIX FLOAT>]>>)
5374 The `OR` construction can be extended to any level of ridiculousness,
5375 but the higher the level of complexity and compoundedness the less
5376 likely the compiler will find the `DECL` useful.
5378 At the highest level, any Pattern at top level in an `ATOM` `DECL` can
5379 be enclosed in the construction
5381 < specialty:atom Pattern >
5383 which explicitly declares the specialty of the `ATOM`(s) in the
5384 preceding `LIST`. *specialty* can be either `SPECIAL` or `UNSPECIAL`.
5385 Specialty is important only when the program is to be compiled. The
5386 word comes from the control stack, which is called "special" in Lisp
5387 (Moon, 1974) because the garbage collector finds objects on it and
5388 modifies their internal pointers when storage is compacted. (An
5389 internal stack is used within the interpreter and is not accessible to
5390 programs -- section 22.1) In an interpreted program all local values
5391 are inherently `SPECIAL`, because all bindings are put on the control
5392 stack (but see `SPECIAL-MODE` below). When the program is compiled,
5393 only values declared `SPECIAL` (which may or may not be the
5394 declaration used by default) remain in bindings on the control stack.
5395 All others are taken care of simply by storing objects on the control
5396 stack: the `ATOM`s involved are not needed and are not created on
5397 loading. So, a program that `SET`s an `ATOM`'s local value for another
5398 program to pick up must declare that `ATOM` to be `SPECIAL`. If it
5399 doesn't, the `ATOM`'s binding will go away during compiling, and the
5400 program that needs to refer to the `ATOM` will either get a no-value
5401 error or refer to an erroneous binding. Usually only `ATOM`s which
5402 have the opposite specialty from that of the current `SPECIAL-MODE`
5403 are explicitly declared. The usual `SPECIAL-MODE` is `UNSPECIAL`, so
5404 typically only `SPECIAL` declarations use this construction:
5406 #DECL ((ACT)) <SPECIAL ACTIVATION>)
5408 explicitly declares `ACT` to be `SPECIAL`.
5410 Most well-written, modular programs get all their information from
5411 their arguments and from `GVAL`s, and thus they rarely use `SPECIAL`
5412 `ATOM`s, except perhaps for `ACTIVATION`s and the `ATOM`s whose
5413 `LVAL`s Muddle uses by default: `INCHAN`, `OUTCHAN`, `OBLIST`, `DEV`,
5414 `SNM`, `NM1`, `NM2`. `OUTCHAN` is a special case: the compiler thinks
5415 that all conversion-output `SUBR`s are called with an explicit
5416 `CHANNEL` argument, whether or not the program being compiled thinks
5417 so. For example, `<CRLF>` is compiled as though it were
5418 `<CRLF .OUTCHAN>`. So you may use (or see) the binding
5419 `(OUTCHAN .OUTCHAN)` in an argument `LIST`, however odd that may
5420 appear, because that -- coupled with the usual `UNSPECIAL` declaration
5421 by default -- makes only one reference to the current binding of
5422 `OUTCHAN` and stuffs the result in a slot on the stack for use within
5428 #DECL ((Q) <OR VECTOR CHANNEL>)
5430 declares .Q to be either a `VECTOR` or a `CHANNEL`.
5432 #DECL ((P Q R S) <PRIMTYPE LIST>)
5434 declares `.P`, `.Q`, `.R`, and `.S` all to be of `PRIMTYPE` `LIST`.
5436 #DECL ((F) <FORM [3 ANY]>)
5438 declares `.F` to be a `FORM` whose length is at least three,
5439 containing objects of any old `TYPE`.
5441 #DECL ((LL) <<PRIMTYPE LIST> [4 <LIST [REST FIX]>]>)
5443 declares `.LL` to be of `PRIMTYPE` `LIST`, and to have at least four
5444 elements, each of which are `LIST`s of unspecified length (possibly
5445 empty) containing `FIX`es.
5447 #DECL ((VV) <VECTOR FIX ATOM CHARACTER>)
5449 declares `.VV` to be a `VECTOR` with at least three elements. Those
5450 elements are, in order, of `TYPE` `FIX`, `ATOM`, and `CHARACTER`.
5452 #DECL ((EH) <LIST ATOM [REST FLOAT]>)
5454 declares `.EH` to be a `LIST` whose first element is an `ATOM` and the
5455 rest of whose elements are `FLOAT`s. It also says that `.EH` is at
5456 least one element long.
5458 #DECL ((FOO) <LIST [REST 'T FIX]>)
5460 declares `.FOO` to be a `LIST` whose odd-positioned elements are the
5461 `ATOM` `T` and whose even-positioned elements are `FIX`es.
5465 #DECL ((X) <VECTOR [1 FIX]>)
5469 declares `.X` to be a `VECTOR` containing at least one `FIX`. The more
5470 restrictive `[REST FIX]` would take excessive checking time by the
5471 interpreter, because the `REST` of the `VECTOR` would be checked on
5472 each iteration of the `MAPR`. In this case both `DECL`s are equally
5473 powerful, because checking the first element of all the `REST`s of a
5474 structure eventually checks all the elements. Also, since the
5475 `FUNCTION` refers only to the first element of `X`, this is as much
5476 declaration as the compiler can effectively use. (If this `VECTOR`
5477 always contains only `FIX`es, it should be a `UVECTOR` instead, for
5478 space efficiency. Then a `[REST FIX]` `DECL` would make the
5479 interpreter check only the `UTYPE`. If the `FIX`es cover a small
5480 non-negative range, then a `BYTES` might be even better, with a `DECL`
5484 #DECL ((N) <UNSPECIAL FIX>)
5485 <COND (<0? .N> 1) (ELSE <* .N <FACT <- .N 1>>>)>>
5487 declares `.N` to be of `TYPE` `FIX` and `UNSPECIAL`. This specialty
5488 declaration ensures that, independent of `SPECIAL-MODE` during
5489 compiling, `.N` gets compiled into a fast control-stack reference.
5492 #DECL ((L VALUE) <UNSPECIAL <LIST [REST FIX]>>
5493 (N <UNSPECIAL FIX>))
5494 <COND (<0? .N> <RETURN .L>)>
5495 <SET L (<+ .N <1 .L>> !.L)>
5498 The above declares `L` and `N` to be `UNSPECIAL`, says that `.N` is a
5499 `FIX`, and says that `.L`, along with the value returned, is a `LIST`
5500 of any length composed entirely of `FIX`es.
5502 14.3. The DECL Syntax
5503 ---------------------
5505 This section gives quasi-BNF productions for the Muddle `DECL` syntax.
5506 In the following table Muddle type-specifiers are distinguished *in
5509 decl ::= #DECL (declprs)
5511 declprs ::= (atlist) pattern | declprs declprs
5513 atlist ::= atom | atom atlist
5515 pattern ::= pat | <UNSPECIAL pat> | <SPECIAL pat>
5517 pat ::= unit | <OR unit ... unit>
5519 unit ::= type | <PRIMTYPE type> | atom | 'any
5520 | ANY | STRUCTURED | LOCATIVE |APPLICABLE
5521 | <struc elts> | <<OR struc ... struc> elts>
5522 | !<struc elts> | !<<OR struc ... struc> elts>
5523 | <bstruc fix> | <bstruc fix fix>
5526 struc ::= structured-type | <PRIMTYPE structured-type>
5528 bstruc ::= BYTES | <PRIMTYPE BYTES>
5530 elts ::= pat | pat elts
5532 | [fix pat ... pat] elts
5533 | [opt pat ... pat] | [REST pat ... pat]
5534 | [opt pat ... pat] [REST pat ... pat]
5536 opt ::= OPT | OPTIONAL
5541 There are some rules of thumb concerning "good" `DECL`s. A "good"
5542 `DECL` is one that is minimally offensive to the `DECL`-checking
5543 mechanism as the compiler, but that gives the maximum amount of
5544 information. It is simple to state what gives offense to the compiler
5545 and `DECL`-checking mechanism: complexity. For example, a large
5546 compound `DECL` like:
5548 #DECL ((X) <OR FIX LIST UVECTOR FALSE>)
5550 is a `DECL` that the compiler will find totally useless. It might as
5551 well be `ANY`. The more involved the `OR`, the less information the
5552 compiler will find useful in it. For example, if the function takes
5553 `<OR LIST VECTOR UVECTOR>`, maybe you should really say `STRUCTURED`.
5554 Also, a very general `DECL` indicates a very general program, which is
5555 not likely to be efficient when compiled (of course there is a
5556 trade-off here). Narrowing the `DECL` to one `PRIMTYPE` gives a great
5557 gain in compiled efficiency, to one `TYPE` still more.
5559 Another situation to be avoided is the ordinary large `DECL`, even if
5560 it is perfectly straightforward. If you have created a structure which
5561 has a very specific `DECL` and is used all over your code, it might be
5562 better as a `NEWTYPE` (see below). The advantage of a `NEWTYPE` over a
5563 large explicit `DECL` is twofold. First, the entire structure must be
5564 checked only when it is created, that is, `CHTYPE`d from its
5565 `PRIMTYPE`. As a full `DECL`, it is checked completely on entering
5566 each function and on each reassignment of `ATOM`s `DECL`ed to be it.
5567 Second, the amount of storage saved in the `DECL`s of `FUNCTION`s and
5568 so on is large, not to mention the effort of typing in and keeping up
5569 to date several instances of the full `DECL`.
5574 ### 15.4.1. GDECL and MANIFEST
5576 There are two ways to declare `GVAL`s for the `DECL`-checking
5577 mechanism. These are through the `FSUBR` `GDECL` ("global
5578 declaration") and the `SUBR` `MANIFEST`.
5580 <GDECL atoms:list Pattern ...>
5582 `GDECL` allows the type/structure of global values to be declared in
5583 much the same way as local values. Example:
5585 <GDECL (X) FIX (Y) <LIST FIX>>
5587 declares `,X` to be a `FIX`, and `,Y` to be a `LIST` containing at
5590 <MANIFEST atom atom ...>
5592 `MANIFEST` takes as arguments `ATOM`s whose `GVAL`s are declared to be
5593 constants. It is used most commonly to indicate that certain `ATOM`s
5594 are the names of offsets in structures. For example:
5599 allows the compiler to confidently open-compile applications of `X`
5600 (getting the first element of a structure), knowing that `,X` will not
5601 change. Any sort of object can be a `MANIFEST` value: if it does not
5602 get embedded in the compiled code, it is included in the `RSUBR`'s
5603 "reference vector", for fast access. However, as a general rule,
5604 structured objects should not be made `MANIFEST`: the `SETG` will
5605 instead refer to a **distinct** copy of the object in **each** `RSUBR`
5606 that does a `GVAL`. A structured object should instead be `GDECL`ed.
5608 An attempt to `SETG` a `MANIFEST` atom will cause an error, unless
5611 1. the `ATOM` was previously globally unassigned;
5612 2. the old value is `==?` to the new value; or
5613 3. `.REDEFINE` is not `FALSE`.
5615 ### 14.5.2. MANIFEST? and UNMANIFEST
5619 returns `T` if *atom* is `MANIFEST`, `#FALSE ()` otherwise.
5621 <UNMANIFEST atom atom ...>
5623 removes the `MANIFEST` of the global value of each of its arguments so
5624 that the value can be changed.
5630 ("globally bound") returns `T` if *atom* has a global value slot (that
5631 is, if it has ever been `SETG`ed, `MANIFEST`, `GDECL`ed, or `GLOC`ed
5632 (chapter 12) with a true second argument), `#FALSE ()` otherwise.
5634 14.6. NEWTYPE (again)
5635 ---------------------
5637 `NEWTYPE` gives the programmer another way to `DECL` objects. The
5638 third (and optional) argument of `NEWTYPE` is a `QUOTE`d Pattern. If
5639 given, it will be saved as the value of an association (chapter 13)
5640 using the name of the `NEWTYPE` as the item and the `ATOM` `DECL` as
5641 the indicator, and it will be used to check any object that is about
5642 to be `CHTYPE`d to the `NEWTYPE`. For example:
5644 <NEWTYPE COMPLEX-NUMBER VECTOR '<<PRIMTYPE VECTOR> FLOAT FLOAT>>
5646 creates a new `TYPE`, with its first two elements declared to be
5647 `FLOAT`s. If later someone types:
5649 #COMPLEX-NUMBER [1.0 2]
5651 an error will result (the second element is not a `FLOAT`). The
5652 Pattern can be replaced by doing another `NEWTYPE` for the same
5653 `TYPE`, or by putting a new value in the association. Further
5656 <NEWTYPE FOO LIST '<<PRIMTYPE LIST> FIX FLOAT [REST ATOM]>>
5658 causes `FOO`s to contain a `FIX` and a `FLOAT` and any number of
5663 <SET A #BAR (#BAR () 1 1.2 GRITCH)>
5665 <NEWTYPE BAR LIST '<<PRIMTYPE LIST> BAR [REST FIX FLOAT ATOM]>>
5667 This is an example of a recursively `DECL`ed `TYPE`. Note that
5668 `<1 .A>` does not satisfy the `DECL`, because it is empty, but it was
5669 `CHTYPE`d before the `DECL` was associated with `BAR`. Now, even
5670 `<CHTYPE <1 .A> <TYPE <1 .A>>>` will cause an error.
5672 In each of these examples, the `<<PRIMTYPE ...> ...>` construction was
5673 used, in order to permit `CHTYPE`ing an object into itself. See what
5676 <NEWTYPE OOPS LIST '<LIST ATOM FLOAT>>$
5678 <SET A <CHTYPE (E 2.71828) OOPS>>$
5681 Now `<CHTYPE .A OOPS>` will cause an error. Unfortunately, you must
5683 <CHTYPE <CHTYPE .A LIST> OOPS>$
5686 14.7. Controlling DECL Checking
5687 -------------------------------
5689 There are several `SUBR`s and `FSUBR`s in Muddle that are used to
5690 control and interact with the `DECL`-checking mechanism.
5692 ### 14.7.1. DECL-CHECK
5694 This entire complex checking mechanism can get in the way during
5695 debugging. As a result, the most commonly used `DECL`-oriented `SUBR`
5696 is `DECL-CHECK`. It is used to enable and disable the entire
5697 `DECL`-checking mechanism.
5699 <DECL-CHECK false-or-any>
5701 If its single argument is non-`FALSE`, `DECL` checking is turned on;
5702 if it is `FALSE`, `DECL` checking is turned off. The previous state is
5703 returned as a value. If no argument is given, `DECL-CHECK` returns the
5704 current state. In an initial Muddle `DECL` checking is on.
5706 When `DECL` checking is on, the `DECL` of an `ATOM` is checked each
5707 time it is `SET`, the arguments and results of calls to `FUNCTION`s,
5708 `RSUBR`s, and `RSUBR-ENTRY`s are checked, and the values returned by
5709 `PROG` and `REPEAT` are checked. The same is done for `SETG`s and, in
5710 particular, attempts to change `MANIFEST` global values. Attempts to
5711 `CHTYPE` an object to a `NEWTYPE` (if the `NEWTYPE` has the optional
5712 `DECL`) are also checked. When `DECL` checking is off, none of these
5713 checks is performed.
5715 ### 14.7.2. SPECIAL-CHECK and SPECIAL-MODE
5717 <SPECIAL-CHECK false-or-any>
5719 controls whether or not `SPECIAL` checking is performed at run time by
5720 the interpreter. It is initially off. Failure to declare an `ATOM` to
5721 be `SPECIAL` when it should be will produce buggy compiled code.
5723 <SPECIAL-MODE specialty:atom>
5725 sets the declaration used by default (for `ATOM`s not declared either
5726 way) and returns the previous such declaration, or the current such
5727 declaration if no argument is given. The initial declaration used by
5728 default is `UNSPECIAL`.
5730 ### 14.7.3. GET-DECL and PUT-DECL
5732 `GET-DECL` and `PUT-DECL` are used to examine and change the current
5733 `DECL` (of either the global or the local value) of an `ATOM`.
5737 returns the `DECL` Pattern (if any, otherwise `#FALSE ()`) associated
5738 with the global or local value slot of an `ATOM`. For example:
5741 #DECL ((X) <OR FIX FLOAT>)
5746 would return `<OR FIX FLOAT>` as the result of the application of
5747 `GET-DECL`. Note that because of the use of `LLOC` (or `GLOC`, for
5748 global values) the `ATOM` being examined must be bound; otherwise you
5749 will get an error! This can be gotten around by testing first with
5750 `BOUND?` (or `GBOUND?`, or by giving `GLOC` a second argument which is
5753 If the slot being examined is the global slot and the value is
5754 `MANIFEST`, then the `ATOM` `MANIFEST` is returned. If the value being
5755 examined is not `DECL`ed, `#FALSE ()` is returned.
5757 <PUT-DECL locd Pattern>
5759 makes *Pattern* be the `DECL` for the value and returns *locd*. If
5760 `<DECL-CHECK>` is true, the current value must satisfy the new
5761 Pattern. `PUT-DECL` is normally used in debugging, to change the
5762 `DECL` of an object to correspond to changes in the program. Note that
5763 it is not legal to `PUT-DECL` a "Pattern" of `MANIFEST` or
5770 specifically checks *any* against *Pattern*. For example:
5772 <DECL? '[1 2 3] '<VECTOR [REST FIX]>>$
5774 <DECL? '[1 2.0 3.0] '<VECTOR [REST FIX]>>$
5780 An `OFFSET` is essentially a `FIX` with a Pattern attached, considered
5781 as an `APPLICABLE` rather than a number. An `OFFSET` allows a program
5782 to specify the type of structure that its `FIX` applies to. `OFFSET`s,
5783 like `DECL`s -- if used properly -- can make debugging considerably
5784 easier; they will eventually also help the compiler generate more
5787 The `SUBR` `OFFSET` takes two arguments, a `FIX` and a Pattern, and
5788 returns an object of `TYPE` and `PRIMTYPE` `OFFSET`. An `OFFSET`, like
5789 a `FIX`, may be given as an argument to `NTH` or `PUT` and may be
5790 applied to arguments. The only difference is that the `STRUCTURED`
5791 argument must match the Pattern contained in the `OFFSET`, or an error
5794 <SETG FOO <OFFSET 1 '<CHANNEL FIX>>>$
5795 %<OFFSET 1 '<CHANNEL FIX>>
5802 LISTENING-AT-LEVEL 2 PROCESS 1
5804 Note: when the compiler gets around to understanding `OFFSET`s, it
5805 will not do the right thing with them unless they are `MANIFEST`.
5806 Since there's no good reason not to `MANIFEST` them, this isn't a
5809 The `SUBR` `INDEX`, given an `OFFSET`, returns its `FIX`:
5814 `GET-DECL` of an `OFFSET` returns the associated Pattern; `PUT-DECL`
5815 of an `OFFSET` and a Pattern returns a new `OFFSET` with the same
5816 `INDEX` as the argument, but with a new Pattern:
5820 <PUT-DECL ,FOO OBLIST>$
5823 %<OFFSET 1 '<CHANNEL FIX>>
5825 An `OFFSET` is not a structured object, as this example should make
5828 14.9. The RSUBR DECL
5829 --------------------
5831 The `RSUBR` `DECL` is similar to the `ATOM` `DECL`, except that the
5832 declarations are of argument positions and value rather than of
5833 specific `ATOM`s. Patterns can be preceded by `STRING`s which further
5834 describe the argument (or value).
5836 The simplest `RSUBR` `DECL` is for an `RSUBR` or `RSUBR-ENTRY`
5837 (chapter 19) which has all of its arguments evaluated and returns a
5838 `DECL`ed value. For example:
5840 #DECL ("VALUE" FIX FIX FLOAT)
5842 declares that there are two arguments, a `FIX` and a `FLOAT`, and a
5843 result which is a `FIX`. While the `STRING` `"VALUE"` is not
5844 constrained to appear at the front of the `DECL`, it does appear there
5845 by custom. It need not appear at all, if the result is not to be
5846 declared, but (again by custom) in this case it is usually declared
5849 If any arguments are optional, the `STRING` `"OPTIONAL"` (or `"OPT"`)
5850 is placed before the Pattern for the first optional argument:
5852 #DECL ("VALUE" FIX FIX "OPTIONAL" FLOAT)
5854 If any of the arguments is not to be evaluated, it is preceded by the
5857 #DECL ("VALUE" FIX "QUOTE" FORM)
5859 declares one argument, which is not `EVAL`ed.
5861 If the arguments are to be evaluated and gathered into a `TUPLE`, the
5862 Pattern for it is preceded by the `STRING` `"TUPLE"`:
5864 #DECL ("VALUE" FIX "TUPLE" <TUPLE [REST FIX]>)
5866 If the arguments are to be unevaluated and gathered into a `LIST`, or
5867 if the calling `FORM` is the only "argument", the Pattern is preceded
5868 by the appropriate `STRING`:
5870 #DECL ("VALUE" FIX "ARGS" LIST)
5872 #DECL ("VALUE" FIX "CALL" <PRIMTYPE LIST>)
5874 In every case the special indicator `STRING` is followed by a Pattern
5875 which describes the argument, even though it may sometimes produce
5876 fairly ludicrous results, since the pattern for `"TUPLE"` always must
5877 be a `TUPLE`; for `"ARGS"`, a `LIST`; and for `"CALL"`, a `FORM` or
5880 Chapter 15. Lexical Blocking
5881 ============================
5883 Lexical, or static, blocking is another means of preventing identifier
5884 collisions in Muddle. (The first was dynamic blocking -- binding and
5885 `ENVIRONMENT`s.) By using a subset of the Muddle lexical blocking
5886 facilities, the "block structure" of such languages as Algol, PL/I,
5887 SAIL, etc., can be simulated, should you wish to do so.
5889 15.1. Basic Considerations
5890 --------------------------
5892 Since what follows appears to be rather complex, a short discussion of
5893 the basic problem lexical blocking solves and Muddle's basic solution
5894 will be given first.
5896 `ATOM`s are identifiers. It is thus essential that whenever you type
5897 an `ATOM`, `READ` should respond with the unique identifier you wish
5898 to designate. The problem is that it is unreasonable to expect the
5899 `PNAME`s of all `ATOM`s to be unique. When you use an `ATOM` `A` in a
5900 program, do you mean the `A` you typed two minutes ago, the `A` you
5901 used in another one of your programs, or the `A` used by some library
5904 Dynamic blocking (pushing down of `LVAL`s) solves many such problems.
5905 However, there are some which it does not solve -- such as state
5906 variables (whether they are impure or pure). Major problems with a
5907 system having only dynamic blocking usually arise only when attempts
5908 are made to share large numbers of significant programs among many
5911 The solution used in Muddle is basically as follows: `READ` must
5912 maintain at least one table of `ATOM`s to guarantee any uniqueness.
5913 So, Muddle allows many such tables and makes it easy for the user to
5914 specify which one is wanted. Such a table is an object of `TYPE`
5915 `OBLIST` ("object list"). All the complication which follows arises
5916 out of a desire to provide a powerful, easily used method of working
5917 with `OBLIST`s, with reasonable values used by default.
5922 An `OBLIST` is of `PRIMTYPE` `UVECTOR` with `UTYPE` `LIST`; the `LIST`
5923 holds `ATOM`s. The `ATOM`s are ordered by a hash coding on their
5924 `PNAME`s: each `LIST` is a hashing bucket.) What follows is
5925 information about `OBLIST`s as such.
5927 ### 15.2.1. OBLIST Names
5929 Every normally constituted `OBLIST` has a name. The name of an
5930 `OBLIST` is an `ATOM` associated with the `OBLIST` under the indicator
5933 <GETPROP oblist OBLIST>
5939 returns the name of *oblist*.
5941 Similarly, every name of an `OBLIST` is associated with its `OBLIST`,
5942 again under the indicator `OBLIST`, so that
5944 <GETPROP oblist-name:atom OBLIST>
5948 <GET oblist-name:atom OBLIST>
5950 returns the `OBLIST` whose name is *oblist-name*.
5952 Since there is nothing special about the association of `OBLIST`s and
5953 their names, the name of an `OBLIST` can be changed by the use of
5954 `PUTPROP`, both on the `OBLIST` and its name. It is not wise to change
5955 the `OBLIST` association without changing the name association, since
5956 you are likely to confuse `READ` and `PRINT` terribly.
5958 You can also use `PUT` or `PUTPROP` to remove the association between
5959 an `OBLIST` and its name completely. If you want the `OBLIST` to go
5960 away (be garbage collected), **and** you want to keep its name around,
5961 this must be done: otherwise the association will force it to stay,
5962 even if there are no other references to it. (If you have no
5963 references to either the name or the `OBLIST` (an `ATOM` -- including
5964 a `TYPE` name -- points to its `OBLIST`), both of them -- and their
5965 association -- will go away without your having to remove the
5966 association, of course.) It is not recommended that you remove the
5967 name of an `OBLIST` without having it go away, since then `ATOM`s in
5968 that `OBLIST` will `PRINT` the name as if they were in no `OBLIST` --
5969 which is defeating the purpose of this whole exercise.
5975 ("make oblist") creates and returns a new `OBLIST`, containing no
5976 `ATOM`s, whose name is *atom*, unless there already exists an `OBLIST`
5977 of that name, in which case it returns the existing `OBLIST`. *fix* is
5978 the size of the `OBLIST` created -- the number of hashing buckets.
5979 *fix* is optional (ignored if the `OBLIST` already exists), 13 by
5980 default. If specified, *fix* should be a prime number, since that
5981 allows the hashing to work better.
5987 returns `#FALSE ()` if *atom* is not in any `OBLIST`. If *atom* is in
5988 an `OBLIST`, it returns that `OBLIST`.
5990 15.3. READ and OBLISTs
5991 ----------------------
5993 `READ` can be explicitly told to look up an `ATOM` in a particular
5994 `OBLIST` by giving the `ATOM` a **trailer**. A trailer consists of the
5995 characters `!-` (exclamation-point dash) following the `ATOM`,
5996 immediately followed by the name of the `OBLIST`. For example,
6000 specifies the unique `ATOM` of `PNAME` `A` which is in the `OBLIST`
6001 whose name is the `ATOM` `OB`.
6003 Note that the name of the `OBLIST` must follow the `!-` with **no**
6004 separators (like space, tab, carriage-return, etc.). There is a name
6005 used by default (section 15.5) which types out and is typed in as
6008 Trailers can be used recursively:
6012 specified the unique `ATOM` of `PNAME` `B` which is in the `OBLIST`
6013 whose name is the unique `ATOM` of `PNAME` `A` which is in the
6014 `OBLIST` whose name is `OB`. (Whew!) The repetition is terminated by
6015 the look-up and insertion described below.
6017 If an `ATOM` with a given `PNAME` is not found in the `OBLIST`
6018 specified by a trailer, a new `ATOM` with that `PNAME` is created and
6019 inserted into that `OBLIST`.
6021 If an `OBLIST` whose name is given in a trailer does not exist, `READ`
6022 creates one, of length 13 buckets.
6024 If trailer notation is not used (the "normal" case), and for an `ATOM`
6025 that terminates a trailer, `READ` looks up the `PNAME` of the `ATOM`
6026 in a `LIST` of `OBLIST`s, the `LVAL` of the `ATOM` `OBLIST` by
6027 default. This look-up starts with `<1 .OBLIST>` and continues until
6028 `.OBLIST` is exhausted. If the `ATOM` is not found. `READ` usually
6029 inserts it into `<1 .OBLIST>`. (It is possible to force `READ` to use
6030 a different element of the `LIST` of `OBLIST`s for new insertions. If
6031 the `ATOM` `DEFAULT` is in that `LIST`, the `OBLIST` following that
6032 `ATOM` will be used.)
6034 15.4. PRIN1 and OBLISTs
6035 -----------------------
6037 When `PRINT` is given an `ATOM` to output, it outputs as little of the
6038 trailer as is necessary to specify the `ATOM` uniquely to `READ`. That
6039 is, if the `ATOM` is the **first** `ATOM` of that `PNAME` which `READ`
6040 would find in its normal look-up in the current `.OBLIST`, no trailer
6041 is output. Otherwise, `!-` is output and the name of the `OBLIST` is
6042 recursively `PRIN1`ed.
6044 Warning: there are obscure cases, which do not occur in normal
6045 practice, for which the `PRINT` trailer does not terminate. For
6046 instance, if an `ATOM` must have a trailer printed, and the name of
6047 the `OBLIST` is an `ATOM` in that very same `OBLIST`, death. Any
6048 similar case will also give `PRINT` a hernia.
6053 In an initial Muddle, `.OBLIST` contains two `OBLIST`s. `<1 .OBLIST>`
6054 initially contains no `ATOM`s, and `<2 .OBLIST>` contains all the
6055 `ATOM`s whose `GVAL` are `SUBR`s or `FSUBR`s, as well as `OBLIST`,
6056 `DEFAULT`, `T`, etc. It is difficult to lose track of the latter; the
6057 specific trailer `!-`*separator* will **always** cause references to
6058 that `OBLIST`. In addition, the `SUBR` `ROOT`, which takes no
6059 arguments, always returns that `OBLIST`.
6061 The name of `<ROOT>` is `ROOT`; this `ATOM` is in `<ROOT>` and would
6062 cause infinite recursion were it not for the use of `!-`*separator*.
6063 The name of the initial `<1 .OBLIST>` is `INITIAL` (really
6066 The `ATOM` `OBLIST` also has a `GVAL`. `,OBLIST` is initially the same
6067 as `.OBLIST`; however, `,OBLIST` is not affected by the `SUBR`s used
6068 to manipulate the `OBLIST` structure. It is instead used only when
6071 In the case of an error, the current `.OBLIST` is checked to see if it
6072 is "reasonable" -- that is, contains nothing of the wrong `TYPE`. (It
6073 is reasonable, but not standard, for `.OBLIST` to be a single `OBLIST`
6074 instead of a `LIST` of them.) If it is reasonable, that value stays
6075 current. Otherwise, `OBLIST` is `SET` to `,OBLIST`. Note that changes
6076 made to the `OBLIST`s on `,OBLIST` -- for example, new `ATOM`s added
6077 -- remain. If even `,OBLIST` is unreasonable, `OBLIST` is `SET` and
6078 `SETG`ed to its initial value. `<ERRET>` (section 16.4) always assumes
6079 that `.OBLIST` is unreasonable.
6081 Three other `OBLIST`s exist in a virgin Muddle: their names and
6082 purposes are as follows:
6084 `ERRORS!-` contains `ATOM`s whose `PNAME`s are used as error messages.
6085 It is returned by `<ERRORS>`.
6087 `INTERRUPTS!-` is used by the interrupt system (section 21.5.1). It is
6088 returned by `<INTERRUPTS>`.
6090 `MUDDLE!-` is used infrequently by the interpreter when loading
6091 compiled programs to fix up references to locations within the
6094 The pre-loading of compiled programs may create other `OBLIST`s in an
6095 initialized Muddle (Lebling, 1979).
6097 15.6. BLOCK and ENDBLOCK
6098 ------------------------
6100 These `SUBR`s are analogous to **begin** and **end** in Algol, etc.,
6101 in the way they manipulate static blocking (and in **no** other way.)
6103 <BLOCK look-up:list-of-oblists>
6105 returns its argument after "pushing" the current `LVAL` of the `ATOM`
6106 `OBLIST` and making its argument the current `LVAL`. You usually want
6107 `<ROOT>` to be an element of *look-up*, normally its last.
6111 "pops" the LVAL of the `ATOM` `OBLIST` and returns the resultant
6112 `LIST` of `OBLIST`s.
6114 Note that this "pushing" and "popping" of `.OBLIST` is entirely
6115 independent of functional application, binding, etc.
6117 15.7. SUBRs Associated with Lexical Blocking
6118 --------------------------------------------
6120 ### 15.7.1. READ (again)
6122 <READ channel eof-routine look-up>
6124 This is a fuller call to `READ`. *look-up* is an `OBLIST` or a `LIST`
6125 of them, used as stated in section 15.3 to look up `ATOM`s and insert
6126 them in `OBLIST`s. If not specified, `.OBLIST` is used. See also
6127 section 11.1.1.1, 11.3, and 17.1.3 for other arguments.
6129 ### 15.7.2. PARSE and LPARSE (again)
6131 <PARSE string radix:fix look-up>
6133 as was previously mentioned, applies `READ`'s algorithm to *string*
6134 and returns the first Muddle object resulting. This **includes**
6135 looking up prospective `ATOM`s on *look-up*, if given, or `.OBLIST`.
6136 `LPARSE` can be called in the same way. See also section 7.6.6.2 and
6137 17.1.3 for other arguments.
6141 <LOOKUP string oblist>
6143 returns the `ATOM` of `PNAME` *string* in the `OBLIST` *oblist*, if
6144 there is such an `ATOM`; otherwise, it returns `#FALSE ()`. If
6145 *string* would `PARSE` into an `ATOM` anyway, `LOOKUP` is faster,
6146 although it looks in only one `OBLIST` instead of a `LIST` of them.
6152 creates and returns a spanking new `ATOM` of `PNAME` *string* which is
6153 guaranteed not to be on **any** `OBLIST`.
6155 An `ATOM` which is not on any `OBLIST` is `PRINT`ed with a trailer of
6160 <REMOVE string oblist>
6162 removes the `ATOM` of `PNAME` *string* from *oblist* and returns that
6163 ATOM. If there is no such `ATOM`, `REMOVE` returns `#FALSE ()`. Also,
6167 removes *atom* from its `OBLIST`, if it is on one. It returns *atom*
6168 if it was on an `OBLIST`; otherwise it returns `#FALSE ()`.
6172 <INSERT string-or-atom oblist>
6174 creates an `ATOM` of `PNAME` *string*, inserts it into *oblist* and
6175 returns it. If there is already an `ATOM` with the same `PNAME` as
6176 *atom* in *oblist*, an error occurs. The standard way to avoid the
6177 error and always get your *atom* is
6179 <OR <LOOKUP string oblist> <INSERT string oblist>>
6181 As with `REMOVE`, `INSERT` can also take an `ATOM` as its first
6182 argument; this `ATOM` must not be on any `OBLIST` -- it must have been
6183 `REMOVE`d, or just created by `ATOM` -- else an error occurs. The
6184 `OBLIST` argument is **never** optional. If you would like the new
6185 `ATOM` to live in the `OBLIST` that `READ` would have chosen, you can
6186 `<PARSE string>` instead.
6192 returns a `STRING` (newly created) which is *atom*'s `PNAME` ("printed
6193 name"). If trailers are not needed, `PNAME` is much faster than
6194 `UNPARSE` on *atom*. (In fact, `UNPARSE` has to go all the way through
6195 the `PRINT` algorithm **twice**, the first time to see how long a
6196 `STRING` is needed.)
6200 `SPNAME` ("shared printed name") is identical to `PNAME`, except that
6201 the `STRING` it returns shares storage with *atom* (appendix 1), which
6202 is more efficient if the `STRING` will not be modified. `PUT`ting into
6203 such a `STRING` will cause an error.
6205 15.8. Example: Another Solution to the INC Problem
6206 --------------------------------------------------
6208 What follows is an example of the way `OBLIST`s are "normally" used to
6209 provide "externally available" `ATOM`s and "local" `ATOM`s which are
6210 not so readily available externally. Lebling (1979) describes a
6211 systematic way to accomplish the same thing and more.
6214 ;"Create an OBLIST to hold your external symbols.
6215 Its name is INCO!-INITIAL!- ."
6218 ;"Put your external symbols into that OBLIST.
6219 If you have many, just write them successively."
6221 <BLOCK (<MOBLIST INCI!-INCO 1> <GET INCO OBLIST> <ROOT>)>
6222 ;"Create a local OBLIST, naming it INCI!-INCO, and set up
6223 .OBLIST for reading in your program. The OBLIST INCO is
6224 included in the BLOCK so that as your external symbols are
6225 used, they will be found in the right place. Note that the
6226 ATOM INCO is not in any OBLIST of the BLOCK; therefore,
6227 trailer notation of !-INCO will not work within the current
6228 BLOCK-ENDBLOCK pair."
6230 <DEFINE INC ;"INC is found in the INCO OBLIST."
6231 (A) ;"A is not found and is therefore put into INCI by
6233 #DECL ((VALUE A) <OR FIX FLOAT>)
6234 <SET .A <+ ..A 1>>> ;"All other ATOMs are found in the
6238 This example is rather trivial, but it contains all of the issues, of
6239 which there are three.
6241 The first idea is that you should create two `OBLIST`s, one to hold
6242 `ATOM`s which are to be known to other users (`INCO`), and the other
6243 to hold internal `ATOM`s which are not normally of interest to other
6244 (`INCI`). The case above has one `ATOM` in each category.
6246 Second, `INCO` is explicitly used **without** trailers so that
6247 surrounding `BLOCK` and `ENDBLOCK`s will have an effect on it. Thus
6248 `INCO` will be in the `OBLIST` desired by the user; `INC` will be in
6249 `INCO`, and the user can refer to it by saying `INC!-INCO`; `INCI`
6250 will also be in `INCO`, and can be referred to in the same way;
6251 finally, `A` is really `A!-INCI!-INCO`. The point of all this is to
6252 structure the nesting of `OBLIST`s.
6254 Finally, if for some reason (like saving storage space) you wish to
6255 throw `INCI` away, you can follow the `ENDBLOCK` with
6257 <REMOVE "INCI" <GET INCO OBLIST>>
6259 and thus remove all references to it. The ability to do such pruning
6260 is one reason for structuring `OBLIST` references.
6262 Note that, even after removing `INCI`, you can "get `A` back" -- that
6263 is, be able to type it in -- by saying something of the form
6265 <INSERT <1 <1 ,INC!-INCO>> <1 .OBLIST>>
6267 thereby grabbing `A` out of the structure of `INC` and re-inserting it
6268 into an `OBLIST`. however, this resurrects the name collision caused
6271 Chapter 16. Errors, Frames, etc.
6272 ================================
6277 This `SUBR` takes any number of arguments. It first checks the `LVAL`s
6278 of `INCHAN`, `OUTCHAN`, and `OBLIST` for reasonability and terminal
6279 usability. In each case, if the value is unreasonable, the `ATOM` is
6280 rebound to the corresponding `GVAL`, if reasonable, or to an invented
6281 reasonable value. `LISTEN` then does `<TTYECHO .INCHAN T>` and
6282 `<ECHOPAIR .INCHAN .OUTCHAN>`. Next, it `PRINT`s its arguments, then
6285 LISTENING-AT-LEVEL i PROCESS p
6287 where *i* is an integer (`FIX`) which is incremented each time
6288 `LISTEN` is called recursively, and *p* is an integer identifying the
6289 `PROCESS` (chapter 20) in which the `LISTEN` was `EVAL`ed. `LISTEN`
6290 then does `<APPLY <VALUE REP>>`, if there is one, and if it is
6291 `APPLICABLE`. If not, it applies the `SUBR` `REP` (without making a
6292 new `FRAME` -- see below). This `SUBR` drops into an infinite
6293 `READ`-`EVAL`-`PRINT` loop, which can be left via `ERRET` (section
6296 The standard `LISTEN` loop has two features for getting a handle on
6297 objects that you have typed in and Muddle has typed out. If the `ATOM`
6298 `L-INS` has a local value that is a `LIST`, `LISTEN` will keep recent
6299 inputs (what `READ` returns) in it, most recent first. Similarly, if
6300 the `ATOM` `L-OUTS` has a local value that is a `LIST`, `LISTEN` will
6301 keep recent outputs (what `EVAL` returns) in it, most recent first.
6302 The keeping is done before the `PRINT`ing, so that `^S` does not
6303 defeat its purpose. The user can decide how much to keep around by
6304 setting the length of each `LIST`. Even if `L-OUTS` is not used, the
6305 atom `LAST-OUT` is always `SET` to the last object returned by `EVAL`
6306 in the standard `LISTEN` loop. Example:
6308 <SET L-INS (NEWEST NEWER NEW)>$
6311 (.L-INS NEWEST NEWER)
6314 <SET FIXIT <2 .LINS>> ;"grab the last input"$
6317 (.L-INS <SET FIXIT <2 .L-INS>> <SET FOO 69>)
6323 (.L-INS <EVAL .FIXIT> <PUT .FIXIT 3 105>)
6330 This `SUBR` is the same as `LISTEN`, except that (1) it generates an
6331 interrupt (chapter 21), if enabled. and (2) it `PRINT`s `*ERROR*`
6332 before `PRINT`ing its arguments.
6334 When any `SUBR` or `FSUBR` detects an anomalous condition (for
6335 example, its arguments are of the wrong `TYPE`), it calls `ERROR` with
6336 at least two arguments, including:
6338 1. an `ATOM` whose `PNAME` describes the problem, normally from the
6339 `OBLIST` `ERRORS!-` (appendix 4),
6340 2. the `ATOM` that names the `SUBR` or `FSUBR`, and
6341 3. any other information of interest, and **then returns whatever the
6342 call to `ERROR` returns**. Exception: a few (for example `DEFINE`)
6343 will take further action that depends on the value returned. This
6344 nonstandard action is specified in the error message (first
6347 16.3. FRAME (the TYPE)
6349 A `FRAME` is the object placed on a `PROCESS`'s control stack (chapter
6350 20) whenever a `SUBR`, `FSUBR`, `RSUBR`, or `RSUBR-ENTRY` (chapter 19)
6351 is applied. (These objects are herein collectively called
6352 "Subroutines".) It contains information describing what was applied,
6353 plus a `TUPLE` whose elements are the arguments to the Subroutine
6354 applied. If any of the Subroutine's arguments are to be evaluated,
6355 they will have been by the time the `FRAME` is generated.
6357 A `FRAME` is an anomalous `TYPE` in the following ways:
6359 1. It cannot be typed in. It can be generated only by applying a
6361 2. It does not type out in any standard format, but rather as
6362 `#FRAME` followed by the `PNAME`of the Subroutine applied.
6368 ("arguments") returns the argument `TUPLE` of *frame*.
6374 ("function"} returns the `ATOM` whose `G/LVAL` is being applied in
6377 16.3.3. FRAME (the SUBR)
6381 returns the `FRAME` stacked **before** *frame* or, if there is none,
6382 it will generate an error. The oldest (lowest) `FRAME` that can be
6383 returned without error has a `FUNCT` of `TOPLEVEL`. If called with no
6384 arguments, `FRAME` returns the topmost `FRAME` used in an application
6385 of `ERROR` or `LISTEN`, which was bound by the interpreter to the
6386 `ATOM` `LERR\ I-INTERRUPTS` ("last error").
6390 Say you have gotten an error. You can now type at `ERROR`'s `LISTEN`
6391 loop and get things `EVAL`ed. For example,
6395 <FUNCT <FRAME <FRAME>>>$
6396 the-name-of-the-Subroutine-which-called-ERROR:atom
6397 <ARGS <FRAME <FRAME>>>$
6398 the-arguments-to-the-Subroutine-which-called-ERROR:tuple
6404 This `SUBR` ("error return") (1) causes the control stack to be
6405 stripped down to the level of *frame*, and (2) **then** returns *any*.
6406 The net result is that the application which generated *frame* is
6407 forced to return *any*. Additional side effects that would have
6408 happened in the absence of an error may not have happened.
6410 The second argument to `ERRET` is optional, by default the `FRAME` of
6411 the last invocation of `ERROR` or `LISTEN`.
6413 If `ERRET` is called with **no** arguments, it drops you **all** the
6414 way down to the **bottom** of the control stack -- **before** the
6415 level-1 `LISTEN` loop -- and then calls `LISTEN`. As always, `LISTEN`
6416 first ensures that Muddle is receptive.
6424 LISTENING-AT-LEVEL 2 PROCESS 1
6425 <ARGS <FRAME <FRAME>>>$
6427 <ERRET 5>$ ;"This causes the + to return 5."
6428 15 ;"finally returned by the *"
6430 Note that when you are in a call to `ERROR`, the most recent set of
6431 bindings is still in effect. This means that you can examine values of
6432 dummy variables while still in the error state. For example,
6434 <DEFINE F (A "AUX" (B "a string"))
6435 #DECL ((VALUE) LIST (A) STRUCTURED (B) STRING)
6436 (.B <REST .A 2>) ;"Return this LIST.">$
6443 LISTENING-AT-LEVEL 2 PROCESS 1
6448 <ERRET '(5)> ; "Make the REST return (5)."$
6455 causes the control stack to be stripped down just beyond *frame*, and
6456 then causes the Subroutine call that generated *frame* to be done
6457 again. *frame* is optional, by default the `FRAME` of the last
6458 invocation of `ERROR` or `LISTEN`. `RETRY` differs from `AGAIN` in
6459 that (1) it is not intended to be used in programs; (2) it can retry
6460 any old *frame* (any Subroutine call), whereas `AGAIN` requires an
6461 `ACTIVATION` (`PROG` or `REPEAT` or `"ACT"`); and (3) if it retries
6462 the `EVAL` of a `FORM` that makes an `ACTIVATION`, it will cause
6463 rebinding in the argument `LIST`, thus duplicating side effects.
6467 `UNWIND` is an `FSUBR` that takes two arguments, usually `FORM`s. It
6468 `EVAL`s the first one, and, if the `EVAL` returns normally, the value
6469 of the `EVAL` call is the value of `UNWIND`. If, however, during the
6470 `EVAL` a non-local return attempts to return below the `UNWIND`
6471 `FRAME` in the control stack, the second argument is `EVAL`ed, its
6472 value is ignored, and the non-local return is completed. The second
6473 argument is evaluated in the environment that was present when the
6474 call to `UNWIND` was made. This facility is useful for cleaning up
6475 data bases that are in inconsistent states and for closing temporary
6476 `CHANNEL`s that may be left around. `FLOAD` sets up an `UNWIND` to
6477 close its `CHANNEL` if the user attempts to `ERRET` without finishing
6478 the `FLOAD`. Example:
6480 <DEFINE CLEAN ACT ("AUX" (C <OPEN "READ" "A FILE">))
6481 #DECL ((C) <OR CHANNEL FALSE> ...)
6483 <UNWIND <PROG () ... <CLOSE .C>>
6486 16.7. Control-G (\^G)
6488 Typing control-G (`^G`, `<ASCII 7>`) at Muddle causes it to act just
6489 as if an error had occurred in whatever was currently being done. You
6490 can then examine the values of variables as above, continue by
6491 applying `ERRET` to one argument (which is ignored), `RETRY` a `FRAME`
6492 lower on the control stack, or flush everything by applying `ERRET` to
6495 16.8. Control-S (\^S)
6497 Typing control-S (`^S`, `<ASCII 19>`) at Muddle causes it to stop what
6498 is happening and return to the `FRAME` `.LERR\ !-INTERRUPTS`,
6499 returning the `ATOM` `T`. (In the Tenex and Tops-20 versions, `^O`
6500 also has the same effect.)
6504 <OVERFLOW false-or-any>
6506 There is one error that can be disabled: numeric overflow and
6507 underflow caused by the arithmetic `SUBR`s (`+`, `-`, `*`, `/`). The
6508 `SUBR` `OVERFLOW` takes one argument: if it is of `TYPE` `FALSE`,
6509 under/overflow errors are disabled; otherwise they are enabled. The
6510 initial state is enabled. `OVERFLOW` returns `T` or `#FALSE ()`,
6511 reflecting the previous state. Calling it with no argument returns the
6514 Chapter 17. Macro-operations
6515 ============================
6520 ### 17.1.1. % and %%
6522 The tokens `%` and `%%` are interpreted by `READ` in such a way as to
6523 give a "macro" capability to Muddle similar to PL/I's.
6525 Whenever `READ` encounters a single `%` -- anywhere, at any depth of
6526 recursion -- it **immediately**, without looking at the rest of the
6527 input, evaluates the object following the `%`. The result of that
6528 evaluation is used by `READ` in place of the object following the `%`.
6529 That is, `%` means "don't really `READ` this, use `EVAL` of it
6530 instead." `%` is often used in files in front of calls to `ASCII`,
6531 `BITS` (which see), etc., although when the `FUNCTION` is compiled the
6532 compiler will do the evaluation if the arguments are constant. Also
6533 seen is `%.INCHAN`, read as the `CHANNEL` in use during `LOAD` or
6534 `FLOAD`; for example, `<PUT %.INCHAN 18 8>` causes succeeding `FIX`es
6535 to be read as octal.
6537 Whenever `READ` encounters `%%`, it likewise immediately evaluates the
6538 object following the `%%`. However, it completely ignores the result
6539 of that evaluation. Side effects of that evaluation remain, of course.
6543 <DEFINE SETUP () <SET A 0>>$
6545 <DEFINE NXT () <SET A <+ .A 1>>>$
6547 [%%<SETUP> %<NXT> %<NXT> (%%<SETUP>) %<NXT>]$
6552 <LINK exp:any string oblist>
6554 creates an object of `TYPE` `LINK`, `PRIMTYPE` `ATOM`. A `LINK` looks
6555 vaguely like an `ATOM`; it has a `PNAME` (the *string* argument),
6556 resides in an `OBLIST` (the *oblist* argument) and has a "value" (the
6557 *exp* argument). A `LINK` has the strange property that, whenever it
6558 is encountered by `READ` (that is, its `PNAME` is read, just like an
6559 `ATOM`, possibly with `OBLIST` trailers), `READ` substitutes the
6560 `LINK`'s "value" for the `LINK` immediately. The effect of `READ`ing a
6561 `LINK`'s `PNAME` is exactly the same as the effect of reading its
6564 The *oblist* argument is optional, `<1 .OBLIST>` by default. `LINK`
6565 returns its first argument. The `LINK` is created via `INSERT`, so an
6566 error results if there is already an `ATOM` or `LINK` in *oblist* with
6569 The primary use of `LINK`s is in interactive work with Muddle:
6570 expressions which are commonly used, but annoyingly long to type, can
6571 be "linked" to `PNAME`s which are shorter. The standard example is the
6574 <LINK '<ERRET> "^E" <ROOT>>
6576 which links the `ATOM` of `PNAME` `^E` in the `ROOT` `OBLIST` to the
6577 expression `<ERRET>`.
6579 ### 17.1.3. Program-defined Macro-characters
6581 During `READ`ing from an input `CHANNEL` or `PARSE`ing a `STRING`, any
6582 character can be made to have a special meaning. A character can cause
6583 an arbitrary routine to be invoked, which can then return any number
6584 of elements to be put into the object being built by `READ`, `PARSE`,
6585 or `LPARSE`. Translation of characters is also possible. This facility
6586 was designed for those persons who want to use Muddle `READ` to do
6587 large parts of their input but have to modify its actions for some
6588 areas: for example, one might want to treat left and right parentheses
6589 as tokens, rather than as delimiters indicating a `LIST`.
6591 #### 17.1.3.1. READ (finally)
6593 Associated with `READ` is an `ATOM`, `READ-TABLE!-`, whose local
6594 value, if any, must be a `VECTOR` of elements, one for each character
6595 up to and including all characters to be treated specially. Each
6596 element indicates, if not `0`, the action to be taken upon `READ`'s
6597 encounter with that character. A similar `VECTOR`, the local value of
6598 `PARSE-TABLE!-`, if any, is used to find the action to take for
6599 characters encountered when `PARSE` or `LPARSE` is applied to a
6602 These tables can have up to 256 elements, one for each ASCII character
6603 and one for each possible exclamation-point/ASCII-character pair. In
6604 Muddle, the exclamation-point is used as a method of expanding the
6605 ASCII character set, and an exclamation-point/character pair is
6606 treated as one logical character when not reading a `STRING`.
6608 The element corresponding to a character is
6609 `<NTH table <+ 1 <ASCII char>>>`. The element corresponding to an
6610 exclamation-point/ASCII-character pair is
6611 `<NTH table <+ 129 <ASCII char>>>`. The table can be shorter than 256
6612 elements, in which case it is treated as if it were 256 long with `0`
6613 elements beyond its actual length.
6615 An element of the tables must satisfy one of the following `DECL`
6618 > `'0` indicates that no special action is to be taken when this
6619 > character is encountered.
6621 > `CHARACTER` indicates that the encountered character is to be
6622 > translated into the given `CHARACTER` whenever it appears, except
6623 > when as an object of `TYPE` `CHARACTER`, or in a `STRING`, or
6624 > immediately following a `\`.
6626 > `FIX` indicates that the character is to be given the same treatment
6627 > as the character with the ASCII value of the `FIX`. This allows you
6628 > to cause other characters to be treated in the same way as A-Z for
6629 > example. The same exceptions apply as for a `CHARACTER`.
6631 > `<LIST FIX>` indicates the same thing, except that the character
6632 > does not by itself cause a break. Therefore, if it occurs when
6633 > reading an `ATOM` or number, it will be treated as part of that
6636 > `APPLICABLE` (to one argument) indicates that the character is to be
6637 > a break character. Whenever it is encountered, the reading of the
6638 > current object is finished, and the corresponding element of the
6639 > table is `APPLY`ed to the ASCII `CHARACTER`. (If `READ` is called
6640 > during the application, the end-of-file slot of the `CHANNEL`
6641 > temporarily contains a special kind of `ACTIVATION` (`TYPE` `READA`)
6642 > so that end-of-file can be signalled properly to the original
6643 > `READ`. Isn't that wonderful?) The value returned is taken to be
6644 > what was read, unless an object of `TYPE` `SPLICE` is returned. If
6645 > so, the elements of this object, which is of `PRIMTYPE` `LIST`, are
6646 > spliced in at the point where Muddle is reading. An empty `SPLICE`
6647 > allows one to return nothing. If a structured object is not being
6648 > built, and a `SPLICE` is returned, elements after the first will be
6649 > ignored. A `SPLICE` says "expand me", whereas the structure
6650 > containing a `SEGMENT` says "I will expand you".
6652 > `<LIST APPLICABLE>` indicates the same thing, except that the
6653 > character does not by itself cause a break. Therefore, if it occurs
6654 > when reading an `ATOM` or number, it will be treated as part of that
6657 `READ` takes an additional optional argument, which is what to use
6658 instead of the local value of the `ATOM` `READ-TABLE` as the `VECTOR`
6659 of read-macro characters. If this argument is supplied, `READ-TABLE`
6660 is rebound to it within the call to `READ`. `READ` takes from zero to
6661 four arguments. The fullest call to `READ` is thus:
6663 <READ channel eof-routine look-up read-table:vector>
6665 The other arguments are explained in sections 11.1.1.1, 11.3, and
6668 `ERROR` and `LISTEN` rebind `READ-TABLE` to the `GVAL` of
6669 `READ-TABLE`, if any, else `UNASSIGN` it.
6671 #### 17.1.3.2. Examples
6673 Examples of each of the different kinds of entries in macro tables:
6675 <SET READ-TABLE <IVECTOR 256 0>>$
6678 <PUT .READ-TABLE <+ 1 <ASCII !\a>> !\A>
6679 ;"CHARACTER: translate a to A."$
6684 <PUT .READ-TABLE <+ 1 <ASCII !\%>> <ASCII !\A>>
6685 ;"FIX: make % just a normal ASCII character."$
6690 <PUT .READ-TABLE <+ 1 <ASCII !\.>> (<ASCII !\.>)>
6691 ;"<LIST FIX>: make comma no longer a break
6692 character, but still special if at a break."$
6696 ;"That was an ATOM with PNAME A,B ."
6699 ;"That was the FORM <GVAL B> ."
6701 <PUT .READ-TABLE <+ 1 <ASCII !\:>>
6702 #FUNCTION ((X) <LIST COLON <READ>>)>
6703 ;"APPLICABLE: make a new thing like ( < and [ ."$
6709 (COLON (COLON (COLON FOO)))
6711 <PUT .READ-TABLE <+ 1 <ASCII !\:>>
6712 '(#FUNCTION ((X) <LIST COLON <READ>>))>
6713 ;"<LIST APPLICABLE>: like above, but not a break
6718 ;"That was an ATOM."
6720 (COLON (COLON (COLON FOO)))
6722 #### 17.1.3.3. PARSE and LPARSE (finally)
6724 <PARSE string radix look-up parse-table:vector look-ahead:character>
6726 is the fullest call to `PARSE`. `PARSE` can take from zero to five
6727 arguments. If `PARSE` is given no arguments, it returns the first
6728 object parsed from the local value of the `STRING` `PARSE-STRING` and
6729 additionally `SET`s `PARSE-STRING` to the `STRING` having those
6730 `CHARACTER`s which were parsed `REST`ed off. If `PARSE` is given a
6731 `STRING` to parse, the `ATOM` `PARSE-STRING` is rebound to the
6732 `STRING` within that call. If the *parse-table* argument is given to
6733 `PARSE`, `PARSE-TABLE` is rebound to it within that call to `PARSE`.
6734 Finally, `PARSE` can take a *look-ahead* `CHARACTER`, which is treated
6735 as if it were logically concatenated to the front of the *string*
6736 being parsed. Other arguments are described in sections 7.6.6.2 and
6739 `LPARSE` is exactly like `PARSE`, except that it tries to parse the
6740 whole `STRING`, returning a `LIST` of the objects created.
6745 An `EVAL` macro provides the convenience of a `FUNCTION` without the
6746 overhead of calling, `SPECIAL`s, etc. in the **compiled** version. A
6747 special-purpose function that is called often by `FUNCTION`s that will
6748 be compiled is a good candidate for an `EVAL` macro.
6750 ### 17.2.1. DEFMAC and EXPAND
6752 `DEFMAC` ("define macro") is syntactically exactly the same as
6753 `DEFINE`. However, instead of creating a `FUNCTION`, `DEFMAC` creates
6754 a `MACRO`. A `MACRO` is of `PRIMTYPE` `LIST` and in fact has a
6755 `FUNCTION` (or other `APPLICABLE` `TYPE`) as its single element.
6757 A `MACRO` can itself be applied to arguments. A `MACRO` is applied in
6758 a funny way, however: it is `EVAL`ed twice. The first `EVAL` causes
6759 the `MACRO`'s element to be applied to the `MACRO`'s arguments.
6760 Whatever that application returns (usually another `FORM`) is also
6761 `EVAL`ed. The result of the second `EVAL`uation is the result of
6762 applying the `MACRO`. `EXPAND` is used to perform the first `EVAL`
6765 To avoid complications, the first `EVAL` (by `EXPAND`, to create the
6766 object to be `EVAL`ed the second time around) is done in a top-level
6767 environment. The result of this policy is that two syntactically
6768 identical invocations of a `MACRO` always return the same expansion to
6769 be `EVAL`ed in the second step. The first `EVAL` generates two extra
6770 `FRAME`s: one for a call to `EXPAND`, and one for a call to `EVAL` the
6771 `MACRO` application in a top-level environment.
6775 <DEFMAC INC (ATM "OPTIONAL" (N 1))
6776 #DECL ((VALUE) FORM (ATM) ATOM (N) <OR FIX FLOAT>)
6777 <FORM SET .ATM <FORM + <FORM LVAL .ATM> .N>>>$
6780 #MACRO (#FUNCTION ((ATM "OPTIONAL" (N 1)) ...))
6790 Perhaps the intention is clearer if `PARSE` and `%` are used:
6792 <DEFMAC INC (ATM "OPTIONAL" (N 1))
6794 <PARSE "<SET %.ATM <+ %.ATM %.N>>">>
6796 `MACRO`s really exhibit their advantages when they are compiled. The
6797 compiler will simply cause the first `EVAL`uation to occur (via
6798 `EXPAND`) and compile the result. The single element of a compiled
6799 `MACRO` is an `RSUBR` or `RSUBR-ENTRY`.
6803 Suppose you want to change the following simple `FUNCTION` to a
6806 <DEFINE DOUBLE (X) #DECL ((X) FIX) <+ .X .X>>
6808 You may be tempted to write:
6810 <DEFMAC DOUBLE (X) #DECL ((X) FIX) <FORM + .X .X>>
6812 This `MACRO` works, but only when the argument does not use temporary
6815 <DEFINE TRIPLE (Y) <+ .Y <DOUBLE .Y>>>
6817 If this `FUNCTION` is applied, the top-level binding of `Y` is used,
6818 not the binding just created by the application. Compilation of this
6819 `FUNCTION` would probably fail, because the compiler probably would
6820 have no top-level binding for `Y`. Well, how about
6822 <DEFMAC DOUBLE ('X) <FORM + .X .X>> ;"The DECL has to go."
6824 Now this is more like the original `FUNCTION`, because no longer is
6825 the argument evaluated and the result evaluated again. And `TRIPLE`
6826 works. But now consider
6828 <DEFINE INC-AND-DOUBLE (Y) <DOUBLE <SET Y <+ 1 .Y>>>>
6832 <INC-AND-DOUBLE 1> -> <DOUBLE <SET Y <+ 1 1>>>
6837 But, when `DOUBLE` is applied to that `FORM`, the argument is
6840 <INC-AND-DOUBLE 1> -> <DOUBLE <SET Y <+ 1 1>>>
6841 -> <FORM + <SET Y <+ 1 .Y>> <SET Y <1 .Y>>>
6845 So, since the evaluation of `DOUBLE`'s argument has a side effect, you
6846 should ensure that the evaluation is done exactly once, say by `FORM`:
6848 <DEFMAC DOUBLE ('ANY)
6849 <FORM PROG ((X .ANY)) #DECL ((X) FIX) '<+ .X .X>>>
6851 As a bonus, the `DECL` can once more be used.
6853 This example is intended to show that writing good `MACRO`s is a
6854 little trickier than writing good `FUNCTION`s. But the effort may be
6855 worthwhile if the compiled program must be speedy.
6857 Chapter 18. Machine Words and Bits
6858 ==================================
6860 The Muddle facility for dealing with uninterpreted machine words and
6861 bits involves two data TYPEs: WORD and BITS. A WORD is simply an
6862 uninterpreted machine word, while a BITS is a "pointer" to a set of
6863 bits within a WORD. Operating on WORDs is usually done only when
6864 compiled programs are used (chapter 19).
6869 A `WORD` in Muddle is a PDP-10 machine word of 36 bits. A `WORD`
6870 always `PRINT`s in "\# format", and its contents are always printed in
6871 octal (hence preceded and followed by `*`). Examples:
6874 #WORD *000000000000*
6876 #WORD *2000* ;"one bit 1"$
6877 #WORD *000000002000*
6879 #WORD *525252525252* ;"every other bit 1"$
6880 #WORD *525252525252*
6882 `WORD` is its own `PRIMTYPE`; it is also the `PRIMTYPE` of `FIX`,
6883 `FLOAT`, `CHARACTER`, and any other `TYPE` which can fit its data into
6886 A `WORD` cannot be an argument to `+`, `-`, or indeed any `SUBR`s
6887 except for `CHTYPE`, `GETBITS`, `PUTBITS` and several bit-manipulating
6888 functions, all to be described below. Thus any arithmetic bit
6889 manipulation must be done by `CHTYPE`ing a `WORD` to `FIX`, doing the
6890 arithmetic, and then `CHTYPE`ing back to `WORD`. However, bit
6891 manipulation can be done without `CHTYPE`ing the thing to be played
6892 with to a `WORD`, so long as it is of `PRIMTYPE` `WORD`; the result of
6893 the manipulation will be of the same `TYPE` as the original object or
6894 can be `CHTYPE`d to it.
6899 An object of `TYPE` `BITS` is of `PRIMTYPE` `WORD`, and `PRINT`s just
6900 like a `WORD`. The internal form of a `BITS` is precisely that of a
6901 PDP-10 "byte pointer", which is, in fact, just what a `BITS` is.
6903 For purposes of explaining what a `BITS` is, assume that the bits in a
6904 `WORD` are numbered from **right** to **left**, with the rightmost bit
6905 numbered 0 and the leftmost numbered 35, as in
6909 (This is not the "standard" ordering: the "standard" one goes from
6912 A `BITS` is most conveniently created via the `SUBR` `BITS`:
6914 <BITS width:fix right-edge:fix>
6916 returns a `BITS` which "points to" a set of bits *width* wide, with
6917 rightmost bit *right-edge*. Both arguments must be of `TYPE` `FIX`,
6918 and the second is optional, 0 by default.
6920 Examples: the indicated application of `BITS` returns an object of
6921 `TYPE` `BITS` which points to the indicated set of bits in a `WORD`:
6924 --------------- ------------------------------------
6925 `<BITS 7>` 35 ... 7 **6 ... 0**
6926 `<BITS 4 18>` 35 ... 22 **21 20 19 18** 17 ... 0
6927 `<BITS 36>` ***35 ... 0***
6932 <GETBITS from:primtype-word bits>
6934 where *from* is an object of `PRIMTYPE` `WORD`, returns a **new**
6935 object whose `TYPE` is `WORD`. This object is constructed in the
6936 following way: the set of bits in *from* pointed to by *bits* is
6937 copied into the new object, right-adjusted, that is, lined up against
6938 the right end (bit number 0) of the new object. All those bits of the
6939 new object which are not copied are set to zero. In other words,
6940 `GETBITS` takes bits from an arbitrary place in *from* and puts them
6941 at the right of a new object. The *from* argument to `GETBITS` is not
6946 <GETBITS #WORD *777777777777* <BITS 3>>$
6947 #WORD *000000000007*
6948 <GETBITS *012345670123* <BITS 6 18>>$
6949 #WORD *000000000045*
6954 <PUTBITS to:primtype-word bits from:primtype-word>
6956 where *to* and *from* are of `PRIMTYPE` `WORD`, returns a **copy** of
6957 *to*, modified as follows: the set of bits in *to* which are pointed
6958 to by *bits* are replaced by the appropriate number of rightmost bits
6959 copied from *from* (optional, 0 by default). In other words: `PUTBITS`
6960 takes bits from the right of *from* and stuffs them into an arbitrary
6961 position in a copy of *to*. **None** of the arguments to `PUTBITS` is
6966 <PUTBITS #WORD *777777777777* <BITS 6 3>>$
6967 #WORD *777777777007*
6968 <PUTBITS #WORD *666777000111* <BITS 5 15> #WORD *123*>$
6969 #WORD *666776300111*
6970 <PUTBITS #WORD *765432107654* <BITS 18>>$
6971 #WORD *765432000000*
6973 18.5. Bitwise Boolean Operations
6974 --------------------------------
6976 Each of the `SUBR`s `ANDB`, `ORB`, `XORB`, and `EQVB` takes arguments
6977 of `PRIMTYPE` `WORD` and returns a `WORD` which is the bitwise Boolean
6978 "and", inclusive "or", exclusive "or", or "equivalence" (inverse of
6979 exclusive "or"), respectively, of its arguments. Each takes any number
6980 of arguments. If no argument is given, a `WORD` with all bits off
6981 (`ORB` and `XORB`) or on (`ANDB` and `EQVB`) is returned. If only one
6982 argument is given, it is returned unchanged but `CHTYPE`d to a `WORD`.
6983 If more than two arguments are given, the operator is applied to the
6984 first two, then applied to that result and the third, etc. Be sure not
6985 to confuse `AND` and `OR` with `ANDB` and `ORB`.
6987 18.6. Bitwise Shifting Operations
6988 ---------------------------------
6990 <LSH from:primtype-word amount:fix>
6992 returns a **new** `WORD` containing the bits in *from*, shifted the
6993 number of bits specified by *amount* (mod 256, says the hardware).
6994 Zero bits are brought in at the end being vacated; bits shifted out at
6995 the other end are lost. If *amount* is positive, shifting is to the
6996 left; if *amount* is negative, shifting is to the right. Examples:
6999 #WORD *000000001000*
7001 #WORD *000000000000*
7003 <ROT from:primtype-word amount:fix>
7005 returns a **new** `WORD` containing the bits from *from*, rotated the
7006 number of bits specified by *amount* (mod 256, says the hardware).
7007 Rotation is a cyclic bitwise shift where bits shifted out at one end
7008 are put back in at the other. If *amount* is positive, rotation is to
7009 the left; if *amount* is negative, rotation is to the right. Examples:
7012 #WORD *000000001000*
7014 #WORD *100000000000*
7016 Chapter 19. Compiled Programs
7017 =============================
7019 19.1. RSUBR (the TYPE)
7020 ----------------------
7022 `RSUBR`s ("relocatable subroutines") are machine-language programs
7023 written to run in the Muddle environment. They are usually produced by
7024 the Muddle assembler (often from output produced by the compiler)
7025 although this is not necessary. All `RSUBR`s have two components: the
7026 "reference vector" and the "code vector". In some cases the code
7027 vector is in pure storage. There is also a set of "fixups" associated
7028 with every `RSUBR`, although it may not be available in the running
7031 19.2. The Reference Vector
7032 --------------------------
7034 An `RSUBR` is basically a `VECTOR` that has been `CHTYPE`d to `TYPE`
7035 `RSUBR` via the `SUBR` `RSUBR` (see below). This ex-`VECTOR` is the
7036 reference vector. The first three elements of the reference vector
7037 have predefined meanings:
7039 - The first element is of `TYPE` `CODE` or `PCODE` and is the impure
7040 or pure code vector respectively.
7041 - The second element is an `ATOM` and specifies the name of the
7043 - The third element is of `TYPE` `DECL` and declares the
7044 type/structure of the `RSUBR`'s arguments and result.
7046 The rest of the elements of the reference vector are objects in
7047 garbage-collected storage that the `RSUBR` needs to reference and any
7048 impure slots that the `RSUBR` needs to use.
7050 When the `RSUBR` is running, one of the PDP-10 accumulators (with
7051 symbolic name `R`) is always pointing to the reference vector, to
7052 permit rapid access to the various elements.
7057 `RSUBR`s can call any `APPLICABLE` object, all in a uniform manner. In
7058 general, a call to an F/SUBR is linked up at assembly/compile time so
7059 that the calling instruction (UUO) points directly at the code in the
7060 interpreter for the F/SUBR. However, the locations of most other
7061 `APPLICABLE`s are not known at assembly/compile time. Therefore, the
7062 calling UUO is set up to point at a slot in the reference vector (by
7063 indexing off accumulator `R`). This slot initially contains the `ATOM`
7064 whose G/LVAL is the called object. The calling mechanism (UUO handler)
7065 causes control to be transferred to the called object and, depending
7066 on the state of the `RSUBR`-link flag, the `ATOM` will be replaced by
7067 its G/LVAL. (If the call is of the "quick" variety, the called `RSUBR`
7068 or `RSUBR-ENTRY` will be `CHTYPE`d to a `QUICK-RSUBR` or
7069 `QUICK-ENTRY`, respectively, before replacement.) Regardless of the
7070 `RSUBR`-link flag's state, calls to `FUNCTION`s are never permanently
7071 linked. A call to a non-Subroutine generates an extra `FRAME`, whose
7072 `FUNCT` is the dummy `ATOM` `CALLER`.
7074 `RSUBR`s are linked together for faster execution, but linking may not
7075 be desirable if the `RSUBR`s are being debugged, and various revisions
7076 are being re-loaded. A linked call will forever after go to the same
7077 code, regardless of the current G/LVAL of the called `ATOM`. Thus,
7078 while testing `RSUBR`s, you may want to disable linking, by calling
7079 the `RSUBR-LINK` `SUBR` with a `FALSE` argument. Calling it with a
7080 non-`FALSE` argument enables linking thereafter. It returns the
7081 previous state of the link flag, either `T` or `#FALSE ()`. Calling it
7082 with no argument returns the current state.
7084 19.4. Pure and Impure Code
7085 --------------------------
7087 The first element of an `RSUBR` is the code vector, of `TYPE` `CODE`
7088 or `PCODE`. `TYPE` `CODE` is of `PRIMTYPE` `UVECTOR`, and the `UTYPE`
7089 should be of `PRIMTYPE` `WORD`. The code vector is simply a block of
7090 words that are the instructions which comprise the `RSUBR`. Since the
7091 code vector is stored just like a standard `UVECTOR`, it will be moved
7092 around by the garbage collector. Therefore, all `RSUBR` code is
7093 required to be location-insensitive. The compiler guarantees the
7094 location-insensitivity of its output. The assembler helps to make the
7095 code location-insensitive by defining all labels as offsets relative
7096 to the beginning of the code vector and causing instructions that
7097 refer to labels to index automatically off the PDP-10 accumulator
7098 symbolically named `M`. `M`, like `R`, is set up by the UUO handler,
7099 but it points to the code vector instead of the reference vector. The
7100 code vector of an `RSUBR` can be frozen (using the `FREEZE` `SUBR`) to
7101 prevent it from moving during debugging by DDT in the superior
7102 operating-system process.
7104 If the first element of an `RSUBR` is of `TYPE` `PCODE` ("pure code"),
7105 the code vector of the `RSUBR` is pure and sharable. `TYPE` `PCODE` is
7106 of `PRIMTYPE` `WORD`. The left half of the word specifies an offset
7107 into an internal table of pure `RSUBR`s, and the right half specifies
7108 an offset into the block of code where this `RSUBR` starts. The
7109 `PCODE` prints out as:
7111 %<PCODE name:string offset:fix>
7113 where *name* names the entry in the user's pure-`RSUBR` table, and
7114 *offset* is the offset. (Obviously, `PCODE` is also the name of a
7115 `SUBR`, which generates a pure code vector.) Pure `RSUBR`s may also
7116 move around, but only by being included in Muddle's page map at
7117 different places. Once again `M` can be used exactly as before to do
7118 location-independent address referencing. Individual pure code vectors
7119 can be "unmapped" (marked as being not in primary storage but in their
7120 original pure-code disk files) if the space in storage allocated for
7121 pure code is exhausted. An unmapped `RSUBR` is mapped in again
7122 whenever needed. All pure `RSUBR`s are unmapped before a `SAVE` file
7123 is written, so that the code is not duplicated on disk. A purified
7124 `RSUBR` must use `RGLOC` ("relative GLOC") instead of `GLOC`. `RGLOC`
7125 produces objects of `TYPE` `LOCR` instead of `LOCD`.
7127 19.5. TYPE-C and TYPE-W
7128 =======================
7130 In order to handle user `NEWTYPE`s reasonably, the internal `TYPE`
7131 codes for them have to be able to be different from one Muddle run to
7132 another. Therefore, references to the `TYPE` codes must be in the
7133 reference vector rather than the code vector. To help handle this
7134 problem, two `TYPE`s exist, `TYPE-C` ("type code") and `TYPE-W` ("type
7135 word"), both of `PRIMTYPE` `WORD`. They print as:
7137 %<TYPE-C type primtype:atom>
7138 %<TYPE-W type primtype:atom>
7140 The `SUBR` `TYPE-C` produces an internal `TYPE` code for the *type*,
7141 and `TYPE-W` produces a prototype "`TYPE` word" (appendix 1) for an
7142 object of that `TYPE`. The *primtype* argument is optional, included
7143 only as a check against the call to `NEWTYPE`. `TYPE-W` can also take
7144 a third argument, of `PRIMTYPE` `WORD`, whose right half is included
7145 in the generated "`TYPE` word". If *type* is not a valid `TYPE`, a
7146 `NEWTYPE` is automatically done.
7148 To be complete, a similar `SUBR` and `TYPE` should be mentioned here.
7152 produces an internal "storage allocation code" (appendix 1) for the
7153 *type*. The value is of `TYPE` `PRIMTYPE-C`, `PRIMTYPE` `WORD`. In
7154 almost all cases the `SUBR` `TYPEPRIM` gives just as much information,
7155 except in the case of `TEMPLATE`s: all `TYPE`s of `TEMPLATE`s have the
7156 same `TYPEPRIM`, but they all have different `PRIMTYPE-C`s.
7158 19.6. RSUBR (the SUBR)
7159 ----------------------
7161 <RSUBR [code name decl ref ref ...]>
7163 `CHTYPE`s its argument to an `RSUBR`, after checking it for legality.
7164 `RSUBR` is rarely called other than in the Muddle Assembler (Lebling,
7165 1979). It can be used if changes must be made to an `RSUBR` that are
7166 prohibited by Muddle's built-in safety mechanisms. For example, if the
7167 `GVAL` of *name* is an `RSUBR`:
7169 <SET FIXIT <CHTYPE ,name VECTOR>>$
7172 ...(changes to .FIXIT)...
7174 <SETG name <RSUBR .FIXIT>>$
7180 `RSUBR`s can have multiple entry points. An `RSUBR-ENTRY` can be
7181 applied to arguments exactly like an `RSUBR`.
7183 <RSUBR-ENTRY [rsubr-or-atom name:atom decl] offset:fix>
7185 returns the `VECTOR` argument `CHTYPE`d to an `RSUBR-ENTRY` into the
7186 *rsubr* at the specified *offset*. If the `RSUBR-ENTRY` is to have a
7187 `DECL` (`RSUBR` style), it should come as shown.
7189 <ENTRY-LOC rsubr-entry>
7191 ("entry location") returns the *offset* into the `RSUBR` of this
7194 19.8. RSUBRs in Files
7195 ---------------------
7197 There are three kinds of files that can contain `RSUBR`s, identified
7198 by second names `BINARY`, `NBIN` and `FBIN`. There is nothing magic
7199 about these names, but they are used by convention.
7201 A `BINARY` file is a completely ASCII file containing complete impure
7202 `RSUBR`s in character representation. Even a code vector appears as
7203 `#CODE` followed by a `UVECTOR` of `PRIMTYPE` `WORD`s. `BINARY` files
7204 are generally slow to load, because of all the parsing that must be
7207 An `NBIN` file contains a mixture of ASCII characters and binary code.
7208 The start of a binary portion is signalled to `READ` by the character
7209 control-C, so naive readers of an `NBIN` file under ITS may
7210 incorrectly assume that it ends before any binary code appears. An
7211 `NBIN` file cannot be edited with a text editor. An `RSUBR` is written
7212 in `NBIN` format by being `PRINT`ed on a `"PRINTB"` `CHANNEL`. The
7213 `RSUBR`s in `NBIN` files are not purified either.
7215 An `FBIN` file is actually part of a triad of files. The `FBIN`
7216 file(s) itself is the impure part of a collection of purified
7217 `RSUBR`s. It is simply ASCII and can be edited at will. (Exception: in
7218 the ITS and Tops-20 versions, the first object in the file should not
7219 be removed or changed in any way, lest a "grim reaper" program for
7220 `FBIN` files think that the other files in the triad are obsolete and
7221 delete them.) The pure code itself resides (in the ITS and Tops-20
7222 versions) in a special large file that contains all currently-used
7223 pure code, or (in the Tenex version) in a file in a special disk
7224 directory with first name the same as the *name* argument to `PCODE`
7225 for the `RSUBR`. The pure-code file is page-mapped directly into
7226 Muddle storage in read-only mode. It can be unmapped when the pure
7227 storage must be reclaimed, and it can be mapped at a different storage
7228 address when pure storage must be compacted. There is also a "fixup"
7229 file (see below) or portion of a file associated with the `FBIN` to
7230 round out the triad.
7232 An initial Muddle can have pure `RSUBR`s in it that were "loaded"
7233 during the initialization procedure. The files are not page-mapped in
7234 until they are actually needed. The "loading" has other side effects,
7235 such as the creation of `OBLIST`s (chapter 15). Exactly what is
7236 pre-loaded is outside the scope of this document.
7241 The purpose of "fixups" is to correct references in the `RSUBR` to
7242 parts of the interpreter that change from one release of Muddle to the
7243 next. The reason the fixups contain a release number is so that they
7244 can be completely ignored when an `RSUBR` is loaded into the same
7245 release of Muddle as that from which it was last written out.
7247 There are three forms of fixups, corresponding to the three kinds of
7248 `RSUBR` files. ASCII `RSUBR`s, found in `BINARY` files, have ASCII
7249 fixups. The fixups are contained in a `LIST` that has the following
7253 name:atom value:fix (use:fix use:fix ...)
7254 name:atom value:fix (use:fix use:fix ...)
7257 The fixups in `NBIN` files and the fixup files associated with `FBIN`
7258 files are in a fast internal format that looks like a `UVECTOR` of
7261 Fixups are usually discarded after they are used during the loading
7262 procedure. However, if, while reading a `BINARY` or `NBIN` file the
7263 `ATOM` `KEEP-FIXUPS!-` has a non-`FALSE` `LVAL`, the fixups will be
7264 kept, via an association between the `RSUBR` and the `ATOM` `RSUBR`.
7265 It should be noted that, besides correcting the code, the fixups
7266 themselves are corrected when `KEEP-FIXUPS` is bound and true. Also,
7267 the assembler and compiler make the same association when they first
7268 create an `RSUBR`, so that it can be written out with its fixups.
7270 In the case of pure `RSUBR`s (`FBIN` files), things are a little
7271 different. If a pure-code file exists for this release of Muddle, it
7272 is used immediately, and the fixups are completely ignored. If a
7273 pure-code file for this release doesn't exist, the fixup file is used
7274 to create a new copy of the file from an old one, and also a new
7275 version of the fixup file is created to go with the new pure-code
7276 file. This all goes on automatically behind the user's back.
7278 Chapter 20. Coroutines
7279 ======================
7281 This chapter purports to explain the coroutine primitives of Muddle.
7282 It does make some attempt to explain coroutines as such, but only as
7283 required to specify the primitives. If you are unfamiliar with the
7284 basic concepts, confusion will probably reign.
7286 A coroutine in Muddle is implemented by an object of `TYPE` `PROCESS`.
7287 In this manual, this use of the word "process" is distinguished by a
7288 capitalization from its normal use of denoting an operating-system
7289 process (which various systems call a process, job, fork, task, etc.).
7291 Muddle's built-in coroutine primitives do not include a "time-sharing
7292 system". Only one `PROCESS` is ever running at a time, and control is
7293 passed back and forth between `PROCESS`es on a coroutine-like basis.
7294 The primitives are sufficient, however, to allow the writing of a
7295 "time-sharing system" **in Muddle**, with the additional use of the
7296 Muddle interrupt primitives. This has, in fact, been done.
7298 20.1. PROCESS (the TYPE)
7299 ------------------------
7301 A `PROCESS` is an object which contains the "current state" of a
7302 computation. This includes the `LVAL`s of `ATOM`s ("bindings"),
7303 "depth" of functional application, and "position" within the
7304 application of each applied function. Some of the things which are
7305 **not** part of any specific `PROCESS` are the `GVAL`s of `ATOM`s,
7306 associations (`ASOC`s), and the contents of `OBLIST`s. `GVAL`s (with
7307 `OBLIST`s) are a chief means of communication and sharing between
7308 `PROCESS`es (all `PROCESS`es can refer to the `SUBR` which is the
7309 `GVAL` of `+`, for instance.) Note that an `LVAL` in one `PROCESS`
7310 cannot easily be directly referenced from another `PROCESS`.
7312 A `PROCESS` `PRINT`s as `#PROCESS` *p*, where *p* is a `FIX` which
7313 uniquely identifies the `PROCESS`; *p* is the "`PROCESS` number" typed
7314 out by `LISTEN`. A `PROCESS` cannot be read in by `READ`.
7316 The term "run a `PROCESS`" will be used below to mean "perform some
7317 computation, using the `PROCESS` to record the intermediate state of
7320 N.B.: A `PROCESS` is a rather large object; creating one will often
7321 cause a garbage collection.
7323 20.2. STATE of a PROCESS
7324 ------------------------
7328 returns an `ATOM` (in the `ROOT` `OBLIST`) which indicates the "state"
7329 of the `PROCESS` *process*. The `ATOM`s which `STATE` can return, and
7330 their meanings, are as follows:
7332 - `RUNABLE` (sic) -- *process* has never ever been run.
7333 - `RUNNING` -- *process* is currently running, that is, it did the
7334 application of `STATE`.
7335 - `RESUMABLE` -- *process* has been run, is not currently running,
7337 - `DEAD` -- *process* has been run, but it can **not** run again; it
7340 In addition, an interrupt (chapter 21) can be enabled to detect the
7341 time at which a `PROCESS` becomes "blocked" (waiting for terminal
7342 input) or "unblocked" (terminal input arrived). (The `STATE` `BLOCKED`
7343 has not been implemented.)
7345 20.3. PROCESS (the SUBR)
7346 ------------------------
7348 <PROCESS starter:applicable>
7350 creates and returns a new `PROCESS` but does **not** run it; the
7351 `STATE` of the returned `PROCESS` is `RUNABLE` (sic).
7353 *starter* is something applicable to **one** argument, which must be
7354 evaluated. *starter* is used both in starting and "terminating" a
7355 `PROCESS`. In particular, if the *starter* of a `PROCESS` **ever**
7356 returns a value, that `PROCESS` becomes `DEAD`.
7361 The `SUBR` `RESUME` is used to cause a computation to start or to
7362 continue running in another `PROCESS`. An application of `RESUME`
7365 <RESUME retval:any process>
7367 where *retval* is the "returned value" (see below) of the `PROCESS`
7368 that does the `RESUME`, and *process* is the `PROCESS` to be started
7371 The *process* argument to `RESUME` is optional, by default the last
7372 `PROCESS`, if any, to `RESUME` the `PROCESS` in which this `RESUME` is
7373 applied. If and when the current `PROCESS` is later `RESUME`d by
7374 another `PROCESS`, that `RESUME`'s *retval* is returned as the value
7377 20.5. Switching PROCESSes
7378 -------------------------
7380 ### 20.5.1. Starting Up a New PROCESS
7382 Let us say that we are running in some `PROCESS`, and that this
7383 original `PROCESS` is the `GVAL` of `P0`. Somewhere, we have evaluated
7385 <SETG P1 <PROCESS ,STARTER>>
7387 where `,STARTER` is some appropriate function. Now, **in `,P0`** we
7392 and the following happens:
7394 1. **In `,P0`** the arguments of the `RESUME` are evaluated: that is,
7395 we get that `LVAL` of `A` which is current in `,P0` and the `GVAL`
7397 2. The `STATE` of `,P0` is changed to `RESUMABLE` and `,P0` is
7398 "frozen" right where it is, in the middle of the `RESUME`.
7399 3. The `STATE` of `,P1` is changed to `RUNNING`, and `,STARTER` is
7400 applied to `,P0`'s `LVAL` of `A` **in `,P1`**. `,P1` now continues
7401 on its way, evaluating the body of `,STARTER.`
7403 The `.A` in the `RESUME` could have been anything, of course. The
7404 important point is that, whatever it is, it is evaluated in `,P0`.
7406 What happens next depends, of course, on what `,STARTER` does.
7408 ### 20.5.2. Top-level Return
7410 Let us initially assume that `,STARTER` does nothing relating to
7411 `PROCESS`es, but instead simply returns a value -- say *starval*. What
7412 happens when `,STARTER` returns is this:
7414 1. The `STATE` of `,P1` is changed to `DEAD`. `,P1` can never again
7416 2. The last `PROCESS` to `RESUME` `,P1` is found, namely `,P0`, and
7417 its `STATE` is changed to `RUNNING`.
7418 3. *starval* is returned in `,P0` as the value of the original
7419 `RESUME`, and `,P0` continues where it left off.
7421 All in all, this simple case looks just like an elaborate version of
7422 applying `,STARTER` to `.A` in `,P0`.
7424 ### 20.5.3. Symmetric RESUMEing
7426 Now suppose that while still in `,P1`, the following is evaluated,
7427 either in `,STARTER` or in something called by `,STARTER`:
7431 This is what happens:
7433 1. The arguments of the `RESUME` are evaluated **in `,P1`**.
7434 2. The `STATE` of `,P1` is changed to `RESUMABLE`, and `,P1` is
7435 "frozen" right in the middle of the `RESUME`.
7436 3. The `STATE` of `,P0` is changed to `RUNNING`, and `,P1`'s `LVAL`
7437 of `BAR` is returned as the value of **`,P0'`s** original `RESUME`
7438 `,P0` then continues right where it left off.
7440 This is **the** interesting case, because `,P0` can now do **another**
7441 `RESUME` of `,P1`; this will "turn off" `,P0`, pass a value to `,P1`
7442 and "turn on" `,P1`. `,P1` can now again `RESUME` `,P0`. which can
7443 `RESUME` `,P1` back again, etc. **ad nauseam**, with everything done
7444 in a perfectly symmetric manner. This can obviously also be done with
7445 three or more `PROCESS`es in the same manner.
7447 Note how this differs from normal functional application: you cannot
7448 "return" from a function without destroying the state that function is
7449 in. The whole point of `PROCESS`es is that you can "return"
7450 (`RESUME`), remembering your state, and later continue where you left
7456 ;"Initially, we are in LISTEN in some PROCESS.
7458 #DECL ((A) (OR FIX FLOAT>)
7460 #DECL ((S) <OR FIX FLOAT>)
7461 <SET S <+ .S <RESUME "GOT 1">>>
7462 <SET S <+ .S <RESUME "GOT 2">>>
7463 <SET S <RESUME .S>>>>$
7465 ;"SUM3, used as the startup function of another PROCESS,
7466 gets RESUMEd with numbers. It returns the sum of the last
7467 three numbers it was given every third RESUME."
7468 <SETG SUMUP <PROCESS ,SUM3>>$
7469 ;"Now we start SUMUP and give SUM3 its three numbers."
7477 Just as a note, by taking advantage of Muddle's order of evaluation,
7478 SUM3 could be have been written as:
7482 #DECL ((A S0 <OR FIX FLOAT>)
7483 <SET S <RESUME <+ .S <RESUME "GOT 1"> <RESUME "GOT 2">>>>>>
7485 20.7. Other Coroutining Features
7486 --------------------------------
7488 ### 20.7.1. BREAK-SEQ
7490 <BREAK-SEQ any process>
7492 ("break evaluation sequence") returns *process*, which must be
7493 `RESUMABLE`, after having modified it so that when it is next
7494 `RESUME`d, it will **first** evaluate *any* and **then** do an
7495 absolutely normal `RESUME`; the value returned by any is thrown away,
7496 and the value given by the `RESUME` is used normally.
7498 If a `PROCESS` is `BREAK-SEQ`ed more than once between `RESUME`s,
7499 **all** of the *any*s `BREAK-SEQ`ed onto it will be remembered and
7500 evaluated when the `RESUME` is finally done. The *any*s will be
7501 evaluated in "last-in first-out" order. The `FRAME` generated by
7502 `EVAL`ing more than one *any* will have as its `FUNCT` the dummy
7507 When you initially start up Muddle, the `PROCESS` in which you are
7508 running is slightly "special" in these two ways:
7510 1. Any attempt to cause it become `DEAD` will be met with an error.
7511 2. `<MAIN>` always returns that `PROCESS`.
7513 The `PROCESS` number of `<MAIN>` is always `1`. The initial `GVAL` of
7514 `THIS-PROCESS` is what `MAIN` always returns, `#PROCESS 1`.
7520 returns the `PROCESS` in which it is evaluated. The `LVAL` of
7521 `THIS-PROCESS` in a `RUNABLE` (new) `PROCESS` is what `ME` always
7528 returns the `PROCESS` which last `RESUME`d *process*. If no `PROCESS`
7529 has ever `RESUME`d process, it returns `#FALSE ()`. *process* is
7530 optional, `<ME>` by default. Note that `<MAIN>` does not ever have any
7533 <PROG ((R <RESUMER>)) ;"not effective in <MAIN>"
7534 #DECL ((R) <OR PROCESS FALSE>)
7536 <==? <STATE .R> RESUMABLE>
7541 <SUICIDE retval process>
7543 acts just like `RESUME`, but clobbers the `PROCESS` (which cannot be
7544 `<MAIN>`) in which it is evaluated to the `STATE` `DEAD`.
7550 returns *process*, after putting it into "single-step mode".
7552 A `PROCESS` in single-step mode, whenever `RESUME`d, runs only until
7553 an application of `EVAL` in it begins or finishes. At that point in
7554 time, the `PROCESS` that did the `1STEP` is `RESUME`d, with a *retval*
7555 which is a `TUPLE`. If an application of `EVAL` just began, the
7556 `TUPLE` contains the `ATOM` `EVLIN` and the arguments to `EVAL`. If an
7557 application of `EVAL` just finished, the `TUPLE` contains the `ATOM`
7558 `EVLOUT` and the result of the evaluation.
7560 *process* will remain in single-step mode until `FREE-RUN` (below) is
7561 applied to it. Until then, it will stop before and after each `EVAL`
7562 in it. Exception: if it is `RESUME`d from an `EVLIN` break with a
7563 *retval* of `TYPE` `DISMISS` (`PRIMTYPE` `ATOM`), it will leave
7564 single-step mode only until the current call to EVAL is about to
7565 return. Thus lower-level `EVAL`s are skipped over without leaving the
7566 mode. The usefulness of this mode in debugging is obvious.
7568 ### 20.7.7. FREE-RUN
7572 takes its argument out of single-step mode. Only the `PROCESS` that
7573 put *process* into single-step mode can take it out of the mode; if
7574 another `PROCESS` tries, `FREE-RUN` returns a `FALSE`.
7576 20.8. Sneakiness with PROCESSes
7577 -------------------------------
7579 `FRAME`s, `ENVIRONMENT`s, `TAG`s, and `ACTIVATION`s are specific to
7580 the `PROCESS` which created them, and each "knows its own father".
7581 **Any** `SUBR` which takes these objects as arguments can take one
7582 which was generated by **any** `PROCESS`, no matter where the `SUBR`
7583 is really applied. This provides a rather sneaky means of crossing
7584 between `PROCESS`es. The various cases are as follows:
7586 `GO`, `RETURN`, `AGAIN`, and `ERRET`, given arguments which lie in
7587 another `PROCESS`, each effectively "restarts" the `PROCESS` of its
7588 argument and acts as if it were evaluated over there. If the `PROCESS`
7589 in which it was executed is later `RESUME`d, it **returns** a value
7592 `SET`, `UNASSIGN`, `BOUND?`, `ASSIGNED?`, `LVAL`, `VALUE`, and `LLOC`,
7593 given optional `ENVIRONMENT` arguments which lie in another `PROCESS`,
7594 will gleefully change, or return, the local values of `ATOM`s in the
7595 other `PROCESS`. The optional argument can equally well be a
7596 `PROCESS`, `FRAME`, or `ACTIVATION` in another `PROCESS`; in those
7597 cases, each uses the `ENVIRONMENT` which is current in the place
7600 `FRAME`, `ARGS`, and `FUNCT` will be glad to return the `FRAME`s,
7601 argument `TUPLE`s, and applied Subroutine names of another `PROCESS`.
7602 If one is given a `PROCESS` (including `<ME>`) as an argument instead
7603 of a `FRAME`, it returns all or the appropriate part of the topmost
7604 `FRAME` on that `PROCESS`'s control stack.
7606 If `EVAL` is applied in `PROCESS` `P1` with an `ENVIRONMENT` argument
7607 from a `PROCESS` `P2`, it will do the evaluation **in `P1`** but with
7608 `P2`'s `ENVIRONMENT` (!). That is, the other `PROCESS`'s `LVAL`s, etc.
7609 will be used, but (1) any **new** `FRAME`s needed in the course of the
7610 evaluation will be created in `P1`; and (2) **`P1`** will be `RUNNING`
7611 -- not `P2`. Note the following: if the `EVAL` in `P1` eventually
7612 causes a `RESUME` of `P2`, `P2` could functionally return to below the
7613 point where the `ENVIRONMENT` used in `P1` is defined; a `RESUME` of
7614 `P1` at this point would cause an `ERROR` due to an invalid
7615 `ENVIRONMENT`. (Once again, `LEGAL?` can be used to forestall this.)
7620 1. A `RESUMABLE` `PROCESS` can be used in place of an `ENVIRONMENT`
7621 in any application. The "current" `ENVIRONMENT` of the `PROCESS`
7622 is effectively used.
7623 2. `FRAME`s and `ENVIRONMENT`s can be `CHTYPE`d arbitrarily to one
7624 another, or an `ACTIVATION` can be `CHTYPE`d to either of them,
7625 and the result "works". Historically, these different `TYPE`s were
7626 first used with different `SUBR`s -- `FRAME` with `ERRET`,
7627 `ENVIRONMENT` with `LVAL`, `ACTIVATION` with `RETURN` -- hence the
7628 invention of different `TYPE`s with similar properties.
7629 3. Bugs in multi-`PROCESS` programs usually exhibit a degree of
7630 subtlety and nastiness otherwise unknown to the human mind. If
7631 when attempting to work with multiple processes you begin to feel
7632 that you are rapidly going insane, you are in good company.
7634 Chapter 21. Interrupts
7635 ======================
7637 The Muddle interrupt handling facilities provide the ability to say
7638 the following: whenever "this event" occurs, stop whatever is being
7639 done at the time and perform "this action"; when "this action" is
7640 finished, continue with whatever was originally being done. "This
7641 event" can be things like the typing of a character at a terminal, a
7642 time interval ending, a `PROCESS` becoming blocked, or a
7643 program-defined and -generated "event". "This action" is the
7644 application of a specified `APPLICABLE` object to arguments provided
7645 by the Muddle interrupt system. The sets of events and actions can be
7646 changed in extremely flexible ways, which accounts for both the
7647 variety of `SUBR`s and arguments, and the rich interweaving of the
7648 topics in this chapter. Interrupt handling is a kind of parallel
7649 processing: a program can be divided into a "main-level" part and one
7650 or more interrupt handlers that execute only when conditions are ripe.
7652 21.1. Definitions of Terms
7653 --------------------------
7655 An **interrupt** is not an object in Muddle, but rather a class of
7656 events, for example, "ticks" of a clock, garbage collections, the
7657 typing of a character at a terminal, etc.
7659 An interrupt is said to **occur** when one of the events in its class
7662 An **external** interrupt is one whose occurrences are signaled to
7663 Muddle by the operating system, for example, "ticks" of a clock. An
7664 **internal** interrupt is one whose occurrences are detected by Muddle
7665 itself, for example, garbage collections. Muddle can arrange for the
7666 operating system to not signal occurrences of an external interrupt to
7667 it; then, as far as Muddle is concerned, that interrupt does not
7670 Each interrupt has a **name** which is either a `STRING` (for example,
7671 `"GC"`, `"CHAR"`, `"WRITE"`) or an `ATOM` with that `PNAME` in a
7672 special `OBLIST`, named `INTERRUPTS!-`. (This `OBLIST` is returned by
7673 `<INTERRUPTS>`.) Certain names must always be further specified by a
7674 `CHANNEL` or a `LOCATIVE` to tell **which** interrupt by that name is
7677 When an interrupt occurs, the interpreter looks for an association on
7678 the interrupt's name. If there is an association, its `AVALUE` should
7679 be an `IHEADER`, which heads a list of actions to be performed. In
7680 each `IHEADER` is the name of the interrupt with which the `IHEADER`
7681 is or was associated.
7683 In each `IHEADER` is an element telling whether it is disabled. If an
7684 `IHEADER` is **disabled**, then none of its actions is performed. The
7685 opposite of disabled is **enabled**. It is sometimes useful to disable
7686 an `IHEADER` temporarily, but removing its association with the
7687 interrupt's name is better than long-term disabling. There are `SUBR`s
7688 for creating an `IHEADER`, associating it with an interrupt, and later
7689 removing the association.
7691 In each `IHEADER` is a **priority**, a `FIX` greater than `0` which
7692 specifies the interrupt's "importance". The processing of a
7693 higher-priority (larger-numbered) interrupt will supersede the
7694 processing of a lower-priority (smaller-numbered) interrupt until the
7695 high-priority interrupt has been handled.
7697 In each `IHEADER` is a (possibly empty) list of `HANDLER`s. (This list
7698 is not a Muddle `LIST`.) Each `HANDLER` corresponds to an action to
7699 perform. There are `SUBR`s for creating a `HANDLER`, adding it to an
7700 `IHEADER`'s list, and later removing it.
7702 In each `HANDLER` is a function that we will call a **handler** (in
7703 lower case), despite possible confusion, because that is really the
7704 best name for it. An **action** consists of applying a handler to
7705 arguments supplied by the interrupt system. The number and meaning of
7706 the arguments depend on the name of the interrupt. In each `HANDLER`
7707 is an element telling in which `PROCESS` the action should be
7713 <EVENT name priority which>
7715 creates and returns an enabled `IHEADER` with no `HANDLER`s. The
7716 *name* may be an `ATOM` in the `INTERRUPTS` `OBLIST` or a `STRING`; if
7717 it is a `STRING`, `EVENT` does a `LOOKUP` or `INSERT` in
7718 `<INTERRUPTS>`. If there already is an `IHEADER` associated with
7719 *name*, `EVENT` just returns it, ignoring the given *priority*.
7721 *which* must be given only for certain *name*s:
7723 - It must be a `CHANNEL` if and only if *name* is `"CHAR"` (or
7724 `CHAR!-INTERRUPTS`). In this case it is the input `CHANNEL` from
7725 the (pseudo-)terminal or Network socket whose received characters
7726 will cause the interrupt to occur, or the output `CHANNEL` to the
7727 pseudo-terminal or Network socket whose desired characters will
7728 cause the interrupt to occur. (See below. Pseudo-terminals are not
7729 available in the Tenex and Tops-20 versions.)
7730 - The argument must be a `LOCATIVE` if and only if *name* is
7731 `"READ"` (or `READ!-INTERRUPTS`) or `"WRITE"` (or
7732 `WRITE!-INTERRUPTS`). In this case it specifies an object to be
7733 "monitored" for usage by (interpreted) Muddle programs (section
7736 If the interrupt is external, Muddle arranges for the operating system
7737 to signal its occurrences.
7739 21.3. HANDLER (the SUBR)
7740 ------------------------
7742 <HANDLER iheader applicable process>
7744 creates a `HANDLER`, adds it to the front of *iheader*'s `HANDLER`
7745 list (first action to be performed), and returns it as a value.
7746 *applicable* may be any `APPLICABLE` object that takes the proper
7747 number of arguments. (None of the arguments can be `QUOTE`d; they must
7748 all be evaluated at call time.) *process* is the `PROCESS` in which
7749 the handler will be applied, by default whatever `PROCESS` was running
7750 when the interrupt occurred.
7752 The value returned by the handler is ignored, unless it is of `TYPE`
7753 `DISMISS` (`PRIMTYPE` `ATOM`), in which case none of the remaining
7754 actions in the list will be performed.
7756 The processing of an interrupt's actions can terminate prematurely if
7757 a handler calls the `SUBR` `DISMISS` (see below.)
7764 removes the association between *iheader* and the name of its
7765 interrupt, and then disables *iheader* and returns it. (An error
7766 occurs if there is no association.) If the interrupt is external,
7767 Muddle arranges for the operating system not to signal its
7772 finds the `IHEADER` associated with *name* and proceeds as above,
7773 returning the `IHEADER`. *which* must be given only for certain
7774 *names*, as for `EVENT`. Caution: if you `<OFF "CHAR" ,INCHAN>`,
7775 Muddle will become deaf.
7779 returns *handler* after removing it from its list of actions. There is
7780 no effect on any other `HANDLER`s in the list.
7782 Now that you know how to remove `IHEADER`s and `HANDLER`s from their
7783 normal places, you need to know how to put them back:
7787 If *iheader* was previously disabled or disassociated from its name,
7788 `EVENT` will associate and enable it.
7790 <HANDLER iheader handler>
7792 If *handler* was previously removed from its list, `HANDLER` will add
7793 it to the front of *iheader*'s list of actions. Note that *process*
7794 cannot be specified.
7796 21.5. IHEADER and HANDLER (the TYPEs)
7797 -------------------------------------
7799 Both these `TYPE`s are of `PRIMTYPE` `VECTOR`, but they do not `PRINT`
7800 that way, since they are self-referencing. Instead they `PRINT` as
7802 #type most-interesting-component
7804 The contents of `IHEADER`s and `HANDLER`s can be changed by `PUT`, and
7805 the new values will then determine the behavior of Muddle.
7807 Before describing the elements of these `TYPE`s in detail, here are a
7808 picture and a Pattern, both purporting to show how they look:
7810 #IHEADER [name:atom or which
7812 *-----------> #HANDLER [*-----------> #HANDLER [#HANDLER []
7813 priority] <-------------* +------*
7814 applicable | applicable
7815 process] <-------+ process]
7817 <IHEADER <OR ATOM CHANNEL LOCATIVE>
7818 <OR '#LOSE 0 '#LOSE -1>
7819 <HANDLER HANDLER <OR HANDLER IHEADER> APPLICABLE PROCESS>
7824 The elements of an `IHEADER` are as follows:
7826 1. name of interrupt (`ATOM`, or `CHANNEL` if the name is `"CHAR"`,
7827 or `LOCATIVE` if the name is `"READ"` or `"WRITE"`)
7828 2. non-zero if and only if disabled
7829 3. first `HANDLER`, if any, else a zero-length `HANDLER`
7832 If you lose track of an `IHEADER`, you can get it via the association:
7834 - For `"CHAR"` interrupts, `<GET channel INTERRUPT>` returns the
7835 `IHEADER` or `#FALSE ()` if there is no association;
7836 `<EVENT "CHAR" 0 channel>` returns the `IHEADER`, creating it if
7837 there is no association.
7838 - For `"READ"` interrupts, `<GET locative READ!-INTERRUPTS>` returns
7839 the `IHEADER` or `#FALSE ()` if there is no association;
7840 `<EVENT "READ" 0 locative>` returns the `IHEADER`, creating it if
7841 there is no association.
7842 - For `"WRITE"` interrupts, `<GET locative WRITE!-INTERRUPTS>`
7843 returns the `IHEADER` or `#FALSE ()` if there is no association:
7844 `<EVENT "WRITE" 0 locative>` returns the `IHEADER`, creating it if
7845 there is no association.
7846 - Otherwise, the `IHEADER` is `PUT` on the name `ATOM` with the
7847 indicator `INTERRUPT`. Thus, for example,
7848 `<GET CLOCK!-INTERRUPTS INTERRUPT>` returns the `IHEADER` for the
7849 clock interrupt or `#FALSE ()` if there is no association;
7850 `<EVENT "CLOCK" 0>` returns the `IHEADER`, creating it if there is
7855 A `HANDLER` specifies a **particular** action for a **particular**
7856 interrupt. The elements of a `HANDLER` are as follows:
7858 1. next `HANDLER` if any, else a zero-length `HANDLER`
7859 2. previous `HANDLER` or the `IHEADER` (Thus the `HANDLER`s of a
7860 given interrupt form a "doubly-linked list" chaining between each
7861 other and back to the `IHEADER`.)
7862 3. handler to be applied (anything but `APPLICABLE` that evaluates
7863 its arguments -- the application is done not by `APPLY` but by
7864 `RUNINT`, which can take a `PROCESS` argument: see next line)
7865 4. `PROCESS` in which the handler will be applied, or `#PROCESS 0`,
7866 meaning whatever `PROCESS` was running when the interrupt occurred
7867 (In the former case, `RUNINT` is applied to the handler and its
7868 arguments in the currently running `PROCESS`, which causes an
7869 `APPLY` in the `PROCESS` stored in the `HANDLER`, which `PROCESS`
7870 must be `RESUMABLE`. The running `PROCESS` becomes `RESUMABLE`,
7871 and the stored `PROCESS` becomes `RUNNING`, but no other `PROCESS`
7872 variables (for example `RESUMER`) are changed.)
7877 <ON name applicable priority:fix process which>
7881 <HANDLER <EVENT name priority which>
7884 `ON` is a combination of `EVENT` and `HANDLER`: it creates (or finds)
7885 the `IHEADER`, associates and enables it, adds a `HANDLER` to the
7886 front the list (first to be performed), and returns the `HANDLER`.
7890 is effectively `<PUT iheader 2 #LOSE -1>`. Actually the `TYPE` `LOSE`
7891 is unimportant, but the `-1` signifies that *iheader* is disabled.
7895 is effectively `<PUT iheader 2 #LOSE 0>`. Actually the `TYPE` `LOSE`
7896 is unimportant, but the `0` signfies that *iheader* is enabled.
7898 21.7. Priorities and Interrupt Levels
7899 -------------------------------------
7901 At any given time there is a defined **interrupt level**. This is a
7902 `FIX` which determines which interrupts can really "interrupt" -- that
7903 is, cause the current processing to be suspended while their wants are
7904 satisfied. Normal, non-interrupt programs operate at an interrupt
7905 level of 0 (zero.) An interrupt is processed at an interrupt level
7906 equal to the interrupt's priority.
7908 ### 21.7.1. Interrupt Processing
7910 Interrupts "actually" only occur at well-defined points in time:
7911 during a call to a Subroutine, or at critical places within
7912 Subroutines (for example, during each iteration of `MAPF` on a `LIST`,
7913 which may be circular), or while a `PROCESS` is `"BLOCKED"` (see
7914 below). No interrupts can occur during garbage collection.
7916 What actually happens when an enabled interrupt occurs is that the
7917 priority of the interrupt is compared with the current interrupt
7918 level, and the following is done:
7920 If the priority is **greater than** the current interrupt level, the
7921 current processing is "frozen in its tracks" and processing of the
7922 action(s) specified for that interrupt begins.
7924 If the priority is less than or equal to the current interrupt level,
7925 the interrupt occurrence is **queued** -- that is, the fact that it
7926 occurred is saved away for processing when the interrupt level becomes
7929 When the processing of an interrupt's actions is completed, Muddle
7930 usually (1) "acts as if" the previously-existing interrupt level is
7931 restored, and processing continues on what was left off (perhaps for
7932 no time duration); and (2) "acts as if" any queued interrupt
7933 occurrences actually occurred right then, in their original order of
7936 ### 21.7.2. INT-LEVEL
7938 The `SUBR` `INT-LEVEL` is used to examine and change the current
7939 interrupt level directly.
7943 simply returns the current interrupt level.
7947 changes the interrupt level to its argument and returns the
7948 **previously**-existing interrupt level.
7950 If `INT-LEVEL` lowers the priority of the interrupt level, it does not
7951 "really" return until all queued occurrences of interrupts of higher
7952 priority than the target priority have been processed.
7954 Setting the `INT-LEVEL` extremely high (for example,
7955 `<INT-LEVEL <CHTPE <MIN> FIX>>`) effectively disables all interrupts
7956 (but occurrences of enabled interrupts will still be queued).
7958 If `LISTEN` or `ERROR` is called when the `INT-LEVEL` is not zero,
7959 then the typeout will be
7961 LISTENING-AT-LEVEL I PROCESS p INT-LEVEL i
7965 `DISMISS` permits a handler to return an arbitrary value for an
7966 arbitrary `ACTIVATION` at an arbitrary interrupt level. The call is as
7969 <DISMISS value:any activation int-level:fix>
7971 where only the *value* is required. If *activation* is omitted, return
7972 is to the place interrupted from, and *value* is ignored. If
7973 *int-level* is omitted, the `INT-LEVEL` prior to the current interrupt
7976 21.8. Specific Interrupts
7977 -------------------------
7979 Descriptions of the characteristics of particular "built-in" Muddle
7980 interrupts follow. Each is named by its `STRING` name. Expect this
7981 list to be incomplete yesterday.
7983 `"CHAR"` is currently the most complex built-in interrupt, because it
7984 serves duty in several ways. These different ways will be described in
7985 several different sections. All ways are concerned with characters or
7986 machine words that arrive or depart at unpredictable times, because
7987 Muddle is communicating with a person or another processor. Each
7988 `"CHAR"` `IHEADER` has a `CHANNEL` for the element that names the
7989 interrupt, and the mode of the `CHANNEL` tells what kinds of `"CHAR"`
7990 interrupts occur to be handled through that `IHEADER`.
7992 1. If the `CHANNEL` is for `INPUT`, "CHAR" occurs every time an
7993 "interesting" character (see below) is received from the
7994 `CHANNEL`'s real terminal, or any character is received from the
7995 `CHANNEL`'s pseudo-terminal, or a character or word is received
7996 from the `CHANNEL`'s Network socket, or indeed (in the ITS
7997 version) the operating system generates an interrupt for any
7999 2. If the `CHANNEL` is for output to a pseudo-terminal or Network
8000 socket, `"CHAR"` occurs every time a character or word is wanted.
8001 3. If the `CHANNEL` is for output to a terminal, `"CHAR"` occurs
8002 every time a line-feed character is output or (in the ITS version)
8003 the operating system generates a screen-full interrupt for the
8006 ### 21.8.1. "CHAR" received
8008 A handler for an input `"CHAR"` interrupt on a real terminal must take
8009 two arguments: the `CHARACTER` which was typed, and the `CHANNEL` on
8012 In the ITS version, the "interesting" characters are those "enabled
8013 for interrupts" on a real terminal, namely `^@` through `^G`, `^K`
8014 through `^_`, and `DEL` (that is, ASCII codes 0-7, 13-37, and 177
8017 In the Tenex and Tops-20 versions, the operating system can be told
8018 which characters typed on a terminal should cause this interrupt to
8019 occur, by calling the `SUBR` `ACTIVATE-CHARS` with a `STRING` argument
8020 containing those characters (no more than six, all with ASCII codes
8021 less than 33 octal). If called with no argument, `ACTIVATE-CHARS`
8022 returns a `STRING` containing the characters that currently interrupt.
8023 Initially, only `^G`, `^S`, and `^O` interrupt.
8025 An initial Muddle already has `"CHAR"` enabled on `,INCHAN` with a
8026 priority 8 (eight), the `SUBR` `QUITTER` for a handler to run in
8027 `#PROCESS 0` (the running `PROCESS`); this is how `^G` and `^S` are
8028 processed. In addition, every time a new `CHANNEL` is `OPEN`ed in
8029 `"READ"` mode to a terminal, a similar `IHEADER` and `HANDLER` are
8030 associated with that new `CHANNEL` automatically. These
8031 automatically-generated `IHEADER`s and `HANDLER`s use the standard
8032 machinery, and they can be `DISABLE`d or `OFF`ed at will. **However**,
8033 the `IHEADER` for `,INCHAN` should not be `OFF`ed: Muddle knows that
8034 `$` is typed only by an interrupt!
8036 Example: the following causes the given message to be printed out
8037 whenever a `^Y` is typed on `.INCHAN`:
8039 <SET H <HANDLER <GET .INCHAN INTERRUPT>
8040 #FUNCTION ((CHAR CHAN)
8041 #DECL ((VALUE) ANY (CHAR) CHARACTER (CHAN) CHANNEL)
8042 <AND <==? .CHAR !\^Y>
8043 <PRINC " [Some of the best friends are ^Ys.] ">>)>>$
8044 #HANDLER #FUNCTION **CHAR CHAN) ...)
8045 <+ 2 ^Y [Some of my best friends are ^Ys.] 2>$
8048 #HANDLER #FUNCTION (...)
8050 Note that occurrences of `"CHAR"` do **not** wait for the `$` to be
8051 typed, and the interrupting character is omitted from the input
8054 A `"CHAR"` interrupt can also be associated with an input `CHANNEL`
8055 open to a Network socket (`"NET"` device). A handler gets applied to a
8056 `NETSTATE` array (which see) and the `CHANNEL`.
8058 In the ITS version, a `"CHAR"` interrupt can also be associated with
8059 an input `CHANNEL` open to a pseudo-terminal ("STY" device and
8060 friends). An interrupt occurs when a character is available for input.
8061 These interrupts are set up in exactly the same way as real-terminal
8062 interrupts, except that a handler gets applied to only **one**
8063 argument, the `CHANNEL`. Pseudo-terminal are not available in the
8064 Tenex and Tops-20 versions.
8066 For any other flavor of ITS channel interrupt, a handler gets applied
8067 to only **one** argument, the `CHANNEL`.
8069 ### 21.8.2. "CHAR" wanted
8071 A `"CHAR"` interrupt can be associated with an output `CHANNEL` open
8072 to a Network socket (`"NET"` device). A handlers gets applied to a
8073 `NETSTATE` array (which see) and the `CHANNEL`.
8075 In the ITS version, a `"CHAR"` interrupt can also be associated with
8076 an output `CHANNEL` open to a pseudo-terminal (`"STY"` device and
8077 friends). An interrupt occurs when the program at the other end needs
8078 a character (and the operating-system buffer is empty). A handler gets
8079 applied to one argument, the `CHANNEL`. Pseudo-terminals are not
8080 available in the Tenex and Tops-20 versions.
8082 ### 21.8.3. "CHAR" for new line
8084 A handler for an output `"CHAR"` interrupt on a real terminal must
8085 take **one or two** arguments (using `"OPTIONAL"` or `"TUPLE"`): if
8086 two arguments are supplied by the interrupt system, they are the line
8087 number (`FIX`) and the `CHANNEL`, respectively, and the interrupt is
8088 for a line-feed; if only one argument is supplied (only in the ITS
8089 version), it is the `CHANNEL`, and the interrupt is for a full
8090 terminal screen. Note: the supplied line number comes from the
8091 `CHANNEL`, and it may not be accurate if the program alters it in
8092 subtle ways, for example, via `IMAGE` calls or special control
8093 characters. (The program can compensate by putting the proper line
8094 number into the `CHANNEL`.)
8098 `"GC"` occurs just **after** every garbage collection. Enabling this
8099 interrupt is the only way a program can know that a garbage collection
8100 has occurred. A handler for `"GC"` takes three arguments. The first is
8101 a FLOAT indicating the number of seconds the garbage collection took.
8102 The second argument is a FIX indicating the cause of the garbage
8103 collection, as follows (chapter 22):
8105 0. Program called GC.
8106 1. Movable storage was exhausted.
8107 2. Control stack overflowed.
8108 3. Top-level LVALs overflowed.
8109 4. GVAL vector overflowed.
8110 5. TYPE vector overflowed.
8111 6. Immovable garbage-collected storage was exhausted.
8112 7. Internal stack overflowed.
8113 8. Both control and internal stacks overflowed (rare).
8114 9. Pure storage was exhausted.
8115 10. Second, exhaustive garbage collection occurred.
8117 The third argument is an ATOM indicating what initiated the garbage
8118 collection: `GC-READ`, `BLOAT`, `GROW`, `LIST`, `VECTOR`, `SET`,
8119 `SETG`, `FREEZE`, `GC`, `NEWTYPE`, `PURIFY`, `PURE-PAGE-LOADER` (pure
8120 storage was exhausted), or `INTERRUPT-HANDLER` (stack overflow,
8123 ### 21.8.5. "DIVERT-AGC"
8125 `"DIVERT-AGC"` ("Automatic Garbage Collection") occurs just **before**
8126 a deferrable garbage collection that is needed because of exhausted
8127 movable garbage-collected storage. Enabling this interrupt is the only
8128 way a program can know that a garbage collection is about to occur. A
8129 handler takes two arguments: A `FIX` telling the number of machine
8130 words needed and an `ATOM` telling what initiated the garbage
8131 collection (see above). If it wishes, a handler can try to prevent a
8132 garbage collection by calling `BLOAT` with the `FIX` argument. If the
8133 pending request for garbage-collected storage cannot then be
8134 satisfied, a garbage collection occurs anyway. `AGC-FLAG` is `SET` to
8135 `T` while the handler is running, so that new storage requests do not
8136 try to cause a garbage collection.
8140 `"CLOCK"`, when enabled, occurs every half second (the ITS
8141 "slow-clock" tick.) It is not available in the Tenex or Tops-20
8142 versions. It wants handlers which take no arguments. Example:
8144 <ON "CLOCK" <FUNCTION () <PRINC "TICK ">> 1>
8146 ### 21.8.7. "BLOCKED"
8148 `"BLOCKED"` occurs whenever **any** `PROCESS` (not only the `PROCESS`
8149 which may be in a `HANDLER`) starts waiting or terminal input: that
8150 is, an occurrence indicates that somewhere, somebody did a `READ`,
8151 `READCHR`, `NEXTCHR`, `TYI`, etc. to a console. The handler for a
8152 `"BLOCKED"` interrupt should take one argument, namely the `PROCESS`
8153 which started waiting (which will also be the `PROCESS` in which the
8154 handler runs, if no specific one is in the `HANDLER`).
8156 Example: the following will cause Muddle to acquire a `*` prompting
8159 <ON "BLOCKED" #FUNCTION ((IGNORE) <PRINC !\*>) 5>
8161 ### 21.8.8. "UNBLOCKED"
8163 `"UNBLOCKED"` occurs whenever a `$` (`ESC`) is typed on a terminal if
8164 a program was hanging and waiting for input, or when a TYI call (which
8165 see) is satisfied. A handler takes one argument: the `CHANNEL` via
8166 which the `$` or character is input.
8168 ### 21.8.9. "READ" and "WRITE"
8170 `"READ"` and `"WRITE"` are associated with read or write references to
8171 Muddle objects. These interrupts are often called "monitors", and
8172 enabling the interrupt is often called "monitoring" the associated
8173 object. A "read reference" to an `ATOM`'s local value includes
8174 applying `BOUND?` or `ASSIGNED?` to the `ATOM`; similarly for a global
8175 value and `GASSIGNED?`. If the `INT-LEVEL` is too high when `"READ"`
8176 or `"WRITE"` occurs, an error occurs, because occurrences of these
8177 interrupts cannot be queued.
8179 Monitors are set up with `EVENT` or `ON`, using a locative to the
8180 object being monitored as the extra *which* argument, just as a
8181 `CHANNEL` is given for `"CHAR"`. A handler for `"READ"` takes two
8182 arguments: the locative and the `FRAME` of the function application
8183 that make the reference. A handler for `"WRITE"` takes three
8184 arguments: the locative, the new value, and the `FRAME`. For example:
8190 <ON "WRITE" <FUNCTION (OBJ VAL FRM)
8191 #DECL ((VALUE VAL ANY (OBJ) LOCATIVE (FRM) FRAME)
8193 <PRINC "Program changed ">
8201 #HANDLER FUNCTION (...)
8205 Program changed #LOCL 2 to 20 via #FRAME PUT
8210 ### 21.8.10. "SYSDOWN"
8212 `"SYSDOWN"` occurs when a system-going-down or system-revived signal
8213 is received from ITS. It is not available in the Tenex or Tops-20
8214 versions. If no `IHEADER` is associated and enabled, a warning message
8215 is printed on the terminal. A handler takes one argument: a `FIX`
8216 giving the number of thirtieths of a second until the shutdown (-1 for
8219 ### 21.8.11. "ERROR"
8221 In an effort to simplify error handling by programs, Muddle has a
8222 facility allowing errors to be handled like interrupts. `SETG`ing
8223 `ERROR` to a user function is a distasteful method, not safe if any
8224 bugs are around. An `"ERROR"` interrupt wants a handler that takes any
8225 number of arguments, via `"TUPLE"`. When an error occurs, handlers are
8226 applied to the `FRAME` of the `ERROR` call and the `TUPLE` of `ERROR`
8227 arguments. If a given handler "takes care of the error", it can
8228 `ERRET` with a value from the `ERROR` `FRAME`, after having done
8229 `<INT-LEVEL 0>`. If no handler takes care of the error, it falls into
8232 If an error occurs at an `INT-LEVEL` greater than or equal to that of
8233 the `"ERROR"` interrupt, real `ERROR` will be called, because
8234 `"ERROR"`interrupts cannot be queued.
8238 `"IPC"` occurs when a message is received on the ITS IPC device
8239 (chapter 23). It is not available in the Tenex and Tops-20 versions.
8241 ### 21.8.13. "INFERIOR"
8243 `"INFERIOR"` occurs when an inferior ITS process interrupts the Muddle
8244 process. It is not available in the Tenex and Tops-20 versions. A
8245 handler takes one argument: A `FIX` between `0` and `7` inclusive,
8246 telling which inferior process is interrupting.
8248 ### 21.8.14. "RUNT and "REALT"
8250 These are not available in the Tenex and Tops-20 versions.
8252 `"RUNT"`, if enabled, occurs **once**, *N* seconds of Muddle running
8253 time (CPU time) after calling `<RUNTIMER N:fix-or-float>`, which
8254 returns its argument. A handler takes no arguments. If `RUNTIMER` is
8255 called with no argument, it returns a `FIX`, the number of run-time
8256 seconds left until the interrupt occurs, or `#FALSE ()` if the
8257 interrupt is not going to occur.
8259 `"REALT"`, if enabled, occurs **every** *N* seconds of real-world time
8260 after calling `<REALTIMER N:fix-or-float>`, which returns its
8261 argument. A handler takes no arguments. `<REALTIMER 0>` tells the
8262 operating system not to generate real-time interrupts. If `REALTIMER`
8263 is called with no argument, it returns a `FIX`, the number of
8264 real-time seconds given in the most recent call to `REALTIMER` with an
8265 argument, or `#FALSE ()` if `REALTIMER` has not been called.
8267 ### 21.8.15. "Dangerous" Interrupts
8269 `"MPV"` ("memory protection violation") occurs if Muddle tries to
8270 refer to a storage address not in its address space. `"PURE"` occurs
8271 if Muddle tries to alter read-only storage. `"ILOPR"` occurs if Muddle
8272 executes and illegal instruction ("operator"). `"PARITY"` occurs if
8273 the CPU detects a parity error in Muddle's address space. All of these
8274 require a handler that takes one argument: the address (`TYPE` `WORD`)
8275 following the instruction that was being executed at the time.
8277 `"IOC"` occurs if Muddle tries to deal illegally with an I/O channel.
8278 A handler must take two arguments: a three-element `FALSE` like one
8279 that `OPEN` might return, and the `CHANNEL` that got the error.
8281 Ideally these interrupts should never occur. In fact, in the Tenex and
8282 Tops-20 versions, these interrupts always go to the superior operating
8283 system process instead of to Muddle. In the ITS version, if and when a
8284 "dangerous" interrupt does occur:
8286 - If no `IHEADER` is associated with the interrupt, then the
8287 interrupt goes to the superior operating system process.
8288 - If an `IHEADER` is associated but disabled, the error
8289 `DANGEROUS-INTERRUPT-NOT-HANDLED` occurs (`FILE-SYSTEM-ERROR` for
8291 - If an `IHEADER` is associated and enabled, but the `INT-LEVEL` is
8292 too high, the error `ATTEMPT-TO-DEFER-UNDEFERABLE-INTERRUPT`
8295 21.9. User-Defined Interrupts
8296 -----------------------------
8298 If the interrupt name given to `EVENT` or `ON` is **not** one of the
8299 standard predefined interrupts of Muddle, they will gleefully create
8300 an `ATOM` in `<INTERRUPTS>` and an associated `IHEADER` anyway, making
8301 the assumption that you are setting up a "program-defined" interrupt.
8303 Program-defined interrupts are made to occur by applying the `SUBR`
8306 <INTERRUPT name arg1 ... argN>
8308 where *name* is a `STRING`, `ATOM` or `IHEADER`, and *arg1* through
8309 *argN* are the arguments wanted by the handlers for the interrupt.
8311 If the interrupt specified by `INTERRUPT` is enabled, `INTERRUPT`
8312 returns `T`; otherwise it returns `#FALSE ()`. All the usual priority
8313 and queueing rules hold, so that even if `INTERRUPT` returns `T`, it
8314 is possible that nothing "really happened" (yet).
8316 `INTERRUPT` can also be used to cause "artificial" occurrences of
8317 standard predefined Muddle interrupts.
8319 Making a program-defined interrupt occur is similar to calling a
8320 handler directly, but there are differences. The value returned by a
8321 handler is ignored, so side effects must be used in order to
8322 communicate information back to the caller, other than whether any
8323 handler ran or will run. One good use for a program-defined interrupt
8324 is to use the priority and queueing machinery of `INT-LEVEL` to
8325 control the execution of functions that must not run concurrently. For
8326 example, if a `"CHAR"` handler just deposits characters in a buffer,
8327 then a function to process the buffered characters should probably run
8328 at a higher priority level -- to prevent unpredictable changes to the
8329 buffer during the processing -- and it is natural to invoke the
8330 processing with `INTERRUPT`.
8332 In more exotic applications, `INTERRUPT` can signal a condition to be
8333 handled by an unknown number of independent and "nameless" functions.
8334 The functions are "nameless" because the caller doesn't know their
8335 name, only the name of the interrupt. This programming style is
8336 modular and event-driven, and it is one way of implementing
8337 "heuristic" algorithms. In addition, each `HANDLER` has a `PROCESS` in
8338 which to run its handler, and so the different handlers for a given
8339 condition can do their thing in different environments quite easily,
8340 with less explicit control than when using `RESUME`.
8342 21.10. Waiting for Interrupts
8343 -----------------------------
8349 hangs interruptibly, without consuming any CPU time, potentially
8350 forever. `HANG` is nice for a program that cannot do anything until an
8351 interrupt occurs. If the optional *pred* is given, it is evaluated
8352 every time an interrupt occurs and is dismissed back into the `HANG`;
8353 if the result of evaluation is not `FALSE`, `HANG` unhangs and returns
8354 it as a value. If *pred* is not given, there had better be a named
8355 `ACTIVATION` somewhere to which a handler can return.
8359 <SLEEP time:fix-or-float pred>
8361 suspends execution, interruptibly, without consuming any CPU time, for
8362 *time* seconds, where *time* is non-negative, and then returns `T`.
8363 *pred* is the same as for `HANG`.
8365 Chapter 22. Storage Management
8366 ==============================
8368 The reason this chapter comes so late in this document is that, except
8369 for special cases, Muddle programs have their storage needs handled
8370 automatically. There is usually no need even to consider storage
8371 management, except as it affects efficiency (chapter 24). This chapter
8372 gives some explanation of why this is so, and covers those special
8373 means by which a program can assume control of storage management.
8375 The Muddle address space is divided into five parts, which are usually
8378 1. movable garbage-collected space,
8379 2. immovable space (both garbage-collected and not),
8380 3. user pure/page space,
8381 4. pure-`RSUBR` mapping space, and
8382 5. internal storage.
8384 Internal storage occupies both the highest and lowest addresses in the
8385 address space, and its size never changes as Muddle executes. The
8386 other spaces can vary in size according to the needs of the executing
8387 program. Generally the interpreter allocates a contiguous set of
8388 addresses for each space, and each space gradually fills up as new
8389 objects are created and as disk files are mapped in. The action taken
8390 when space becomes full varies, as discussed below.
8392 22.1. Movable Garbage-collected Storage
8393 ---------------------------------------
8395 Most storage used explicitly by Muddle programs is obtained from a
8396 pool of free storage managed by a "garbage collector". Storage is
8397 obtained from this pool by the `SUBR`s which construct objects. When a
8398 `SUBR` finds that the pool of available storage is exhausted, it
8399 automatically calls the garbage collector.
8401 The garbage collector has two algorithms available to it: the
8402 "copying" algorithm, which is used by default, and the "mark-sweep"
8403 algorithm. Actually, one often speaks of two separate garbage
8404 collectors, the "copying" one and the "mark-sweep" one, because each
8405 is an independent module that is mapped in to the interpreter's
8406 internal storage from disk only during garbage collection. For
8407 simplicity, this document speaks of "the" garbage collector, which has
8410 The garbage collector examines the storage pool and **marks** all the
8411 objects there, separating them into two classes: those which cannot
8412 possibly be referenced by a program, and those which can. The
8413 "copying" algorithm then copies the latter into one compact section of
8414 the pool, and the remainder of the pool is made available for newly
8415 constructed objects. The "mark-sweep" algorithm, instead, puts all
8416 objects in the former class (garbage) into "free lists", where the
8417 object-construction `SUBR`s can find them and re-use their storage.
8419 If the request for more storage still cannot be satisfied from
8420 reclaimed storage, the garbage collector will attempt to obtain more
8421 total storage from the operating system under which Muddle runs.
8422 (Also, if there is a gross superfluity of storage space, the garbage
8423 collector will politely return some storage to the operating system.)
8424 Only when the total system resources are exhausted will you finally
8427 Thus, if you just "forget about" an object, that is, lose all possible
8428 means of referencing it, its storage is automatically reclaimed.
8429 "Object" in this context includes that stack-structured storage space
8430 used in `PROCESS`es for functional application.
8432 ### 22.1.1. Stacks and Other Internal Vectors
8434 Control stacks are used in Muddle to control the changes in
8435 environment caused by calling and binding. Each active `PROCESS` has
8436 its own control stack. On this stack are stored `LVAL`s for `ATOM`s;
8437 `PRIMTYPE` `TUPLE`s, which are otherwise like `VECTOR`s; `PRIMTYPE`
8438 `FRAME`s, which are generated by calling Subroutines; and
8439 `ACTIVATION`s, which are generated by calling `FUNCTION`s with named
8440 `ACTIVATION`s, `PROG`, and `REPEAT`. `TAG` and `LLOC` can make `TAG`s
8441 and `LOCD`s (respectively) that refer to a specific place on a
8442 specific control stack. (`LEGAL?` returns `T` if and only if the
8443 portion of the control stack in which its argument is found or to
8444 which its argument refers is still active, or if its argument doesn't
8445 care about the control stack. The garbage collector may change a
8446 non-`LEGAL?` object to `TYPE` `ILLEGAL` before reclaiming it.) As the
8447 word "stack" implies, things can be put on it and removed from it at
8448 only one end, called the top. It has a maximum size (or depth), and
8449 attempting to put too many things on it will cause overflow. A stack
8450 is stored like a `VECTOR`, and it must be `GROW`n if and when it
8453 A control stack is actually two stacks in one. One section is used for
8454 "top-level" `LVAL`s -- those `SET` while the `ATOM` is not bound by
8455 any active Function's argument `LIST` or Subroutine's `SPECIAL`
8456 binding -- and the other section is used for everything else. Either
8457 section can overflow, of course. The top-level-`LVAL` section is below
8458 the other one, so that a top-level `LVAL` will be found only if the
8459 `ATOM` is not currently bound elsewhere, namely in the other section.
8461 Muddle also has an internal stack, used for calling and temporary
8462 storage within the interpreter and compiled programs. It too is stored
8463 like a `VECTOR` and can overflow. There are other internal vectors
8464 that can overflow: the "global vector" holds pairs ("slots") of
8465 `ATOM`s and corresponding `GVAL`s ("globally bound" or `GBOUND?` means
8466 that the `ATOM` in question is in this vector, whether or not it
8467 currently has a global value), and the "`TYPE` vector" holds `TYPE`
8468 names (predefined and `NEWTYPE`s) and how they are to be treated.
8470 22.2. Immovable Storage
8471 -----------------------
8473 ### 22.2.1. Garbage-collected: FREEZE
8475 In very special circumstances, such as debugging `RSUBR`s, you may
8476 need to prevent an object from being moved by the garbage collector.
8477 `FREEZE` takes one argument, of `PRIMTYPE` `VECTOR`, `UVECTOR`,
8478 `STRING`, `BYTES` or `TUPLE`. It copies its argument into non-moving
8479 garbage-collected space. `FREEZE` returns the copy `CHTYPE`d to its
8480 `PRIMTYPE`, except in the case of a `TUPLE`, which is changed to a
8483 ### 22.2.2. Non-garbage-collected: STORAGE (the PRIMTYPE)
8485 An object of `PRIMTYPE` `STORAGE` is really a frozen `UVECTOR` whose
8486 `UTYPE` is of `PRIMTYPE` `WORD`, but it is always pointed to by
8487 something internal to Muddle and thus is never garbage-collectible.
8488 The use of `FREEZE` is always preferable, except when for historical
8489 reasons a `STORAGE` is necessary.
8494 User pure/page space serves two purposes. First, when a user program
8495 `PURIFY`s (see below) Muddle objects, they are copied into this space.
8496 Second, so-called hand-crafted `RSUBR`s (assembled but not compiled)
8497 can call on the interpreter to map pages of disk files into this space
8498 for arbitrary purposes.
8500 Pure-`RSUBR` mapping space is used by the interpreter to dynamically
8501 map pages of pure compiled programs into and out of the Muddle address
8502 space. Pure code can refer to impure storage through the "transfer
8503 vector", another internal vector. This space is the most vulnerable to
8504 being compressed in size by the long-term growth of other spaces.
8506 Internal storage has both pure and impure parts. The interpreter
8507 program itself is pure and sharable, while impure storage is used for
8508 internal pointers, counters, and flags, for example, pointers to the
8509 boundaries of other spaces. In the pure part of this space are most of
8510 the `ATOM`s in an initial Muddle, along with their `OBLIST` buckets
8511 (`LIST`s) and `GVAL` slots (a pure extension of the global vector),
8512 where possible. A `SET` or `SETG` of a pure `ATOM` automatically
8513 impurifies the `ATOM` and as much of its `OBLIST` bucket as needs to
8516 22.4. Garbage Collection: Details
8517 ---------------------------------
8519 When either of the garbage-collected spaces (movable or immovable)
8520 becomes full, Muddle goes through the following procedure:
8522 1. A `"DIVERT-AGC"` interrupt occurs if the garbage collection can be
8523 deferred temporarily by shifting boundaries between storage spaces
8524 slightly. The interrupt handler may postpone a garbage collection
8525 by moving boundaries itself with a call to `BLOAT` (below).
8526 2. The garbage collector begins execution. The "copying" algorithm
8527 creates an inferior operating-system process (named `AGC` in the
8528 ITS version) whose address space is used to hold the new copies of
8529 non-garbage objects. Muddle accesses the inferior's address space
8530 through two pages ("frontier" and "window") in its internal space
8531 that are shared with the inferior. If the garbage collection
8532 occurred because movable garbage-collected space was exhausted,
8533 then the "mark-sweep" algorithm might be used instead (see below)
8534 and no inferior process is created.
8535 3. The garbage collector marks and moves all objects that can
8536 possibly be referenced hereafter. It begins with the `<MAIN>`
8537 `PROCESS` and the currently running `PROCESS` `<ME>`, considered
8538 as vectors containing the control stacks, object pointers in live
8539 registers, etc. Every object in these "`PROCESS` vectors" is
8540 marked "accessible", and every element of these objects (bindings,
8541 etc.), and so on recursively. The "copying" algorithm moves
8542 objects into the inferior process's address space as it marks
8544 4. If the garbage collection is "exhaustive" -- which is possible
8545 only in the "copying" algorithm -- then both the chain of
8546 associations and top-level local/global bindings are examined
8547 thoroughly, which takes more time but is more likely to uncover
8548 garbage therein. In a normal garbage collection these constructs
8549 are not treated specially.
8550 5. Finally, the "mark-sweep" algorithm sweeps through the storage
8551 space, adding unmarked objects to the internal free lists for
8552 later re-use. The "copying" algorithm maps the inferior process's
8553 address space into Muddle's own, replacing old garbagey with the
8554 new compact storage, and the inferior process is destroyed.
8559 <GC min:fix exh?:false-or-any ms-freq:fix>
8561 causes the garbage collector to run and returns the total number of
8562 words of storage reclaimed. All of its arguments are optional: if they
8563 are not supplied, a call to GC simply causes a "copying" garbage
8566 If *min* is explicitly supplied as an argument, a garbage-collection
8567 parameter is changed permanently before the garbage collector runs.
8568 *min* is the smallest number of words of "free" (unclaimed, available
8569 for use) movable garbage-collected storage the garbage collector will
8570 be satisfied with having after it is done. Initially it is 8192 words.
8571 If the total amount of reclaimed storage is less than *min*, the
8572 garbage collector will ask the operating system for enough storage (in
8573 1024 word blocks) to make it up. N.B.: the system may be incivil
8574 enough not to grant the request; in that case, the garbage collector
8575 will be content with what it has, **unless** that is not enough to
8576 satisfy a **pending** request for storage. Then it will inform you
8577 that it is losing. A large *min* will result in fewer total garbage
8578 collections, but they will take longer since the total quantity of
8579 storage to be dealt with will generally be larger. Smaller *min*s
8580 result in shorter, more frequent garbage collections.
8585 `BLOAT` is used to cause a temporary expansion of the available
8586 storage space with or without changing the garbage-collection
8587 parameters. `BLOAT` is particularly useful for avoiding unnecessary
8588 garbage collections when loading a large file. It will cause (at most)
8589 one garbage collection, at the end of which the available storage will
8590 be at least the amount specified in the call to `BLOAT`. (Unless, of
8591 course, the operating system is cranky and will not provide the
8592 storage. Then you will get an error. `<ERRET 1>` from this error will
8593 cause the `BLOAT` to return `1`, which usually just causes you to lose
8594 at a later time -- unless the operating system feels nicer when the
8595 storage is absolutely necessary.)
8597 A call to BLOAT looks like this:
8599 <BLOAT fre stk lcl glb typ sto pstk
8600 min plcl pglb ptyp imp pur dpstk dstk>
8602 where all arguments on the first line above are `FIX`, optional (`0`
8603 by default), and indicate the following:
8605 - *fre*: number of words of free movable storage desired (for
8606 `LIST`s, `VECTOR`s, `ATOM`s, etc.)
8607 - *stk*: number of words of free control-stack space desired (for
8608 functional applications and binding of `ATOM`s)
8609 - *lcl*: number of new top-level `LVAL`s for which to leave space
8610 (`SET`s of `ATOM`s which are not currently bound)
8611 - *glb*: number of new `GVAL`s for which to leave space (in the
8613 - *typ*: number of new `TYPE` definitions for which to leave space
8614 (in the `TYPE` vector)
8615 - *sto*: number of words of immovable garbage-collected storage
8617 - *pstk*: number of words of free internal-stack space desired (for
8618 `READ`ing large `STRING`s, and calling routines within the
8619 interpreter and compiled programs)
8621 Arguments on the second line are also `FIX` and optional, but they set
8622 garbage-collection parameters permanently, as follows:
8624 - *min*: as for `GC`
8625 - *plcl*: number of slots for `LVAL`s added when the space for
8626 top-level `LVAL`s is expanded (initially 64)
8627 - *pglb*: number of slots for `GVAL`s added when the global vector
8628 is grown (initially 64)
8629 - *ptyp*: number of slots for `TYPE`s added when the `TYPE` vector
8630 is grown (initially 32)
8631 - *imp*: number of words of immovable garbage-collected storage
8632 added when it is expanded (initially 1024)
8633 - *pur*: number of words reserved for pure compiled programs, if
8634 possible (initially 0)
8635 - *dpstk*: most desirable size for the internal stack, to prevent
8636 repeated shrinking and `GROW`ing (initially 512)
8637 - *dstk*: most desirable size for the control stack (initially 4096)
8639 `BLOAT` returns the actual number of words of free movable
8640 garbage-collected storage available when it is done.
8645 `BLOAT-STAT` can be used with `BLOAT` to "tune" the garbage collector
8646 to particular program requirements.
8648 <BLOAT-STAT length-27:uvector>
8650 fills the *uvector* with information about the state of storage of
8651 Muddle. The argument should be a `UVECTOR` of length 27 and `UTYPE`
8652 `FIX`. If `BLOAT-STAT` does not get an argument, it will provide its
8653 own `UVECTOR`. The information returned is as follows: the first 8
8654 elements indicate the number of garbage collections that are
8655 attributable to certain causes, and the other 19 give information
8656 about certain areas of storage. In detail:
8658 1. number of garbage collections caused by exhaustion of movable
8659 garbage-collected storage
8660 2. ditto by overflow of control stack(s)
8661 3. ditto by overflow of top-level-`LVAL` section of control stack(s)
8662 4. ditto by overflow of global vector
8663 5. ditto by overflow of `TYPE` vector
8664 6. ditto by exhaustion of immovable garbage-collected storage
8665 7. ditto by overflow of internal stack
8666 8. ditto by overflow of both stacks at the same time (rare)
8668 9. number of words of movable storage
8669 10. number of words of movable storage used since last `BLOAT-STAT`
8670 11. maximum number of words of movable storage ever existing
8671 12. number of words of movable storage used since Muddle began running
8672 13. maximum size of control stack
8673 14. number of words on control stack in use
8674 15. maximum size of control stack(s) ever reached
8675 16. number of slots for top-level `LVAL`s
8676 17. number of top-level `LVAL`s existing
8677 18. number of slots for `GVAL`s in global vector
8678 19. number of `GVAL`s existing
8679 20. number of slots for `TYPE`s in `TYPE` vector
8680 21. number of `TYPE`s existing
8681 22. number of words of immovable garbage-collected storage
8682 23. number of words of immovable storage unused
8683 24. size of largest unused contiguous immovable-storage block
8684 25. number of words on internal stack
8685 26. number of words on internal stack in use
8686 27. maximum size of internal stack ever reached
8693 ("garbage-collector monitor") determines whether or not the
8694 interpreter will hereafter print information on the terminal when a
8695 garbage collection starts and finishes, according to whether or not
8696 its argument is true. It returns the previous state. Calling it with
8697 no argument returns the current state. The initial state is false.
8699 When typing is enabled, the "copying" garbage collector prints, when
8702 GIN reason subr-that-caused:atom
8704 and, when it finishes:
8708 The "mark-sweep" garbage collector prints `MSGIN` and `MSGOUT` instead
8709 of `GIN` and `GOUT`.
8711 22.9. Related Subroutines
8712 -------------------------
8714 Two `SUBR`s, described next, use only part of the garbage-collector
8715 algorithm, in order to find all pointers to an object. `GC-DUMP` and
8716 `GC-READ`, as their names imply, also use part in order to translate
8717 between Muddle objects and binary representation thereof.
8719 ### 22.9.1. SUBSTITUTE
8721 <SUBSTITUTE new:any old:any>
8723 returns *old*, after causing a miniature garbage collection to occur,
8724 during which **all** references to *old* are changed so as to refer to
8725 *new*. Neither argument can be of `PRIMTYPE` `STRING` or `BYTES` or
8726 `LOCD` or live on the control stack, unless both are of the same
8727 `PRIMTYPE`. One `TYPE` name cannot be substituted for another. One of
8728 the few legitimate uses for it is to substitute the "right" `ATOM` for
8729 the "wrong" one, after `OBLIST`s have been in the wrong state. This is
8730 more or less the way `ATOM`s are impurified. It is also useful for
8731 unlinking `RSUBR`s. `SUBSTITUTE` returns *old* as a favor: unless you
8732 hang onto *old* at that point, it will be garbage-collected.
8737 <PURIFY any-1 ... any-N>
8739 returns its last argument, after causing a miniature garbage
8740 collection that results in all the arguments becoming pure and
8741 sharable, and ignored afterward by the garbage collector. No argument
8742 can live on the control stack or be of `PRIMTYPE` `PROCESS` or `LOCD`
8743 or `ASOC`. Sharing between operating-system processes actually occurs
8744 after a `SAVE`, if and when the `SAVE` file is `RESTORE`d.
8746 Chapter 23. Muddle as a System Process
8747 ======================================
8749 This chapter treats Muddle considered as executing in an
8750 operating-system process, and interactions between Muddle and other
8751 operating-system processes. See also section 21.8.13.
8756 `TIME` takes any number of arguments, which are evaluated but ignored,
8757 and returns a `FLOAT` giving the number of seconds of CPU time the
8758 Muddle process has used so far. `TIME` is often used in machine-level
8759 debugging to examine the values of its arguments, by having Muddle's
8760 superior process (say, DDT) plant a breakpoint in the code for `TIME`.
8767 returns a `STRING` which is the "user name" of Muddle's process. This
8768 is the "uname" process-control variable in the ITS version and the
8769 logged-in directory in the Tenex and Tops-20 versions.
8773 returns a `STRING` which is the "intended user name" of Muddle's
8774 process. This is the "xuname" process-control variable in the ITS
8775 version and identical to `<UNAME>` in the Tenex and Tops-20 versions.
8779 returns a `STRING` which is the "job name" of Muddle's process. This
8780 is the "jname" process-control variable in the ITS version and the
8781 `SETNM` name in the Tenex and Tops-20 versions. The characters belong
8782 to the "sixbit" or "printing" subset of ASCII, namely those between
8783 `<ASCII *40*>` and `<ASCII *137*>` inclusive.
8787 returns a `STRING` which is the "intended job name" of Muddle's
8788 process. This is the "xjname" process-control variable in the ITS
8789 version and identical to `<JNAME>` in the Tenex and Tops-20 versions.
8796 attempts to log out the process in which it is executed. It will
8797 succeed only if the Muddle is the top-level process, that is, it is
8798 running disowned or as a daemon. If it succeeds, it of course never
8799 returns. If it does not, it returns `#FALSE ()`.
8803 causes Muddle to stop running, in an orderly manner. In the ITS
8804 version, it is equivalent to a `.LOGOUT 1` instruction. In the Tenex
8805 and Tops-20 versions, it is equivalent to a control-C signal, and
8806 control passes to the superior process.
8808 <VALRET string-or-fix>
8810 ("value return") seldom returns. It passes control back up the process
8811 tree to the superior of Muddle, passing its argument as a message to
8812 that superior. If it does return, the value is `#FALSE ()`. If the
8813 argument is a `STRING`, it is passed to the superior as a command to
8814 be executed, via `.VALUE` in the ITS version and `RSCAN` in the
8815 Tops-20 version. If the argument is a `FIX`, it is passed to the
8816 superior as the "effective address" of a `.BREAK 16`, instruction in
8817 the ITS version and ignored in other versions.
8819 23.4. Inter-process Communication
8820 ---------------------------------
8822 All of the `SUBR`s in this section are available only in the ITS
8825 The IPC ("inter-process communication") device is treated as an I/O
8826 device by ITS but not explicitly so by Muddle: that is, it is never
8827 `OPEN`ed. It allows Muddle to communicate with other ITS processes by
8828 means of sending and receiving messages. A process identifies itself
8829 as sender or recipient of a message with an ordered pair of "sixbit"
8830 `STRING`s, which are often but not always `<UNAME>` and `<JNAME>`. A
8831 message has a "body" and a "type".
8833 ### 23.4.1. SEND and SEND-WAIT
8835 <SEND othern1 othern2 body type mynamel myname2>
8837 <SEND-WAIT othern1 othern2 body type mynamel myname2>
8839 both send an IPC message to any job that is listening for it as
8840 *othern1* *othern2*. *body* must be either a `STRING`, or a `UVECTOR`
8841 of objects of `PRIMTYPE` `WORD`. *type* is an optional `FIX`, `0` by
8842 default, which is part of the information the other guy receives. The
8843 last two arguments are from whom the message is to be sent. These are
8844 optional, and `<UNAME>` and `<JNAME>` respectively are used by
8845 default. `SEND` returns a `FALSE` if no one is listening, while
8846 `SEND-WAIT` hangs until someone wants it. Both return `T` if someone
8847 accepts the message.
8849 ### 23.4.2. The "IPC" Interrupt
8851 When your Muddle process receives an IPC message, `"IPC"` occurs
8852 (chapter 21). A handler is called with either four or six arguments
8853 gleaned from the message. *body*, *type*, *othern1*, and *othern2* are
8854 supplied only if they are not this process's `<UNAME>` and `<JNAME>`.
8856 There is a built-in `HANDLER` for the `"IPC"` interrupt, with a
8857 handler named `IPC-HANDLER` and `0` in the `PROCESS` slot. The handler
8858 prints out on the terminal the *body*, whom it is from, the *type* if
8859 not `0`, and whom it is to if not `<UNAME>` `<JNAME>`. If the *type*
8860 is `1` and the *body* is a `STRING`, then, after the message
8861 information is printed out, the `STRING` is `PARSE`d and `EVAL`uated.
8865 `<IPC-OFF>` stops all listening on the IPC device.
8869 <IPC-ON myname1 myname2>
8871 causes listening on the IPC device as *myname1* *myname2*. If no
8872 arguments are provided, listening is on `<UNAME>` `<JNAME>`. When a
8873 message arrives, `"IPC"` occurs.
8875 Muddle is initially listening as `<UNAME>` `<JNAME>` with the built-in
8876 `HANDLER` set up on the `"IPC"` interrupt with a priority of `1`.
8880 <DEMSIG daemon:string>
8882 signals to ITS (directly, not via the IPC device) that the daemon
8883 named by its argument should run now. It returns `T` if the daemon
8884 exists, `#FALSE ()` otherwise.
8886 Chapter 24. Efficiency and Tastefulness
8887 =======================================
8892 Actually, you make Muddle programs efficient by thinking hard about
8893 what they really make the interpreter **do**, and making them do less.
8894 Some guidelines, in order of decreasing expense:
8896 1. Free storage is expensive.
8897 2. Calling functions is expensive.
8898 3. `PROG` and `REPEAT` are expensive, except when compiled.
8902 1. Unnecessary use of free storage (creating needless `LIST`s,
8903 `VECTOR`s, `UVECTOR`s, etc.) will cause the garbage collector to
8904 run more often. This is **expensive!** A fairly large Muddle (for
8905 example, 60,000 36-bit words) can take ten seconds of PDP-10 CPU
8906 time for a garbage collection. Be especially wary of constructions
8907 like `(0)`. Every time that is evaluated, it creates a new
8908 one-element `LIST`; it is too easy to write such things when they
8909 aren't really necessary. Unless you are doing `PUT`s or `PUTREST`s
8910 on it, use `'(0)` instead.
8911 2. Sad, but true. Also generally ignored. If you call a function only
8912 once, or if it is short (less than one line), you are much better
8913 off in speed if you substitute its body in by hand. On the other
8914 hand, you may be much worse off in modularity. There are
8915 techniques for combining several `FUNCTION`s into one `RSUBR`
8916 (with `RSUBR-ENTRY`s), either during or after compilation, and for
8917 changing `FUNCTION`s into `MACRO`s.
8918 3. `PROG` is almost never necessary, given (a) `"AUX"` in
8919 `FUNCTION`s; (b) the fact that `FUNCTION`s can contain any number
8920 of `FORM`s; (c) the fact that `COND` clauses can contain any
8921 number of `FORM`s; and (d) the fact that new variables can be
8922 generated and initialized by `REPEAT`. However, `PROG` may be
8923 useful when an error occurs, to establish bindings needed for
8924 cleaning things up or interacting with a human.
8926 The use of `PROG` may be sensible when the normal flow of control can
8927 be cut short by unusual conditions, so that the program wants to
8928 `RETURN` before reaching the end of `PROG`. Of course, nested `COND`s
8929 can accomplish the same end, but deep nesting may tend to make the
8930 program unreadable. For example:
8933 <OR <SET TEMP <OK-FOR-STEP-1?>>
8936 <OR <SET TEMP <OK-FOR-STEP-2?>>
8940 could instead be written
8942 <COND (<OK-FOR-STEP-1?>
8944 <COND (<OK-FOR-STEP-2?>
8947 By the way, `REPEAT` is faster than `GO` in a `PROG`. The `<GO x>`
8948 `FORM` has to be separately interpreted, right? In fact, if you
8949 organize things properly you **very** seldom need a `GO`; using `GO`
8950 is generally considered "bad style", but in some cases it's needed.
8953 In many cases, a `REPEAT` can be replaced with a `MAPF` or `MAPR`, or
8954 an `ILIST`, `IVECTOR`, etc. of the form
8956 <ILIST .N '<SET X <+ .X 1>>
8958 which generates an `N`-element `LIST` of successive numbers starting
8961 Whether a program is interpreted or compiled, the first two
8962 considerations mentioned above hold: garbage collection and function
8963 calling remain expensive. Garbage collection is, clearly, exactly the
8964 same. Function calling is relatively more expensive. However, the
8965 compiler careth not whether you use `REPEAT`, `GO`, `PROG`, `ILIST`,
8966 `MAPF`, or whatnot: it all gets compiled into practically the same
8967 thing. However, the `REPEAT` or `PROG` will be slower if it has an
8968 `ACTIVATION` that is `SPECIAL` or used other than by `RETURN` or
8973 There follows an example of a `FUNCTION` that does many things wrong.
8974 It is accompanied by commentary, and two better versions of the same
8975 thing. (This function actually occurred in practice. Needless to say,
8976 names are withheld to protect the guilty.)
8978 Blunt comment: this is terrible. Its purpose is to output the
8979 characters needed by a graphics terminal to draw lines connecting a
8980 set of points. The points are specified by two input lists: `X` values
8981 and `Y` values. The output channel is the third argument. The actual
8982 characters for each line are returned in a `LIST` by the function
8985 <DEFINE PLOTVDSK (X Y CHN "AUX" L LIST)
8986 <COND (<NOT <==? <SET L <LENGTH .X>><LENGTH .Y> >>
8987 <ERROR "LENGTHS NOT EQUAL">)>
8990 <SET LIST (!.LIST !<TRANS <.N .X> <.N .Y>>)>
8991 <COND (<G? <SET N <+ .N 1>> .L><RETURN .N>)> >
8992 <REPEAT ((N 1) (L1 <LENGTH .LIST>))
8993 <PRINC <ASCII <.N .LIST>> .CHN>
8994 <COND (<G? <SET N <+ .N 1>> .L1>
8995 <RETURN "DONE">)> >>
8999 1. `LIST` is only temporarily necessary. It is just created and then
9001 2. Worse, the construct `(!.LIST !<TRANS ...>)` **copies** the
9002 previous elements of `LIST` every time it is executed!
9003 3. Indexing down the elements of `LIST` as in `<.N .LIST>` takes a
9004 long time, if the `LIST` is long. `<3 ...>` or `<4 ...>` is not
9005 worth worrying about, but `<10 ...>` is, and `<100 ...>` takes
9006 quite a while. Even if the indexing were not phased out, the
9007 compiler would be happier with `<NTH .LIST .N>`.
9008 4. The variable `CHN` is unnecessary if `OUTCHAN` is bound to the
9010 5. It is tasteful to call `ERROR` in the same way that F/SUBRs do.
9011 This includes using an `ATOM` from the `ERRORS` `OBLIST` (if one
9012 is appropriate) to tell what is wrong, and it includes identifying
9017 <DEFINE PLOTVDSK (X Y OUTCHAN)
9018 #DECL ((OUTCHAN <SPECIAL CHANNEL>)
9019 <COND (<NOT <==? <LENGTH .X> <LENGTH .Y>>>
9020 <ERROR VECTOR-LENGTHS-DIFFER!-ERRORS PLOTVDSK>)>
9023 <COND (<EMPTY? .X> <RETURN "DONE">)>
9024 <REPEAT ((OL <TRANS <1 .X> <1 .Y>>))
9025 <PRINC <ASCII <1 .OL>>>
9026 <COND (<EMPTY? <SET OL <REST .OL>>>
9031 Of course, if you know how long is the `LIST` that `TRANS` returns,
9032 you can avoid using the inner `REPEAT` loop and have explicit `PRINC`s
9033 for each element. This can be done even better by using `MAPF`, as in
9034 the next version, which does exactly the same thing as the previous
9035 one, but uses `MAPF` to do the `REST`ing and the end conditional:
9037 <DEFINE PLOTVDSK (X Y OUTCHAN)
9038 #DECL ((OUTCHAN <SPECIAL CHANNEL>)
9039 <COND (<NOT <==? <LENGTH .X> <LENGTH .Y>>>
9040 <ERROR VECTOR-LENGTHS-DIFFER!-ERRORS PLOTVDSK>)>
9041 <PRINC <ASCII 29>> <MAPF <>
9043 <MAPF <> #FUNCTION ((T) <PRINC <ASCII .T>>) <TRANS
9049 24.2. Creating a LIST in Forward Order
9050 --------------------------------------
9052 If you must create the elements of a `LIST` in sequence from first to
9053 last, you can avoid copying earlier ones when adding a later one to
9054 the end. One way is to use `MAPF` or `MAPR` with a first argument of
9055 `,LIST`: the elements are put on the control stack rather than in free
9056 storage, until the final call to `LIST`. If you know how many elements
9057 there will be, you can put them on the control stack yourself, in a
9058 `TUPLE` built for that purpose. Another way is used when `REPEAT` is
9061 <REPEAT ((FIRST (T)) (LAST .FIRST) ...)
9062 #DECL ((VALUE FIRST LAST) LIST ...)
9064 <SET LAST <REST <PUTREST .LAST (.NEW)>>>
9066 <RETURN <REST .FIRST>>>
9069 Here, `.LAST` always points to the current last element of the `LIST`.
9070 Because of the order of evaluation, the `<SET LAST ...>` could also be
9071 written `<PUTREST .LAST (SET LAST (.NEW)>>`.
9073 24.3. Read-only Free Variables
9074 ------------------------------
9076 If a Function uses the value of a free variable
9077 (`<GVAL unmanifest:atom>` or `<LVAL special:atom>`) without changing
9078 it, the compiled version may be more efficient if the value is
9079 assigned to a dummy `UNSPECIAL` `ATOM` in the Function's `"AUX"` list.
9080 This is true because an `UNSPECIAL` `ATOM` gets compiled into a slot
9081 on the control stack, which is accessible very quickly. The tradeoff
9082 is probably worthwhile if a *special* is referenced more than once, or
9083 if an *unmanifest* is referenced more than twice. Example:
9085 <DEFINE MAP-LOOKUP (THINGS "AUX" (DB ,DATA-BASE))
9086 #DECL ((VALUE) VECTOR (THINGS DB) <UNSPECIAL <PRIMTYPE LIST>>)
9087 <MAPF ,VECTOR <FUNCTION (T) <MEMQ .T .DB>> .THINGS>>
9089 24.4. Global and Local Values
9090 -----------------------------
9092 In the interpreter the sequence `,X .X ,X .X` is slower than
9093 `,X ,X .X .X` because of interference between the `GVAL` and `LVAL`
9094 mechanisms (appendix 1). Thus it is not good to use both the `GVAL`
9095 and `LVAL` of the same `ATOM` frequently, unless references to the
9096 `LVAL` will be compiled away (made into control stack references).
9098 24.5. Making Offsets for Arrays
9099 -------------------------------
9101 It is often the case that you want to attach some meaning to each
9102 element of an array and access it independently of other elements.
9103 Firstly, it is a good idea to use names (`ATOM`s) rather than integers
9104 (`FIX`es or even `OFFSET`s) for offsets into the array, to make future
9105 changes easier. Secondly, it is a good idea to use the `GVAL`s of the
9106 name `ATOM`s to remember the actual `FIX`es, so that the `ATOM`s can
9107 be `MANIFEST` for the compiler's benefit. Thirdly, to establish the
9108 `GVAL`s, both the interpreter and the compiler will be happier with
9109 `<SETG name offset>` rather than
9110 `<DEFINE name ("TUPLE" T) <offset !.T>>`.
9115 There are several ways in Muddle to store a table, that is, a
9116 collection of (names and) values that will be searched.
9117 Unsurprisingly, choosing the best way is often dictated by the size of
9118 the table and/or the nature of the (names and) values.
9120 For a small table, the names and values can be put in (separate)
9121 structures -- the choice of `LIST` or array being determined by
9122 volatility and limitability -- which are searched using `MEMQ` or
9123 `MEMBER`. This method is very space-efficient. If the table gets
9124 larger, and if the elements are completely orderable, a (uniform)
9125 vector can be used, kept sorted, and searched with a binary search.
9127 For a large table, where reasonably efficient searches are required, a
9128 hashing scheme is probably best. Two methods are available in Muddle:
9129 associations and `OBLIST`s.
9131 In the first method, `PUTPROP` and `GETPROP` are used, which are very
9132 fast. The number of hashing buckets is fixed. Duplicates are
9133 eliminated by `==?` testing. If it is necessary to use `=?` testing,
9134 or to find all the entries in the table, you can duplicate the table
9135 in a `LIST` or array, to be used only for those purposes.
9137 In the second method, `INSERT` and `LOOKUP` on a specially-built
9138 `OBLIST` are used. (If the names are not `STRING`s, they can be
9139 converted to `STRING`s using `UNPARSE`, which takes a little time.)
9140 The number of hashing buckets can be chosen for best efficiency.
9141 Duplicates are eliminated by `=?` testing. MAPF/R can be used to find
9142 all the entries in the table.
9147 The beauty of deeply-nested control structures in a single `FUNCTION`
9148 is definitely in the eye of the beholder. (`PPRINT`, a preloaded
9149 `RSUBR`, finds them trying. However, the compiler often produces
9150 better code from them.) **If** you don't like excessive nesting, then
9154 <COND (<0? .X> ...) ...>
9158 <COND (<0? <SET X ...>> ...) ...>
9176 You can see the nature of the choices. Nesting is still and all better
9179 Appendix 1. A Look Inside
9180 =========================
9182 This appendix tells about the mapping between Muddle objects and
9183 PDP-10 storage -- in other words, the way things look "on the inside".
9184 None of this information is essential to knowing how to program in
9185 Muddle, but it does give some reasons for capabilities and
9186 restrictions that otherwise you have to memorize. The notation and
9187 terminology get a little awkward in this discussion, because we are in
9188 a twilight zone between the worlds of Muddle objects and of bit
9189 patterns. In general the words and phrases appearing in diagrams refer
9190 to bit patterns not Muddle objects. A lower-case word (like "tuple")
9191 refers to the storage occupied by an object of the corresponding
9192 `PRIMTYPE` (like `TUPLE`).
9194 First some terminology needs discussion. The sine qua non of any
9195 Muddle object is a **pair** of 36-bit computer words. In general,
9196 lists consist of pairs chained together by pointers (addresses), and
9197 vectors consist of contiguous blocks of pairs. `==?` essentially tests
9198 two pairs to see whether they contain the same bit patterns.
9200 The first (lower-addressed) word of a pair is called the **`TYPE`
9201 word**, because it contains a numeric **`TYPE` code** that represents
9202 the object's `TYPE`. The second (higher-addressed) word of a pair is
9203 called the **value word**, because it contains (part of or the
9204 beginning of) the "data part" of the object. The `TYPE` word (and
9205 sometimes the value word) is considered to be made of a left half and
9206 a right half. We will picture a pair like this:
9208 ---------------------------------
9210 | - - - - - - - - - - - - - - - |
9212 ---------------------------------
9214 where a vertical bar in the middle of a word means the word's halves
9215 are used independently. You can see that the `TYPE` code is confined
9216 to the left half of the `TYPE` word. (Half-)words are sometimes
9217 subdivided into **fields** appropriate for the context; fields are
9218 also pictured as separated by vertical bars. The right half of the
9219 `TYPE` word is used for different purposes depending on the `TYPE` of
9220 the object and actual location of the value.
9222 Actually the 18-bit `TYPE` field is further decoded. The high-order
9223 (leftmost) bit is the mark bit, used exclusively by the garbage
9224 collector when it runs. The next two bits are monitor bits, used to
9225 cause `"READ"` and `"WRITE"` interrupts on read and write references
9226 to the pair. The next bit is used to differentiate between list
9227 elements and vector dope words. The next bit is unused but could be
9228 used in the future for an "execute" monitor. The remaining 13 bits
9229 specify the actual `TYPE` code. What `CHTYPE` does is to copy the pair
9230 and put a new `TYPE` code into the new pair.
9232 Each data `TYPE` (predefined and `NEWTYPE`s) must belong to one of
9233 about 25 "storage allocation classes" (roughly corresponding to Muddle
9234 `PRIMTYPE`s). These classes are characterized primarily by the manner
9235 in which the garbage collector treats them. Some of these classes will
9240 This class includes all data that are not pointers to some kind of
9241 structure. All external (program-available) `TYPE`s in this class are
9242 of `PRIMTYPE` `WORD`. Example:
9244 ---------------------------------
9246 | - - - - - - - - - - - - - - - |
9248 ---------------------------------
9252 The members of this class are all 18-bit pointers to list elements.
9253 All external `TYPE`s in this class are of `PRIMTYPE` `LIST`. Example:
9255 ---------------------------------
9257 | - - - - - - - - - - - - - - - |
9259 ---------------------------------
9261 where `pointer` is a pointer to the first list element. If there are
9262 no elements, `pointer` is zero; thus empty objects of `PRIMTYPE`
9263 `LIST` are `==?` if their `TYPE`s are the same.
9267 Members of this class are all "counting pointers" to blocks of
9268 two-word pairs. The right half of a counting pointer is an address,
9269 and the left half is the negative of the number of 36-bit words in the
9270 block. (This format is tailored to the PDP-10 `AOBJN` instruction.)
9271 The number of pairs in the block (`LENGTH`) is half that number, since
9272 each pair is two words. All external `TYPE`s in this class are of
9273 `PRIMTYPE` `VECTOR`. Example:
9275 ---------------------------------
9277 | - - - - - - - - - - - - - - - |
9278 | -2*length | pointer |
9279 ---------------------------------
9281 where `length` is the `LENGTH` of the `VECTOR` and `pointer` is the
9282 location of the start (the element selected by an `NTH` argument of 1)
9287 This class is the same as the previous one, except that the block
9288 contains objects all of the same `TYPE` without individual `TYPE`
9289 words. The `TYPE` code for all the elements is in vector dope words,
9290 which are at addresses just larger than the block itself. Thus, any
9291 object that carries information in its `TYPE` word cannot go into the
9292 block: `PRIMTYPE`s `STRING`, `BYTES`, `TUPLE` (and the corresponding
9293 locatives `LOCS`, `LOCB`, `LOCA`), `FRAME`, and `LOCD`. All external
9294 `TYPE`s in this class are of `PRIMTYPE` `UVECTOR`. Example:
9296 ---------------------------------
9298 | - - - - - - - - - - - - - - - |
9299 | -length | pointer |
9300 ---------------------------------
9302 where `length` is the `LENGTH` of the `UVECTOR` and `pointer` points
9303 to the beginning of the `UVECTOR`.
9305 "Byte String" and "Character String"
9307 These two classes are almost identical. Byte strings are byte pointers
9308 to strings of arbitrary-size bytes. `PRIMTYPE` `BYTES` is the only
9309 member of this class. Character strings are byte pointers to strings
9310 of ASCII characters. `PRIMTYPE` `STRING` is the only member of this
9311 class. Both of these classes consist of a length and a PDP-10 byte
9312 pointer. In the case of character strings, the byte-size field in the
9313 byte pointer is always seven bits per byte (hence five bytes per
9316 ---------------------------------
9318 | - - - - - - - - - - - - - - - |
9320 ---------------------------------
9322 where `length` is the `LENGTH` of the `STRING` (in bytes) and
9323 `byte-pointer` points to a byte just before the beginning of the
9324 string (an `ILDB` instruction is needed to get the first byte). A
9325 newly-created `STRING` always has `*010700*` in the left half of
9326 `byte-pointer`. Unless the string was created by `SPNAME`,
9327 `byte-pointer` points to a uvector, where the elements (characters) of
9328 the `STRING` are stored, packed together five to a word.
9332 This class gives the user program a handle on its control and
9333 variable-reference structures. All external `TYPE`s in this class are
9334 of `PRIMTYPE` `FRAME`. Three numbers are needed to designate a frame:
9335 a unique 18-bit identifying number, a pointer to the frame's storage
9336 on a control stack, and a pointer to the `PROCESS` associated with the
9339 ---------------------------------
9340 | FRAME |PROCESS-pointer|
9341 | - - - - - - - - - - - - - - - |
9342 | unique-id | frame-pointer |
9343 ---------------------------------
9345 where `PROCESS-pointer` points to the dope words of a `PROCESS`
9346 vector, and `unique-id` is used for validating (testing `LEGAL?`) the
9347 `frame-pointer`, which points to a frame for some Subroutine call on
9352 A tuple pointer is a counting pointer to a vector on the control
9353 stack. It may be a pointer to the arguments to a Subroutine or a
9354 pointer generated by the `"TUPLE"` declaration in a `FUNCTION`. Like
9355 objects in the previous class, these objects contain a unique
9356 identifying number used for validation. `PRIMTYPE` `TUPLE` is the only
9357 member of this class. Example:
9359 ---------------------------------
9360 | TUPLE | unique-id |
9361 | - - - - - - - - - - - - - - - |
9362 | -2*length | pointer |
9363 ---------------------------------
9365 Other Storage Classes
9367 The rest of the storage classes include strictly internal `TYPE`s and
9368 pointers to special kinds of lists and vectors like locatives, `ATOM`s
9369 and `ASOC`s. A pair for any `LOCATIVE` except a `LOCD` looks like a
9370 pair for the corresponding structure, except of course that the `TYPE`
9371 is different. A `LOCD` pair looks like a tuple pair and needs a word
9372 and a half for its value; the `unique-id` refers to a binding on the
9373 control stack or to the "global stack" if zero. Thus `LOCD`s are in a
9374 sense "stack objects" and are more restricted than other locatives.
9376 An `OFFSET` is stored with the `INDEX` in the right half of the value
9377 word and the Pattern in the left half. Since the Pattern can be either
9378 an `ATOM` or a `FORM`, the left half actually points to a pair, which
9379 points to the actual Pattern. The Patttern `ANY` is recognized as a
9380 special case: the left-half pointer is zero, and no pair is used.
9381 Thus, if you're making the production version of your program and want
9382 to save some storage, can do something like
9383 `<SETG FOO <PUT-DECL ,FOO ANY>>` for all `OFFSET`s.
9385 Basic Data Structures
9386 ---------------------
9390 List elements are pairs linked together by the right halves of their
9391 first words. The list is terminated by a zero in the right half of the
9392 last pair. For example the `LIST` `(1 2 3)` would look like this:
9396 | - - - - - | ----------- ----------- -----------
9397 | 0 | ------>| FIX | ------->| FIX | ------->| FIX | 0 |
9398 ------------- | - - - - | | - - - - | | - - - - |
9400 ----------- ----------- -----------
9402 The use of pointers to tie together elements explains why new elements
9403 can be added easily to a list, how sharing and circularity work, etc.
9404 The links go in only one direction through the list, which is why a
9405 list cannot be `BACK`ed or `TOP`ped: there's no way to find the
9408 Since some Muddle values require a word and a half for the value in
9409 the pair, they do not fit directly into list elements. This problem is
9410 solved by having "deferred pointers". Instead of putting the datum
9411 directly into the list element, a pointer to another pair is used as
9412 the value with the special internal `TYPE` `DEFER`, and the real datum
9413 is put in the deferred pair. For example the `LIST` `(1 "hello" 3)`
9414 would look like this:
9418 | - - - - - | ----------- ----------- -----------
9419 | 0 | ------>| FIX | ------->|DEFER| ------->| FIX | 0 |
9420 ------------- | - - - - | | - - - - | | - - - - |
9422 ----------- ----------- | -----------
9432 A vector is a block of contiguous words. More than one pair can point
9433 to the block, possibly at different places in the block; this is how
9434 sharing occurs among vectors. Pointers that are different arise from
9435 `REST` or `GROW`/`BACK` operations. The block is followed by two "dope
9436 words", at addresses just larger than the largest address in the
9437 block. Dope words have the following format:
9442 ---------------------------------
9444 | - - - - - - - - - - - - - - - |
9446 ---------------------------------
9448 The various fields have the following meanings:
9450 `type` -- The fourth bit from the left (the "vector bit", `40000`
9451 octal) is always one, to distinguish these vector dope words from a
9454 If the high-order bit is zero, then the vector is a `UVECTOR`, and the
9455 remaining bits specify the uniform `TYPE` of the elements. `CHUTYPE`
9456 just puts a new `TYPE` code in this field. Each element is limited to
9457 a one-word value: clearly `PRIMTYPE` `STRING`s and `BYTES`es and stack
9458 objects can't go in uniform vectors.
9460 If the high-order bit is one and the `TYPE` bits are zero, then this
9461 is a regular `VECTOR`.
9463 If the high-order bit is one and the `TYPE` bits are not all zero,
9464 then this is either an `ATOM`, a `PROCESS`, an `ASOC`, or a
9465 `TEMPLATE`. The special internal format of these objects will be
9466 described a little later in this appendix.
9468 `length` -- The high-order bit is the mark bit, used by the garbage
9469 collector. The rest of this field specifies the number of words in the
9470 block, including the dope words. This differs from the length given in
9471 pairs pointing to this vector, since such pairs may be the result of
9474 `grow` -- This is actually two nine-bit fields, specifying either
9475 growth or shrinkage at both the high and low ends of the vector. The
9476 fields are usually set only when a stack must be grown or shrunk.
9478 `gc` -- This is used by the garbage collector to specify where this
9479 vector is moving during compaction.
9481 Examples (numbers in octal): the `VECTOR` `[1 "bye" 3]` looks like:
9485 | - - - - - - | -----------------
9486 | -6 | ----------->| FIX | |
9487 --------------- | - - - - - - - |
9503 The `UVECTOR` `![-1 7 -4!]` looks like:
9507 | - - - - - - | -----------------
9508 | -3 | ----------->| -1 |
9509 --------------- -----------------
9521 Internally, atoms are special vector-like objects. An atom contains a
9522 value cell (the first two words of the block, filled in whenever the
9523 global or local value of the `ATOM` is referenced and is not already
9524 there), an `OBLIST` pointer, and a print name (`PNAME`), in the
9527 ---------------------------------
9529 ---------------------------------
9530 | pointer-to-value |
9531 ---------------------------------
9532 | pointer-to-oblist |
9533 ---------------------------------
9537 |(ASCII with NUL padding on end)|
9538 ---------------------------------
9539 | ATOM | valid-type |
9540 | - - - - - - - - - - - - - - - |
9542 ---------------------------------
9544 If the type field corresponds to `TYPE` `UNBOUND`, then the `ATOM` is
9545 locally and globally unbound. (This is different from a pair, where
9546 the same `TYPE` `UNBOUND` is used to mean unassigned.) If it
9547 corresponds to `TYPE` `LOCI` (an internal `TYPE`), then the value cell
9548 points either to the global stack, if `bindid` is zero, or to a local
9549 control stack, if `bindid` is non-zero. The `bindid` field is used to
9550 verify whether the local value pointed to by the value cell is valid
9551 in the current environment. The `pointer-to-OBLIST` is either a
9552 counting pointer to an oblist (uvector). a positive offset into the
9553 "transfer vector" (for pure `ATOM`s), or zero, meaning that this
9554 `ATOM` is not on an `OBLIST`. The `valid-type` field tells whether or
9555 not the `ATOM` represents a `TYPE` and if so the code for that `TYPE`:
9556 `grow` values are never needed for atoms.
9560 Associations are also special vector-like objects. The first six words
9561 of the block contain `TYPE`/value pairs for the `ITEM`, `INDICATOR`
9562 and `AVALUE` of the `ASOC`. The next word contains forward and
9563 backward pointers in the chain for that bucket of the association hash
9564 table. The last word contains forward and backward pointers in the
9565 chain of all the associations.
9567 ---------------------------------
9569 | - - - - - - - - - - - - - - - |
9571 ---------------------------------
9573 | - - - - - - - - - - - - - - - |
9575 ---------------------------------
9577 | - - - - - - - - - - - - - - - |
9579 ---------------------------------
9580 | bucket-chain-pointers |
9581 ---------------------------------
9582 | association-chain-pointers |
9583 ---------------------------------
9585 | - - - - - - - - - - - - - - - |
9587 ---------------------------------
9591 A `PROCESS` vector looks exactly like a vector of `TYPE`/value pairs.
9592 It is different only in that the garbage collector treats it
9593 differently from a normal vector, and it contains extremely volatile
9594 information when the `PROCESS` is `RUNNING`.
9598 In a template, the number in the type field (left half or first dope
9599 word) identifies to which "storage allocation class" this `TEMPLATE`
9600 belongs, and it is used to find PDP-10 instructions in internal tables
9601 (frozen uvectors) for performing `LENGTH`, `NTH`, and `PUT` operations
9602 on any object of this `TYPE`. The programs to build these tables are
9603 not part of the interpreter, but the interpreter does know how to use
9604 them properly. The compiler can put these instructions directly in
9605 compiled programs if a `TEMPLATE` is never `REST`ed; otherwise it must
9606 let the interpreter discover the appropriate instruction. The value
9607 word of a template pair contains, not a counting pointer, but the
9608 number of elements that have been `REST`ed off in the left half and a
9609 pointer to the first dope word in the right half.
9614 Accumulators with symbolic names `AB`, `TB`, and `TP` are all pointers
9615 into the `RUNNING` `PROCESS`'s control stack. `AB` ("argument base")
9616 is a pointer to the arguments to the Subroutine now being run. It is
9617 set up by the Subroutine-call mediator, and its old value is always
9618 restored after a mediated Subroutine call returns. `TB` ("temporaries
9619 base") points to the frame for the running Subroutine and also serves
9620 as a stack base pointer. The `TB` pointer is really all that is
9621 necessary to return from a Subroutine -- given a value to return, for
9622 example by `ERRET` -- since the frame specifies the entire state of
9623 the calling routine. `TP` ("temporaries pointer") is the actual stack
9624 pointer and always points to the current top of the control stack.
9626 While we're on the subject of accumulators, we might as well be
9627 complete. Each accumulator contains the value word of a pair, the
9628 corresponding `TYPE` words residing in the `RUNNING` `PROCESS` vector.
9629 When a `PROCESS` is not `RUNNING` (or when the garbage collector is
9630 running), the accumulator contents are stored in the vector, so that
9631 the Objects they point to look like elements of the `PROCESS` and thus
9632 are not garbage-collectible.
9634 Accumulators `A`, `B`, `C`, `D`, `E` and `O` are used almost entirely
9635 as scratch accumulators, and they are not saved or restored across
9636 Subroutine calls. Of course the interrupt machinery always saves these
9637 and all other accumulators. `A` and `B` are used to return a pair as
9638 the value of a Subroutine call. Other than that special feature, they
9639 are just like the other scratch accumulators.
9641 `M` and `R` are used in running `RSUBR`s. `M` is always set up to
9642 point to the start of the `RSUBR`'s code, which is actually just a
9643 uniform vector of instructions. All jumps and other references to the
9644 code use `M` as an index register. This makes the code
9645 location-insensitive, which is necessary because the code uvector will
9646 move around. `R` is set up to point to the vector of objects needed by
9647 the `RSUBR`. This accumulator is necessary because objects in
9648 garbage-collected space can move around, but the pointers to them in
9649 the reference vector are always at the same place relative to its
9652 `FRM` is the internal frame pointer, used in compiled code to keep
9653 track of pending Subroutine calls when the control stack is heavily
9654 used. `P` is the internal-stack pointer, used primarily for internal
9655 calls in the interpreter.
9657 One of the nicest features of the Muddle environment is the uniformity
9658 of the calling and returning sequence. All Subroutines -- both
9659 built-in F/SUBRs and compiled `RSUBR(-ENTRY)`s -- are called in
9660 exactly the same way and return the same way. Arguments are always
9661 passed on the control stack and results always end up in the same
9662 accumulators. For efficiency reasons, a lot of internal calls within
9663 the interpreter circumvent the calling sequence. However, all calls
9664 made by the interpreter when running user programs go through the
9665 standard calling sequence.
9667 A Subroutine call is initiated by one of three UUOs (PDP-10
9668 instructions executed by software rather than hardware). `MCALL`
9669 ("Muddle call") is used when the number of arguments is known at
9670 assemble or compile time, and this number is less than 16. `QCALL`
9671 ("quick call") may be used if, in addition, an `RSUBR(-ENTRY)` is
9672 being called that can be called "quickly" by virtue of its having
9673 special information in its reference vector. `ACALL` ("accumulator
9674 call") is used otherwise. The general method of calling a Subroutine
9675 is to `PUSH` (a PDP-10 instruction) pairs representing the arguments
9676 onto the control stack via `TP` and then either (1) `MCALL` or `QCALL`
9677 or (2) put the number of arguments into an accumulator and `ACALL`.
9678 Upon return the object returned by the Subroutine will be in
9679 accumulators `A` and `B`, and the arguments will have been `POP`ped
9680 off the control stack.
9682 The call mediator stores the contents of `P` and `TP` and the address
9683 of the calling instruction in the current frame (pointed to by `TB`).
9684 It also stores Muddle's "binding pointer" to the topmost binding in
9685 the control stack. (The bindings are linked together through the
9686 control stack so that searching through them is more efficient than
9687 looking at every object on the stack.) This frame now specifies the
9688 entire state of the caller when the call occurred. The mediator then
9689 builds a new frame on the control stack and stores a pointer back to
9690 the caller's frame (the current contents of `TB`), a pointer to the
9691 Subroutine being called, and the new contents of `AB`, which is a
9692 counting pointer to the arguments and is computed from the information
9693 in the `MCALL` or `QCALL` instruction or the `ACALL` accumulator. `TB`
9694 is then set up to point to the new frame, and its left half is
9695 incremented by one, making a new `unique-id`. The mediator then
9696 transfers control to the Subroutine.
9698 A control stack frame has seven words as shown:
9700 ---------------------------------
9701 | ENTRY | called-addr |
9702 ---------------------------------
9703 | unique-id | prev frame |
9704 ---------------------------------
9705 | argument pointer |
9706 ---------------------------------
9707 | saved binding pointer |
9708 ---------------------------------
9710 ---------------------------------
9712 ---------------------------------
9713 | saved calling address |
9714 ---------------------------------
9716 The first three words are set up during the call to the Subroutine.
9717 The rest are filled in when this routine calls another Subroutine. The
9718 left half of `TB` is incremented every time a Subroutine call occurs
9719 and is used as the `unique-id` for the frame, stored in frame and
9720 tuple pairs as mentioned before. Obviously this `id` is not strictly
9721 unique, since each 256K calls it wraps around to zero. The right half
9722 of `TB` is always left pointing one word past the
9723 saved-calling-address word in the frame. `TP` is also left pointing at
9724 that word, since that is the top of the control stack at Subroutine
9725 entry. The arguments to the called Subroutine are below the frame on
9726 the control stack (at lower storage addresses), and the temporaries
9727 for the called Subroutine are above the frame (at higher storage
9728 addresses). These arguments and temporaries are just pairs stored on
9729 the control stack while needed: they are all that remain of
9730 `UNSPECIAL` values in compiled programs.
9732 The following figure shows what the control stack might look like
9733 after several Subroutine calls.
9743 ----------------- <--
9752 | frame for S2 | ---
9753 ----------------- <------
9760 | frame for S3 | -------
9769 The above figure shows the frames all linked together through the
9770 control stack (the "execution path"), so that it is easy to return to
9771 the caller of a given Subroutine (`ERRET` or `RETRY`).
9773 Subroutine exit is accomplished simply by the call mediator, which
9774 loads the right half of `TB` from the previous frame pointer, restores
9775 the "binding pointer", `P`, and `TP`, and transfers control back to
9776 the instruction following the saved calling address.
9781 All local `ATOM` values are kept on the control stack of the `PROCESS`
9782 to which they are local. As described before, the atom contains a word
9783 that points to the value on the control stack. The pointer is actually
9784 to a six-word "binding block" on the control stack. Binding blocks
9785 have the following format:
9787 ---------------------------------
9788 | BIND or UBIND | prev |
9789 ---------------------------------
9791 ---------------------------------
9793 | - - - - - - - - - - - - - - - |
9795 ---------------------------------
9796 | decl | unique-id |
9797 ---------------------------------
9798 | previous-binding |
9799 ---------------------------------
9803 - `BIND` means this is a binding for a `SPECIAL` `ATOM` (the only
9804 kind used by compiled programs), and `UBIND` means this is a
9805 binding for an `UNSPECIAL` `ATOM` -- for `SPECIAL` checking by the
9807 - `prev` points to the closest previous binding block for any `ATOM`
9808 (the "access path" -- `UNWIND` objects are also linked in this
9810 - `decl` points to a `DECL` associated with this value, for
9811 `SET(LOC)` to check;
9812 - `unique-id` is used for validation of this block; and
9813 - `previous-binding` points to the closest previous binding for this
9814 `ATOM` (used in unbinding).
9816 Bindings are generated by an internal subroutine called `SPECBIND`
9817 (name comes from `SPECIAL`). The caller to `SPECBIND` `PUSH`es
9818 consecutive six-word blocks onto the control stack via `TP` before
9819 calling `SPECBIND`. The first word of each block contains the `TYPE`
9820 code for `ATOM` in its left half and all ones in its right half.
9821 `SPECBIND` uses this bit pattern to identify the binding blocks.
9822 `SPECBIND`'s caller also fills in the next three words and leaves the
9823 last two words empty. `SPECBIND` fills in the rest and leaves the
9824 "binding pointer" pointing at the topmost binding on the control
9825 stack. `SPECBIND` also stores a pointer to the current binding in the
9826 value cell of the atom.
9828 Unbinding is accomplished during Subroutine return. When the previous
9829 frame is being restored, the call mediator checks to see if the saved
9830 "binding pointer" and the current one are different; if they are,
9831 `SPECSTORE` is called. `SPECSTORE` runs through the binding blocks,
9832 restoring old value pointers in atoms until the "binding pointer" is
9833 equal to the one saved in the frame.
9835 Obviously variable binding is more complicated than this, because
9836 `ATOM`s can have both local and global values and even different local
9837 values in different `PROCESS`es. The solution to all of these
9838 additional problems lies in the `bindid` field of the atom. Each
9839 `PROCESS` vector also contains a current `bindid`. Whenever an ATOM's
9840 local value is desired, the `RUNNING` `PROCESS`'s `bindid` is checked
9841 against that of the atom: if they are the same, the atom points to the
9842 current value; if not, the current `PROCESS`'s control stack must be
9843 searched to find a binding block for this `ATOM`. This binding scheme
9844 might be called "shallow binding". The searching is facilitated by
9845 having all binding blocks linked together. Accessing global variables
9846 is accomplished in a similar way, using a `VECTOR` that is referred to
9847 as the "global stack". The global stack has only an `ATOM` and a value
9848 slot for each variable, since global values never get rebound.
9850 `EVAL` with respect to a different environment causes some additional
9851 problems. Whenever this kind of `EVAL` is done, a brand new `bindid`
9852 is generated, forcing all current local value cells of atoms to appear
9853 invalid. Local values must now be obtained by searching the control
9854 stack, which is inefficient compared to just pulling them out of the
9855 atoms. (The greatest inefficiency occurs when an `ATOM`'s `LVAL` is
9856 never accessed twice in a row in the same environment.) A special
9857 block is built on the control stack and linked into the binding-block
9858 chain. This block is called a "skip block" or "environment splice",
9859 and it diverts the "access path" to the new environment, causing
9860 searches to become relative to this new environment.