1 % The Muddle Programming Environment
5 MIT Technical Report 294
7 Laboratory for Computer Science
8 Massachusetts Institute of Technology
10 Cambridge, Massachusetts 02139
14 This book was originally published in the United States in 1980
15 without a copyright notice and without subsequent registration with
16 the U.S. Copyright Office within 5 years. Doing at least one of those
17 was a requirement of United States copyright law at that time [^1].
18 This book is therefore in the public domain in the United States for
19 failure to comply with the required formalities. This means you're
20 free to download, modify and redistribute this book. People outside of
21 the United States must check the copyright laws of their country
22 before downloading or redistributing.
24 [^1]: <http://copyright.cornell.edu/resources/publicdomain.cfm>
28 The Muddle language is described in "The Muddle Programming Language",
29 but in addition to the language itself, there is a rich and varied
30 collection of software written in the language which facilitates the
31 writing of programs and systems of programs in Muddle. The information
32 describing this programming environment has been contained in various
33 documents, some out of print or out of date, and in supplemental disk
34 files describing changes and additions. Some of the packages of
35 functions used to deal with Muddle code have never been formally
36 documented. This manual brings together some of that scattered
39 The document's purpose is to flesh out the description of the language
40 contained in "The Muddle Programming Language", giving a fuller
41 description of the program writing and debugging aids available to
42 Muddle users, to describe the methods for producing code usable by
43 others, to describe the Muddle compiler and the many other techniques
44 for producing and speeding up Muddle object code.
46 The imagined reader of this document is someone who has read "The
47 Muddle Programming Language", and now proposes to write programs in
48 Muddle, possibly even very large programs. Muddle packages that they
49 would find useful in the process of doing so are documented here:
50 editors, debuggers, etc. Packages that they might wish to use within
51 their program are not included: data-management systems, command
54 This document is highly self-referent, as many of the components of
55 the Muddle programming environment refer to reach other and adhere to
56 the same conventions. Additionally, this document assumes that the
57 read is familiar with the language itself (at least to some degree)
58 and with the ITS, TENEX, or TOPS-20 operating systems.
62 The programs described in this document are the products of many years
63 of effort by many people. Most have been "touched" by several
64 programmers, added to and improved over the years.
66 Some of the people responsible for the programs mentioned in the
67 document are Chris Reeve (Muddle, the compiler, `GLUE`); Brian
68 Berkowitz (Muddle, the compiler, `TEMPLATE`, `SUBRFY`); Bruce Daniels
69 (Muddle, the compiler, `PACKAGE`, `PPRINT`, `DEBUGR`, `ASSEM`); Tim
70 Anderson (`PACKAGE`, the Library, `FINDATOM`, `DFL`, Combat, Mudinq);
71 Neal Ryan (`EDIT`, `PDUMP`, the IPC interface); Marc Blank (Mat,
72 Muxicom, `MONITR`, Combat, `EDIT`, `CURSOR`); Dave Lebling (`CRITIC`,
73 `EDIT`); Michael Broos (the Library); Roger Banks (`TRACE`); Greg
74 Pfister (`PPRINT`); Joel Berez (`EDIT`).
76 Most of the documentation in this manual is from published and
77 unpublished memos of the Programming Technology Division of the M.I.T.
78 Laboratory for Computer Science. As a general rule, updates and
79 revisions to this and other PTD documents concerning Muddle are
80 available online in the directory "`MUDMAN`" at MIT-DMS.
84 Anything which is written in the Muddle language or which is typed on
85 a computer console appears here in in a typewriter font, as in
86 `PPRINT` while a metasyntactic variable -- something to be replaced in
87 actual use by something else -- appears as *channel*, in an italic
88 font. Where a meta-syntactic variable is being used to denote a
89 required argument to some function, it appears as before, but in bold,
92 In the argument templates of Muddle functions, the individual
93 arguments are often given in the form *argument:type*, where
94 *argument* is a "descriptive" name for the argument, and *type* is its
95 Muddle type (or range of types). In such cases, the "type" *boolean*
96 indicates an argument that is only examined for truth or falsity, and
97 not for any of its other qualities. Such arguments in Muddle are often
98 declared `<OR ATOM FALSE>`.
100 Finally, file names are given as though for the ITS operating system:
102 device:sname;fnm1 fnm2
104 The analogous specification for TENEX or TOPS-20 would be
106 device:<sname>fnm1,fnm2
108 Note that in the TENEX/TOPS-20 version of Muddle, the *fnm2* (which
109 may include the *generation* number, *protection* and *account*
110 fields) is by default `MUD` as opposed to \> for the ITS version.
112 # 1\. Overview of the Muddle Programming Environment
114 The part of the Muddle programming environment described in this
115 document are primarily those dealing with the writing, debugging,
116 sharing, and maintenance of code and programs written in Muddle. Most
117 of the packages described herein are written in Muddle themselves:
118 some are assembly language programs useful to Muddle programmers.
120 The document is divided into chapters dealing with the major issues
121 facing the notice (or even the experienced) Muddle programmer:
123 - **The Package System** introduces the standard mechanism for
124 lexical blocking and therefore, sharing of Muddle code.
125 Understanding its use is fundamental to writing Muddle programs.
127 - **Program Writing And Debugging Aids** is the largest chapter. It
128 covers mechanisms for loading, dumping, editing and debugging
129 Muddle code, whether interpreted or compiled, in a development or
132 - **The Library System** discusses the usage of libraries of Muddle
135 - **The Compiler** includes the specifics of interaction with the
136 Muddle compiler, as well as an overview of the theory behind its
139 - **Making It Run Faster** covers the various methods for speeding
140 up "production" Muddle code by removing mediated calls and
141 compacting data structures.
143 - **The Assembler** documents the Muddle assembler and some methods
144 of debugging binary code.
146 - **Informational Aids** discusses a few programs, mostly written in
147 assembly language, rather than Muddle, which are useful to the
150 # 2\. The Package System
152 The portion of the Muddle environment which provides a uniform
153 facility for lexical blocking is known as the Package System. In one
154 sense it is the most basic part of the environment, since it enables
155 many programmers to use each other's code without identifier
158 In addition, the Package System is interfaced to a library facility
159 (see section 4) by which Muddle code may be stored and later loaded as
162 The Package System is so basic to use of the Muddle environment that
163 (with a few exceptions) every subsystem or family of Muddle functions
164 described in this document is a "package".
166 ## 2.1. The Theory Of Lexical Blocking In Muddle
168 Lexical blocking is implemented in Muddle by means of `OBLIST`s and
169 `LIST`s of `OBLIST`s. Changes of lexical context are performed using
170 the `SUBR`s `BLOCK` and `ENDBLOCK`. The Package System provides a
171 high-level interface to these low-level constructs.
173 The primary goal of a lexical blocking scheme is the prevention of
174 identifier conflicts. Specifically, when your program references the
175 variable `X`, it should be your `X` and not that of some other
176 program. At the same time, it should not be necessary for a programmer
177 to search every program previously written to verify that an
178 identifier he wishes to use is not already "taken".
180 It should be clear that the simplest solution, a single `OBLIST`, will
181 not satisfy either of these goals. With only one `OBLIST` there would
182 necessarily be identifier conflicts, necessitating exhaustive
183 searching for unique identifiers.
185 Obviously, programmers could put their program's identifiers on an
186 `OBLIST` unique to that program. Unfortunately, such a solution
187 addresses only half the program. What happens when some other
188 programmer wishes to use some of this code? He could insert the unique
189 `OBLIST` for that program into the `OBLIST` path for his program; but
190 the moment that is done he gets all the identifiers for that program,
191 including local variable, internal data structures, and so on.
193 Consequently, we move to a situation where each program uses two
194 `OBLIST`s: one for the identifiers that are local to the program, and
195 one for the identifiers that are to be used by other programs. In the
196 Package System, these are known as the "internal" `OBLIST` and the
199 Most of the identifiers in a program are local to it, and want to be
200 placed on the internal `OBLIST`. Therefore, in terms of an argument to
201 the `BLOCK` `SUBR`, when a program is being loaded into Muddle, the
202 `OBLIST` path wants to be:
208 With this `OBLIST` path, most `ATOM`s (identifiers) will be on the
209 internal `OBLIST` (as `READ` puts unknown identifiers on `<1
210 .OBLIST>`), but the `ATOM`s for the entries and the `ATOM`s for the
211 usual `SUBR`s will be available.
213 The only issue yet to be addressed is that of using an entry of a
214 different program in your program. This is accomplished by adding the
215 entry `OBLIST` of any such programs to the path after `ROOT`:
220 *other-program-entry-oblist
221 yet-another-program-entry-oblist*
226 As only the entry `OBLIST`, and not the internal `OBLIST`, of the
227 program being used is added to the path, the chance of identifier
228 conflict is lessened.
230 All that remains is to introduce the functions by which these various
231 operations are performed.
233 ## 2.2. Package System Overview
235 The functions which make up the Package System are:
237 - `PACKAGE` - This indicates the start of a package of functions.
239 - `ENDPACKAGE` - This indicates the end of the package of functions.
241 - `ENTRY` - This indicates an `ATOM` which is to be made available
242 outside the definition of this package of functions. All other
243 `ATOM`s will not be directly available outside the package.
245 - `USE` - This indicates a reference by name to another package of
248 - `USE-DATUM` - This indicates a reference by name to a data set.
250 - `DROP` and `L-UNUSE` - These undo the effects of `USE` and
253 These functions are themselves part of a package named `PKG`, which is
254 preloaded into Muddle.
256 ### 2.2.1. Sample Package
258 A sample Muddle `PACKAGE` is given with comments in order to
259 demonstrate the usage of these functions.
261 <PACKAGE "HOUR-STRING">
263 ;"PACKAGE begins the package called HOUR-STRING."
267 ;"The atom TIME-STRING is an entry to this package;
268 it may be referenced by other packages by
273 ;"Indicate that the package DATIME is
274 used within the current package."
276 <DEFINE TIME-STRING ()
277 <STRING <UNPARSE <HOURS>> " o'clock">>
279 ;"Define this little function which returns a string
280 telling the last hour in a strange format."
282 <DEFINE HOURS () <1 <RTIME>>>
284 ;"Define an internal function which is available
285 only within the HOUR-STRING package, since its
286 name is not in any ENTRY statement.
287 Note that this function refers to RTIME,
288 which is an ENTRY in the DATIME package."
292 ;"The end of this little demonstration package."
296 This function delimits the beginning of a package of functions. It
297 takes one required argument, a `STRING`, which is the the name of the
298 package. This `STRING` uniquely identifies the package within a
299 library of packages (see section 4.)
301 In a `PACKAGE` those `ATOM`s which are specified as entries live in a
302 separate `OBLIST` of their own, called the entry `OBLIST`. The `ATOM`
303 naming this `OBLIST` is on the `PACKAGE` `OBLIST` and has the same
304 name as the package itself. Thus, an entry "X" of a `PACKAGE` "Y"
305 would have as its "full-trailer" name: `X!-Y!-PACKAGE!-`.
307 `PACKAGE` blocks (sets up) the current `OBLIST` path so that the
308 `ATOM`s which are internal to the `PACKAGE` fall into an `OBLIST`
309 which is not otherwise used. The `ATOM` naming this `OBLIST` is on the
310 entry `OBLIST` of the `PACKAGE`, and is by default given a name
311 created by putting the character I at the beginning of the `PACKAGE`
312 name. An internal `ATOM` "Z" in the `PACKAGE` "Y" previously mentioned
313 would have as its "full-trailer" name: `Z!-IY-Y!-PACKAGE!-`.
315 `PACKAGE` also keeps track of the fact that the particular `PACKAGE`
316 named has been defined in this Muddle process by putting its name on
317 the `PACKAGE` `OBLIST`.
319 `<PACKAGE` **name:string**
324 `PACKAGE` takes three optional arguments in addition to the required
325 one (the optional arguments are ignored if *name* is already a
328 - *iname* is the name of the internal `OBLIST` of the `PACKAGE`; by
329 default is is the name of the `PACKAGE` with the letter "I"
332 - *size* is the number of buckets in the entry `OBLIST`; by default
335 - *isize* is the number of buckets in the internal `OBLIST`; by
338 In addition to `PACKAGE`, there exists the obsolete function
339 `RPACKAGE`, documented here only because some programs still use it.
340 The difference between them is that the entry `OBLIST` for an
341 `RPACKAGE` is the `ROOT` `OBLIST`. The implication of inserting an
342 entry into the `ROOT` is that this requires the name of the entry be
343 unique over all `PACKAGE`s, because the entry is, in effect, being
344 promoted to the status of a `SUBR`. It is (in rare cases) useful to do
345 this, but the correct way is with the function `RENTRY` (see section
350 The `ENTRY` function applied to one or more `ATOM`s declares that
351 these `ATOM`s are to be put into the `OBLIST` reserved for entries in
352 this particular `PACKAGE`. Only `ATOM`s declared this way will be
353 accessible (in the normal course of events) to functions outside this
356 It is possible to place some entries of a `PACKAGE` on the `ROOT`
357 `OBLIST` using the function `RENTRY`. It is recommended that instead
358 of using `RPACKAGE` in those rare cases where entries must go on the
359 `ROOT`, `RENTRY` be used instead.
361 All `ENTRY` statements should appear immediately after the `PACKAGE`
362 or `RPACKAGE` statement. Note: never put a `USE` statement before the
363 `ENTRY` statements; if you do, you may get the `ERROR` message
364 `ALREADY-USED-ELSEWHERE`, meaning that the name of an entry is
365 conflicting with an `ENTRY` in one of the packages you `USE`d. `ENTRY`
366 will also give an `ERROR` if it is used outside the body of a
371 This function takes as arguments one or more `STRING`s which are the
372 names (as given to `PACKAGE`) of other `PACKAGE`s. `EXTERNAL` is a
373 synonym of `USE`. `USE` causes the entry `OBLIST`s of the `PACKAGE`s
374 named to be spliced into the current `OBLIST` path. Thus, references
375 to entries of those `PACKAGE`s may be made after the `USE`, until the
376 next `ENDPACKAGE` (or the next `DROP` or `L-UNUSE` if `USE` is being
377 invoked outside a `PACKAGE` to load a file.)
379 `USE` is consequently the mechanism for sharing code. If the `PACKAGE`
380 being used is already loaded, its entries are made available; if not,
381 the `PACKAGE` is loaded first (see section 4.1 for details on how this
386 `USE-DATUM` requires one `STRING` argument, the name of a data set. If
387 the data set is not loaded, `USE-DATUM` loads it and creates an `ATOM`
388 of the same name, on the `USE-DATUM` `OBLIST`, whose `GVAL` is the
389 data set. `USE-DATUM` always `EVAL`s to the data set named, regardless
390 of whether it had to be loaded or not.
392 ### 2.3.4. DROP and L-UNUSE
394 These function take the same arguments as `USE` and `USE-DATUM` and
397 `DROP` simply splices the named packages out of the current `OBLIST`
398 path. A `USE` of a `DROP`ped `PACKAGE` will not reload the `PACKAGE`
399 but simply splice it back into the `OBLIST` path.
401 `L-UNUSE` splices the `PACKAGE` out and removes its name from the
402 `PACKAGE` `OBLIST`, which will cause the entire `PACKAGE` to be
403 reloaded if it is `USE`d again. `L-UNUSED` of a data set will remove
404 its `ATOM` from the `USE-DATUM` `OBLIST`.
406 ### 2.3.5. ENDPACKAGE
408 The `ENDPACKAGE` function of no arguments terminates the definition of
409 the current `PACKAGE` and undoes the lexical blocking done by the
410 `PACKAGE` function. The `ENDPACKAGE` statement should be the last one
413 ### 2.3.6. PACKAGE Restrictions
415 There are some restrictions on what the user may do inside a
416 `PACKAGE`. These are enforced by the Library System when the user
417 attempts to submit a `PACKAGE` to a library.
419 A `PACKAGE` should not `FLOAD` or `LOAD` any file to obtain parts of
420 itself. All such environment setup should be done with `USE` and
423 A `PACKAGE` may not reference any `ATOM` whose `OBLIST` path goes
424 through the `INITIAL` `OBLIST`. All of the non-entry `ATOM`s in a
425 package should fall naturally into it's internal `OBLIST`.
427 As mentioned before, the `RENTRY` of a package have the same `OBLIST`
428 status as `SUBR`s, i.e., they must be unique among both all `SUBR`s
429 and all `PACKAGE` entries.
431 ### 2.3.7. ENTRY Name Conflicts
433 It is possible to have two or more `PACKAGE`s (not `RPACKAGE`s) which
434 have entries (not `RENTRY`s) with the same `PNAME`. If the user needs
435 both `PACKAGE`s at the same time, he may `USE` them both and refer to
436 the ambiguous entries by their "full trailer" names. All of the
437 non-ambiguous entries in `PACKAGE`s may still be referenced by `PNAME`
440 # 3\. Program Writing and Debugging Aids
442 This chapter concentrates on editing and debugging aids for Muddle
443 programming. The basis for editing and debugging in Muddle is twofold:
444 First, Muddle is an interpreter, which permits interactive testing and
445 debugging of software. Second, Muddle programs (even compiled Muddle
446 programs) are structures and therefore may be manipulated by other
449 Packages useful in editing and debugging range from `EDIT` and
450 `PPRINT`, which are preloaded, and which form the core of most editing
451 or debugging systems, to more sophisticated aids such as `DEBUGR` and
452 `TRACE`, which are more powerful, and useful for more complicated
455 It should be noted that, in addition to the editors discussed below,
456 RMODE and EMACS, TECO based text editors, understand much of the
457 syntax and many of the conventions of Muddle programs.
459 ## 3.1. Pretty-Printing
461 The purpose of pretty printing is to clarify the structure of Muddle
462 objects by printing them in a more human-readable format than that
463 provided by the `SUBR`s `PRINT`, `PRIN1`, etc. Objects are
464 pretty-printed through the judicious insertion of spaces, tabs, and
465 new-lines between tokens. Pretty-printed objects are readable by the
466 Muddle Reader. Pretty printing is an aid to understanding and
467 debugging Muddle `FUNCTION`s or other objects. You will probably find
468 pretty printing to be extremely helpful, especially if you are working
469 without a listing or with an old listing. In fact, pretty-printing is
470 one way to make a new pretty listing after editing. `PPRINT` is
471 pre-loaded in most initial Muddles. The name of the package containing
474 `<PPRINT` **any** *channel*`>`
476 pretty-prints *any* on *channel*. The second argument is option, by
477 default `.OUTCHAN`. If *any* is an `ATOM`, `PPRINT` will enclose it in
478 an application of `DEFINE`, `DEFMAC`, `SETG`, or `SET`, as seems
479 appropriate. `COMMENT`s found inside *any* are right-justified.
480 `PPRINT` cannot output an `RSUBR` without `FIXUP`s (that is, one that
481 was `READ` in while `KEEP-FIXUPS` (see section 3.4) had no `LVAL` or
482 had a `FALSE` `LVAL`); it will give the `ERROR` message
483 `CAN-NOT-BE-DUMPED`. `PPRINT` returns `.NULL` which is an `ATOM` whose
484 `PNAME` is a single rubout, invisible on most consoles.
486 `<PPRINF` **in:string-or-atom-or-list** *outfile:string
487 width:fix eval?:boolean*`>`
489 pretty-prints all the contents of *in* into *outfile*.
491 If *in* is an `ATOM` or a `LIST` of `ATOM`s, its `VALUE`(s) are the
492 objects to be `PPRINT`ed. In this case, *outfile* is by default a file
493 whose first name is produced by taking the `PNAME` of *in* (or *in*'s
494 first element, if *in* is a `LIST`).
496 If *in* is a `STRING`, it specifies a file containing objects to
497 `PPRINT`. In this case, *outfile* is by default "`TPL:`".
499 *width* is the maximum width of output lines (although output lines
500 are prevented from being extremely long); it is optional, and by
501 default `<13 ,OUTCHAN>`.
503 *eval?* tells `PPRINF` whether or not to `EVAL` everything in the
504 file; it is optional, by default a `FALSE` (don't `EVAL`). *eval?* is
505 meaningless if *in* is not a `STRING`.
507 `PPRINF` returns either "`DONE`" or a `FALSE` if it couldn't open
508 *infile* or \*outfile(. `PPRINF` inserts page boundaries in *outfile*,
509 between objects, every 60 lines or fewer; you may want to move these
510 afterward to more logical places. `PPRINF` binds `KEEP-FIXUPS` and
511 `REDEFINE` to `T`, and `QUICKPRINT` (see below) to a `FALSE`.
513 ### 3.1.1. PPRINT Control Switches
515 `PPRINT`'s output is affected by the local values of several `ATOM`s.
516 Each value is examined only for truth.
520 If this `ATOM`'s `LVAL` is `FALSE`, you are in slow mode; otherwise
521 (include the case of no `LVAL`), you are in fast mode. The behavioral
522 difference is this: in fast mode, there may be `COMMENT`s in the
523 pretty-printed object(s) which `PPRINT` misses. Also, fast mode is
524 indeed faster than slow mode. Fast mode is the default, that is,
525 `QUICKPRINT` is initially true. The modes are really distinguished by
526 the depth of recursion to which PPRINT resorts. In slow mode, it
527 recurses all the way down to every monad in the thing pretty-printed;
528 in fast mode, it goes down only far enough to find something that will
533 `PPRINT` uses full recursive lookahead to avoid packing things against
534 the right margin and, as a result, not being able to fit things within
535 the right margin. The lookahead results in very good formatting of
536 deeply-nested `MAPF`ed and `FUNCTION`s; all but the most bizarre cases
537 should be very legible. However, it can result in noticeable "pauses"
538 in the printing operation and, in some cases, a net speed slightly
539 less than with limited lookahead. Since this can be a disadvantage
540 when using `PPRINT` interactively on a heavily-loaded system, the
541 lookahead can be disabled: if the `LVAL` of `LOOKAHEAD` is a `FALSE`,
542 no lookahead will be performed; otherwise it happens. `LOOKAHEAD` is
543 initially true, that is, lookahead happens by default.
547 If `LOOKAHEAD` is a `FALSE`, the formatting can cause too many objects
548 to be squeezed against the right margin. So that particular cases can
549 be made legible, the format when lookahead is not in use can be
550 manually set: if the `LVAL` of `VERTICAL` is non-`FALSE`, `PPRINT`
551 will indent very little whenever indenting is called for. (`VERTICAL`
552 being true means a "more vertical" format.) `VERTICAL` is initially
553 `FALSE`. The value of `VERTICAL` is ignored when `LOOKAHEAD` is true;
554 the lookahead effective chooses different values for `VERTICAL` for
555 different parts of the object pretty-printed.
557 ### 3.1.2. Lower-level Pretty Printing
559 It is sometimes desirable to use some of the functions that `PPRINT`
560 uses but in a different way. For example, a specialized pretty-printer
561 for Program Abstracts would want to insert indented field names into
562 the output and pretty-print field values with the same indentation.
563 The names of lower-level pretty-print functions are included in the
564 `ROOT` `OBLIST` for such purposes.
566 `<EPRINT` **any** *left-margin:fix*`>`
568 pretty-prints *any* on `.OUTCHAN` to the right of *left-margin*. The
569 second argument is optional, by default `<VALUE LEFT-MARGIN>` (see
572 `<EPRINT` **any** *left-margin:fix*`>`
574 `EPRIN1` is to `EPRINT` as `PRIN1` is to `PRINT`.
578 This is the `ATOM` that `EPRINT` binds to its second argument. You can
579 `SET` it outside calls to `EPRINT` in order to make a permanent left
580 margin. Its initial `LVAL` IS 0.
582 `<INDENT-TO` **column:fix** *channel*`>`
584 outputs tabs and/or spaces to advance the output column (`<14
585 channel>`) to *column*, if it is not already past.
592 pretty-prints *any* on *channel* (by default `.OUTCHAN`) between the
593 margin *left-margin* (by default `<14 channel>`, the current column)
594 and *right-margin* \*by default `<13 channel>`, the rightmost column.)
595 All arguments but the first are optional. `COLPP` returns `,NULL`. For
596 example, `<COLPP any .OUTCHAN 10 70>` would leave a 10-character
597 margin at left and right on an 80-column `OUTCHAN`. Also,
599 <PRINT () PRINT AAAAAAAAAAAAAAA> <COLPP ,FOO>>
601 would result in output like
603 AAAAAAAAAAAAAAA #FUNCTION ((X GGGGGGGGGGGGGGGGGGGGGG)
606 `EPRINT`, `EPRIN1`, and `COLPP` are affected by the truth of
607 `.QUICKPRINT`, `.LOOKAHEAD`, AND `.VERTICAL`.
609 ### 3.1.3. Ampersand Printing
611 "Ampersand printing" consists of printing any object on a single line
612 by using the character `&` (ampersand) to mean "There's more stuff
613 here." (This technique is borrowed by the InterLisp editor.)
615 There are two ways in which `&` is used by this printer as an
618 1. An `&` appearing between some variety of brackets indicates that
619 there is a big object of the indicated `TYPE` there.
620 2. The characters `..&` or `&..` on the left or right of a structure
621 mean that there are more objects to the left or right which have
626 #FUNCTION ((A B C D) <&>)
628 This is a `FUNCTION` with four arguments in its argument `LIST`, and
629 the `FUNCTION` body contains one `FORM` which was too big to print in
630 the remainder of the line.
632 <PROG () <KRK <+ /A 5>> <PRINC .Q> <SET BAR <ORG>> <&> &..>
634 This is a large `FORM`, namely a `PROG`. In addition to the elements
635 printed, there are more elements to the right, and there is one `FORM`
636 which was too big to print.
638 Ampersand printing is effected by two pure `RSUBR`s: `&`, analogous to
639 `PRINT`, and `&1`, analogous to `PRIN1`. A related `RSUBR`, `&LIS`,
640 can be applied to no arguments to put you into an endless
641 `READ-EVAL-&` loop, instead of the normal `READ-EVAL-PRINT` loop.
643 ### 3.1.4. Examining the stack
647 returns the *fix*th `FRAME` down from the top application of `ERROR`
650 `<FRAMES` *how-many:fix start:fix*`>`
652 pretty-prints *how-many* `FRAME`s (by printing the `FRAME` number
653 (suitable as an argument to `FRM`), `FUNCT`, and `ARGS` of the
654 `FRAME`), starting with `<FRM` *start*`>`. Both arguments are
655 optional; *start* defaults to 0, and *how-many* defaults to a large
656 integer. A `FRAME` whose `FUNCT` is an `ATOM` whose `VALUE` is an
657 `FSUBR` is not printed, if the same information is found in the next
660 `<FR&` *how-many:fix start:fix*`>`
662 is like `FRAMES but uses ampersand printing instead of pretty
663 printing. It is handy for summarizing`FUNCT`s and`ARGS`that are large
664 or unprintable (like`RSUBR\`s with no fixups).
666 `<FRATM` *how-many:fix start:fix*`>`
668 is like `FRAMES` but gives an abbreviated view of the stack. It prints
669 `FUNCT`s only, and only for `FRAME`s connected with named `FUNCTION`s,
670 `RSUBR`s, and `RSUBR-ENTRY`s. It is handy when a `FRAME` contains a
677 prints out the stacked bindings of *atom*, going through *how-many*
678 `FRAME`s, starting with `<FRM` *start*`>`. The two numeric arguments
679 are optional; *how-many* defaults to a large integer, and *start*
680 defaults to 0. The format of the printing is two columns: the first
681 column is the number of the `FRAME` in which *atom* has a binding; the
682 second column is the value bound, or a message proclaiming the lack of
685 `<FR&VAL **atom**\ *how-many:fix\ start:fix*`\>\`
687 is precisely the same as FRLVAL, except that the values are ampersand
688 printed instead of `PRINT`ed.
690 Finally, the "`FRMSP`" `PACKAGE` contains analogues of many of the
691 preceding functions, but each takes as its first argument a `PROCESS`,
692 by default `<ME>`. These are all named by adding a 'P' to the end of
693 the usual name. For example,
697 Does does a `<FR&>` in the `PROCESS` `MAIN`.
699 There is one additional function of interest in "FRMSP".
701 `<FRTYPE` *how-many:fix start:fix*`>`
703 is like `FRAMES`, but gives only the `TYPE`s of the arguments to each.
704 This is useful in those situations when the stack shows illegal
705 `FRAME`s or other unprintable objects.
707 ## 3.2. The Muddle Editor
709 `EDIT` allows a Muddle user to make incremental changes in Muddle
710 structured objects, without leaving Muddle and with the ability to
711 save the results in a file, and to set or clear conditional
712 breakpoints of various sorts in objects that will be evaluated, such
715 `EDIT` is an editor/debugger written in, written for, and running
716 under Muddle. It comprises the package "`EDIT`" and several smaller
717 packages which wi11 be mentioned later in this section. `EDIT` is
718 preloaded in most initial Muddles.
720 To start editing, apply `EDIT` to no arguments or to the name of the
721 object you wish to edit: `<EDIT>` causes entry into `EDIT` and opens
722 the last object edited; `<EDIT` *object*`>` causes entry into `EDIT`
723 and opens *object* for editing. Permissible *object*s include:
725 - `ATOM`s. The `GVAL` (preferably) or the `LVAL` of the `ATOM` is
726 opened. If it has no value, `EDIT` returns a `FALSE`.
728 - A `PRIMTYPE` `LIST`. The `PRIMTYPE` `LIST` is opened.
730 - A `FIX`. The stack frame with that number is opened (i.e., `<ARGS
733 Part of `EDIT`'s efficiency comes from forbidding it to delve into
734 objects that are not of `PRIMTYPE` `LIST`, that is, not `LIST`s,
735 `FORM`s, `FUNCTION`s, etc. Attempts to edit objects of other
736 `PRIMTYPE`s will result in error messages. These objects can, however.
737 be treated as units when inserting. searching, etc.; or they can be
738 changed into `LIST`s, edited, and then changed back to their original
741 ### 3.2.1. The Edit 'LISTEN Loop'
743 #### 3.2.1.1. The Reader
745 When in `EDIT`, you are typing at a special, non-standard, input
746 function: The `EDIT` Reader.
748 The Reader allows you to type `EDIT` commands and have them executed,
749 and also to evaluate Muddle expressions normally. Its characteristics
752 - As in the normal Muddle Reader, nothing is done until you type
753 `ESC`. `DEL`, `Ctrl-L`, `Ctrl-D`, `Ctrl-G`, and `Ctrl-S` also work
756 - All `EDIT` commands are terminated when an `ESC` is encountered in
757 the input stream. (In addition. most commands will terminate
758 whenever the maximum number of arguments required has been input
759 or whenever an argument of the wrong type is encountered. In the
760 former case the next object is taken as a new command; in the
761 latter case the object of the wrong type is taken as a new
762 command. `EDIT` commands may be typed in either upper or
765 - If you type something that `EDIT` does not recognize as a command,
766 normal Muddle evaluation and printing are performed on that
767 something. This evaluation will have no effect on your position in
768 the object you are editing.
770 - While editing a function which is part of a `PACKAGE` (determined
771 from an examination of the `OBLIST` containing the `ATOM` whose
772 value is the function), `EDIT` causes the OBLIST path to be set up
773 to what it was in the environment of that `PACKAGE`. This has the
774 advantage of reducing the number of trailers printed, and causes
775 newly entered `ATOM`s to fall on the correct `OBLIST` (the
776 internal `OBLIST` of the `PACKAGE`). It has the slight
777 disadvantage that it disables the dynamic loader (which depends on
778 unbound variables falling on the `INITIAL` `OBLIST`). If the
779 `GVAL` of `E-PKG` is a `FALSE`, this feature is disabled, and the
780 normal `OBLIST` path is in effect during editing.
786 Causes execution of `EDIT` command R with argument 5.
790 Causes application of the function R to 5.
792 #### 3.2.1.2. The Ampersand Printer
794 Your current position is displayed by "ampersand printing' (see
795 section 3.1.3). This consists of printing any object on a single line
796 by using the character & (ampersand) to mean "There's more stuff
799 The ampersand printer used in `EDIT` is much like the standard one,
800 with the addition that your current position (see below) is displayed
801 by the glyph of a solid square: █.
803 When you initially enter `EDIT`, you are in a mode called
804 "non-verbose", in which ampersand printing is not automatically done
805 following execution of `EDIT` commands. The `V` command is used to
806 toggle you in and out of verbose mode (see below).
810 `<FUNCTION (` █ `(A B C D) <&>>`
812 Indicates that your position is just to the left of a `FUNCTION`'s
813 argument list. and the `FUNCTION` body contains one `FORM` which was
816 `<..& <KRK <+A .A 5>>` █ `<SET BAR <ORG>> <&> *..>`
818 Indicates that you are in the middle of a large `FORM` (e.g., a
819 `REPEAT` or a `PROG`), positioned just to the left of the `<SET BAR
820 <ORG>>`. In addition to the objects printed, there are more objects to
821 both the left and the right, and there is one `FORM` which was too
822 large to fit on the line.
824 ### 3.2.2. Edit Commands
826 #### 3.2.2.1. General
828 A sequence of `EDIT` commands is executed as soon as you type `ESC`.
829 If one command fails, subsequent commands up to the `ESC` are ignored,
830 and EDIT types out an appropriate error message. A failing
831 `EDIT`command generally has no effect whatsoever; but see individual
834 Note that *all* arguments to `EDIT` functions must be legal Muddle
835 objects. In particular, you can't search for `<SET`, since the `<>`'s
836 aren't balanced. Nor can you insert it. (But you can, for instance,
837 search for and insert `<SET THING 1>`.)
839 If a command expects an argument and doesn't get one, an error message
842 Many `EDIT` commands take `FIX`es as arguments. Those that do
843 interpret the `ATOM` \* as an argument to mean "as many as possible".
845 Whenever you are in `EDIT`, you have a well-defined "position". A
846 position is a "place" *inside* a Muddle structure: this "place" is
847 either *between* two elements elements of the structure, or between an
848 element and either end of the structure, or *inside* an empty
849 structure. All editing, movement, and printing commands operate
850 relative to your current position. The term "cursor" is used in the
851 following descriptions to refer to an embodiment of a position.
853 The format listed in each of the following command descriptions is:
859 #### 3.2.2.2. General Commands
863 Causes a short summary of all EDIT commands to be typed out. The same
864 summary appears later in this chapter.
868 Similar to the above, but the summary is even shorter, and should fit
869 entirely on the screen of an Imlac terminal.
873 Leave `EDIT` and return to Muddle. (Causes `EDIT` to return the `ATOM`
878 Quit from `EDIT` and then retry the frame specified, or by default,
879 the one originally given to an open command or, if none was given, the
880 frame beneath the last `ERROR` or `LISTEN` frame.
884 This is not really an `EDIT` command; rather, it is a character,
885 obtained from the input stream at interrupt level, which is used to
886 return you to the `EDIT` Reader from some higher level of application,
887 e.g., an `ERROR`'s `LISTEN`. It is the `EDIT` equivalent of `ERRET`
890 `Ctrl-F` (or `Ctrl-S`) typed during execution of an `EDIT` command is
891 similar to normal Muddle `Ctrl-S` but returns to the `EDIT` Reader
892 instead of the Muddle `LISTEN` loop.
896 Equivalent to `Q` followed by `<EDIT` *object*`>`. Positions the
897 cursor just to the left of the first element of the entire object
902 If the object to the right of the cursor is an `ATOM`, or a `FORM`
903 whose first element `ATOM`, and the `ATOM`'s value is openable, then
904 it is opened. This command is useful when tracing a calling sequence
905 through several functions.
907 #### 3.2.2.3. Movement Commands
911 Places the cursor at the position it had following an `O`.
915 Moves the cursor *fix* objects to the right, by default one. If *fix*
916 is too large, i.e., there are not that many positions to the right of
917 the current position, `EDIT` prints an error comment and the cursor
922 Moves the cursor as far to the right as possible.
926 Moves the cursor \*fix( positions to the left, by default one. If
927 *fix* is too large, EDIT prints an error message.
931 Moves the cursor as far to the left as possible.
935 Positions the cursor just to the right of the rightmost element within
936 the object to the left of the cursor, if that object is of `PRIMETYPE`
937 `LIST`. Visually, the cursor moves left over one "close bracket".
941 Positions the cursor just to the left of the leftmost element within
942 the object to the right of the cursor, if that object is of `PRIMTYPE`
943 `LIST`. Visually. the cursor moves right over one "open bracket". If
944 the cursor is to the left of an element that is not of `PRIMETYPE`
945 `LIST`, `EDIT` prints an error message.
953 Positions the cursor just to the right of the object the cursor is
954 currently within. Does so `fix` times, by default once.
958 Positions the cursor just to the left of the object the cursor is
959 currently within. Does so *fix* times, by default once.
967 Does a depth-first, left-first tree-walk. (i.e., left-to-right)
968 starting with the object to the right of the cursor. until the cursor
969 is just to the right of an object structurally equal (i.e., =?) to its
970 argument. An occurrence of the object will not be found if it is
971 inside anything not of `PRIMETYPE` `LIST`. On failure. the cursor does
972 not move. If the argument is omitted, the last object searched for is
981 Same as `S`, but the tree-walk is depth-first, right-first (i.e.,
982 right-to-left) and you end up to the left of the object for which you
985 #### 3.2.2.4. Printing Commands
988 Causes the normal "ampersand print" to be done. This is principally
989 useful when you are in "silent" mode; see the `V` command.
991 By the way, an "empty" command is typed by typing `ESC` without having
992 typed any visible characters before it.
996 `PPRINT`s (not "ampersand prints") the object to the right of the
1001 `PPRINT`s the object the cursor is in. This is similar to doing a `U`
1002 and then a `P`, although the cursor is not moved.
1006 `PPRINT`s the whole object you have open.
1010 Toggles the verbosity mode between "verbose" (most commands cause
1011 ampersand printing) and "silent" (printing of any sort is done only
1012 when some explicit print command is used, or when an error occurs.)
1013 The current state of verbosity is the `G-VAL` of `E-VERBOSE`.
1015 In silent mode, absolutely *nothing* is printed after each command,
1016 not even new-lines or prompts. However, normal Muddle evaluation still
1017 causes normal Muddle printing.
1019 #### 3.2.2.5 Editing Commands
1023 Inserts all its arguments immediately to the right of the cursor. None
1024 of its arguments are evaluated; you can insert unevaluated `FORM`s
1025 without using `QUOTE`. The cursor ends up to the right of the last
1030 Same as `I`, but its arguments are evaluated. This is useful in
1031 conjunction with the `X` command (see below.)
1033 `I:` *type:atom fix*
1035 Grabs *fix* objects to the right of the cursor, inserts them into a
1036 newly created object of `TYPE` *type*, deletes them from the original
1037 structure, and inserts the newly created object in their place. In
1038 other words, it "inserts" the appropriate open and close brackets for
1039 *type* at the cursor and *fix* objects to the right.
1041 By default *fix* is one, *type* is `LIST`. An error message is printed
1042 if *fix* is larger than the number of objects to the right of the
1045 There is no way to directly insert or delete single parentheses,
1046 brackets, etc. using `EDIT`. Insert, use `K:` (see below) to remove
1047 pairs of brackets, and `I:` to insert them.
1049 `I*` *indicator:atom* **new-structure**
1051 Imbed looks for all occurrences of *indicator* in *new-structure* and
1052 replaces these occurrences with objects taken and deleted from the
1053 right of the cursor. In then inserts the result.
1055 If only *new-structure* is given, the *indicator* is the `ATOM` \*. If
1056 there aren't enough objects to the right of the cursor to replace each
1057 `indicator`, remaining indicators are left untouched and a warning
1060 `I*` is generally used to insert one or more structures into another
1061 complex structure in one operation, instead of several. For example:
1063 `<SET X` █ `<12 .Y>>`
1064 `I* <COND (<NOT <LENGTH? .Y 11>> *)>$`
1065 `<SET X <COND (<NOT <LENGTH? .Y 11>> <12 .Y>)>` █ `>`
1067 Places a protective conditional around an `NTH` to prevent an
1068 out-of-bounds error.
1072 Insert into a group. `IG` is similar to `I`, but assumes that the
1073 object you are in is a group (as produced by `GROUP-LOAD`). Arguments
1074 to `IG` which are not `ATOM`s are inserted as `I`, Objects which are
1075 `ATOM`s and which have a value insert a `FORM` which `DEFINE`s,
1076 `SETG`s, or `SET`s the `ATOM` as appropriate. Thus, to add a new
1077 function `F` to a group \`G1 one could type:
1083 Deletes `fix` objects to the right of the cursor. Defaults to one.
1084 Negative `fix` causes deletion to the left of the cursor.
1088 Changes the one object to the right of the cursor so its single
1089 argument. Does not move the cursor. Does not evaluate is argument. `C`
1090 is more efficient than `K` plus `I`.
1094 Changes the type of object to the right of the cursor to *type*.
1095 Attempts to do something reasonable for every type change. If you tell
1096 it to change a `STRING` to a`LIST`, you get a `LIST` of `CHARACTER`s.
1097 If you attempt to change a structure whose elements are other than
1098 `CHARACTER`s and `STRING`s to a `STRING`, you will get a Muddle error.
1102 Deletes the brackets around the object to the right of the cursor i.e.
1103 kills the object and inserts its elements into the structure of which
1106 `SU` **new** **old**
1108 The Substitute command takes two arguments. All occurrences of *old*
1109 from the current location to the end of the open object (actually a
1110 search-right is done) are replaced by *new*. Once the search for *old*
1111 fails, the command terminates, and the number of substitutions
1112 performed is printed. The cursor is left after the last object
1117 `SET`s the *atom* to the object to the right of the cursor. `X` can be
1118 used with `K` and `G` to move things around within the object being
1123 Swaps the two objects to right of the cursor, leaving the cursor
1124 pointing at the same object. The effect is to move the cursor and the
1125 object it points at one object to the right. Repeated `SW`s move
1126 cursor and object further and further to the right.
1128 #### 3.2.2.6. Macro Facility
1132 Takes either a `STRING` or something which `EVAL`s to a `STRING` and
1133 performs all of the commands in the `STRING`. For complete assurance
1134 that your commands will be done properly, put an ESC between commands.
1136 `IT` **fix** *macro*
1138 This command (also called DO) takes a *fix* and macro as if an
1139 argument to `M`. This command will loop through the *macro* *fix*
1140 times or until an error is generated. When the iteration ends, the
1141 user is told how many complete passes have been made of the `macro`.
1143 In both of the above commands, if an `EDIT` error is generated, the
1144 *macro* will be terminated, and the *macro* itself will be printed,
1145 with an arrow pointing to the offending command. The cursor wilt
1146 remain at the place where the last legal command left it.
1148 The SU command is, internally:
1149 `DO * "S` *old*`$L$C` *new*`$"`
1151 #### 3.2.2.7. Cursors
1153 Cursors are locations in objects being `EDIT`ed. In addition to the
1154 main cursor, which is where editing occurs, other locations (also
1155 called cursors) may be remembered. The main cursor may be moved to
1156 another cursor in a single operation, potentially saving many motion
1157 commands. In large `FUNCTION`s cursors may also reduce confusion by
1158 distinguishing among several similar areas of code.
1162 The `PACKAGE` for dealing with cursors is not normally loaded in an
1163 initial Muddle, so the UC command loads it and makes the cursor
1164 commands available. The `PACKAGE` loaded is "`CURSOR`".
1168 `CU` takes an `ATOM` argument and `SET`s the `ATOM` to an object of
1169 type `CURSOR`, which tries to be clever in the event you change the
1170 object. Also, if you use the `X` command to name a substructure and
1171 then move copy it with `G` or `I`, the cursors in the substructure
1172 will follow to the new location.
1174 There are some restrictions. Cursors in empty `LIST`s are okay but
1175 they will not follow the object to new locations. Also this
1176 "following" feature is effective only at the first `G` or `I` after
1177 the `X`. To move the substructure again you have to `X` again.
1179 `I*` is somewhat incompatible with `CURSOR`s. Cursors in Imbedded
1180 structures will sometimes disappear.
1184 `GO` takes a *cursor* (normally the `LVAL` of an
1185 `ATOM` previously given as an argument to `CU`) and `GO`es to that
1186 position. If the *cursor* is illegal (not in the current top-level
1187 structure), an error message will be printed and you will remain in
1188 your previous position.
1192 Kill the cursor assigned to *atom*.
1196 Prints all cursors in the structure to the right of the main cursor.
1199 Prints all cursors in the currently open structure.
1201 #### 3.2.2.8. Breakpoints
1203 `BK` *predicate* *any* ...
1205 Inserts a breakpoint "around" the object to the right of the cursor.
1206 Takes any number of arguments. Subsequently, whenever that object
1207 would have heen evaluated, you instead hit a breakpoint function
1210 1. Evaluates *predicate*. If the value is `FALSE`, evaluation
1211 continues as if there were no breakpoint. If the value is
1212 non-`FALSE`, or `BK` was given no arguments:
1214 2. Types `**BREAK**`.
1216 3. For each argument after the first that you gave `BK`, types
1222 You continue by applying `ERRET` to one argument, just as from an
1223 `ERROR`; the argument's value is ignored.
1225 Breakpoints are implemented by inserting a `BREAKR` (a `PRIMTYPE`
1226 `LIST` with `APPLYTYPE` `FORM`) which consists of the function
1227 `BREAKR` and arguments, including the object breakpointed. A
1228 breakpoint prints as a glyph similar to the cursor:
1230 <strike>`B`</strike> *object*
1232 If the `ATOM` `SHORT-PRINT` is assigned `FALSE`, the actual `BREAKR`
1235 The breakpoint function returns `EVAL` of the thing it is put
1236 "around", and there are cases where this does not work. There are
1237 always equivalent places that do work.
1239 1. Breakpoint on the first element of a `FORM` does not work. Put it
1240 on the whole `FORM`.
1242 2. Breakpoint on a `LIST` which is an argument to a `COND` does not
1243 work. Put it on the first `FORM` in the `LIST`.
1245 `BA` *predicate* *any*
1247 Similar to `BK`, but puts the breakpoint *after* the object at the
1248 cursor. Its action is like that of `BK` except that the break occurs
1249 after the object it is on is `EVAL`ed.
1251 This sort of breakpoint prints like the "before" sort. but with the
1252 glyph after the object broken:
1254 object <strike>`B`</strike>
1256 The *predicate* for a `BA` breakpoint may check the value returned by
1257 `EVAL` for the object the hreakpoint is on. This value is assigned by
1258 `BREAKR` to the `ATOM` `VALUE`.
1262 Removes the breakpoint (if any) from the object to the right of the
1267 Removes all breakpoints in the currently open object.
1269 #### 3.2.2.9. Edit Monitors
1271 There are several commands in `EDIT` which provide a simple interface
1272 to the "`MONITOR`" `PACKAGE`. These allow placing of monitors on
1273 references to or modifications of `LVAL`s in interpreted Muddle code.
1275 For a more complete discussion of the use of monitors, see section
1280 The `PACKAGE`s for dealing with monitors are not normally loaded in an
1281 initial Muddle, so the `UM` command loads them and makes the three
1282 commands for creating monitors available. The `PACKAGE`s loaded are
1283 "`MONITR`", which is the general monitor `PACKAGE`, and "`EMONIT`",
1284 which is the interface between `EDIT` and "`MONITR`".
1286 `RW` **atom** *predicate* *any* ...
1287 `Read-write Monitor`
1288 The most general type of monitor that can be set is a read-write
1289 monitor. It will catch any reference to or attempt to modify the
1290 `LVAL` of the *atom* specified. The restrictions on placement of
1291 breakpoints also apply to monitors, with the addition that a monitor
1292 on an `LVAL` must be placed after that `LVAL` has become `ASSIGNED?`.
1294 The second, third (and so on) arguments to `RW` are the same as those
1295 for `BK`. The *predicate* may be dependent on either the new or old
1296 value of the variable: These are available as the `LVAL`s of `NEWVAL`
1297 and `OLDVAL`, respectively.
1299 When a monitor is triggered, it prints the type of monitor, the
1300 variable being monitored, and any other information requested by the
1301 user, and then calls `LISTEN`.
1303 A monitor prints as yet another glyph: