1 MUDDLE F/SUBRS: (for MUDDLE 55) PDL/SWG 3/8/79
3 The following is a very brief description of all the
4 primitives currently available in MDL. These descriptions are in
5 no way to be considered a definition of the effects or values
6 produced by the primitives. They just try to be as complete and
7 as accurate as is possible in a single-statement description.
8 However, because of the complexity of most primitives, many
9 important defaults and restrictions have been omitted.
11 *: Multiplication of fixes and floats.
17 * (Multiply) takes any number of FIXes or FLOATs, and multiplies
18 them together, returning the result. If any of the arguments are
19 FLOATs, the result will be FLOAT. If no argument is given, * returns
20 1, if one argument is given, * returns that argument.
21 * will given an arithmetic overflow error (unless disabled by OVERFLOW)
22 if the word size of the PDP-10 is exceeded.
26 Template: #DECL ("VALUE" <OR FIX FLOAT>
27 "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
30 Tuple of arguments -- FIXes and FLOATs
31 Returns -- FIX or FLOAT, floating is contagious.
35 Floating is contagious.
37 +: Add fixes and floats.
43 + adds together any number of FIXes or FLOATs, returning the
44 result. Floating is contagious, as in all arithmetic SUBRs. If no
45 argument is given, + returns 0, if one argument, + returns the argument.
46 + will give an arithmetic overflow error (unless disabled by
47 OVERFLOW) if the result (or an intermediate result) exceeds the word
52 Template: #DECL ("VALUE" <OR FIX FLOAT>
53 "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
56 Tuple of arguments -- FIXes and FLOATs.
57 Returns -- FIX or FLOAT, sum of arguments.
59 Example: <+ !<SET FOO (1 2 3)!>>
61 Sum of elements of list.
63 -: Subtract fixes and floats.
69 - takes any number of fixes or floats and subtracts from the first
70 one all of the remaining ones. If no argument is given, returns 0. If
71 one argument is given, returns its negation. Floating is contagious,
72 and - will give an arithmetic overflow error (unless disabled by OVERFLOW)
73 if the word size of the PDP-10 is exceeded.
77 Template: #DECL ("VALUE" <OR FIX FLOAT>
78 "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
81 Tuple of arguments -- FIXes and FLOATs.
82 Returns -- The FIX or FLOAT result of the subtraction.
86 All but first argument are subtracted from first.
88 /: Divide fixes and floats.
94 / divides any number of fixes and floats. The first is divided
95 successively by each of the remaining arguments. If no arguments are
96 given, returns 1. If one argument is given, returns its reciprocal.
97 Floating is contagious. If the arguments are FIX, the result is
98 always completely fixed point division, with no rounding.
99 / will give an arithmetic overflow error (unless disabled by OVERFLOW)
100 if the word size of the PDP-10 is exceeded.
104 Template: #DECL ("VALUE" <OR FIX FLOAT>
105 "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
108 Tuple of arguments -- FIXes and FLOATs
109 Returns -- FIX or FLOAT quotient.
111 Example: </ 10 7 2.0>
113 First division gave 1, then .5 after second.
115 0?: Tests if a fix or float is zero.
121 0? tests a FIX or FLOAT to see if it is equal to zero. If it is
122 not, a FALSE is returned. If it is, T is returned.
126 Template: #DECL ("VALUE" <OR FALSE 'T> <OR FIX FLOAT>)
128 Argument 1 -- A FIX or FLOAT.
129 Returns -- FALSE if not equal to 0, T if equal to zero.
135 1?: Tests if a fix or float is equal to one.
141 1? takes a fix or float and tests its equality to one. If it is
142 not equal, returns FALSE. If it is equal, returns T.
146 Template: #DECL ("VALUE" <OR FALSE 'T> <OR FIX FLOAT>)
148 Argument 1 -- FIX or FLOAT to test.
149 Returns -- FALSE if not 1, T if 1.
153 Works for floats, too.
155 1STEP: Put a PROCESS in One-step mode
159 Category: PROCESS-CONTROL
161 Reference: RESUME, FREE-RUN
163 1STEP puts a PROCESS in single step mode. It takes as argument
164 a PROCESS. When RESUMEd, the PROCESS will be in one-step mode, running
165 until an EVAL is either entered or left.
166 The PROCESS which executed the 1STEP will then be RESUMEd. It
167 will be passed a tuple. If EVAL was being entered, the tuple will
168 contain the ATOM EVLIN and the arguments to EVAL. If EVAL was being
169 left, the tuple will contain the ATOM EVLOUT and the result of the
171 The PROCESS will remain in 1STEP mode until FREE-RUN is done on
172 it. RESUME will thus stop at each EVAL until then.
176 Template: #DECL ("VALUE" PROCESS PROCESS)
178 Argument 1 -- A PROCESS to put in one-step mode.
179 Returns -- The PROCESS.
181 Example: <1STEP .FOO>
187 Two successive steps of the process.
189 ==?: Test for physical identity of two objects.
197 ==? tests two objects for physical identity. For ==? to return
198 T (true), the two objects must have the same identical type-value pair.
199 For example, two STRINGs typed in from the console will not be ==?, but
200 two ATOMS, FIXes, or nil LISTs will be.
201 If the two objects are not the same, ==? returns FALSE.
205 Template: #DECL ("VALUE" <OR 'T FALSE> ANY ANY)
207 Argument 1 -- Any object.
208 Argument 2 -- Another object.
209 Returns -- T if the two objects are the same, FALSE otherwise.
211 Example: <==? "FOO" "FOO">
213 These two STRINGs look identical, but are not.
215 =?: Test for structural identity of two objects.
223 =? is a less stringent, but more expensive, test for identity
224 than ==?. It also takes two objects as arguments, but tests only for
225 structural identity of the objects, rather than physical identity. If
226 two objects print the same, they will be =? to each other, except for
227 numeric fuzz. For example, two STRINGs typed in from the console will
228 be =? to each other, but not ==?. Any objects that are ==? will also
229 be =?, and if ==? applies, it should be used. =? is much more
230 expensive than ==?, in general, as it must test an entire structure
232 =? returns T if the objects are structurally identical, and FALSE if
237 Template: #DECL ("VALUE" <OR 'T FALSE> ANY ANY)
239 Argument 1 -- Any object.
240 Argument 2 -- Any other object.
241 Returns -- T if the arguments are structurally equal, FALSE if they
244 Example: <=? <SET V <VECTOR 1 2 3>> <EVAL .V>>
246 If the test were ==?, the result would be FALSE.
248 ABS: Returns the Absolute value of a FIX or FLOAT.
254 Returns the absolute value of its argument.
258 Template: #DECL ("VALUE" <OR FIX FLOAT> <OR FIX FLOAT>)
260 Argument 1 -- A FIX or FLOAT to take the absolute value of.
261 Returns -- A FIX or FLOAT guaranteed non-negative.
263 Example: <ABS -69105>
265 Simple SUBR, simple example.
267 ACCESS: Position channel to given point in file
273 Reference: FILE-LENGTH
275 ACCESS makes the next character or binary word (depending on
276 the channel's mode) which will be input from or output to a channel
277 the (arg2+1)st one from the beginning of the file.
281 Template: #DECL ("VALUE" CHANNEL CHANNEL FIX)
283 Argument 1 -- the channel, open (not in "PRINT" mode) to DSK, USR, etc.
284 Argument 2 -- where to point for next i/o
285 Returns -- the channel
287 Example: <ACCESS .IN 0>
288 starts reading again from beginning of file
290 ACTIVATE-CHARS: Set or inspect interrupt characters for console typing (TENEX only)
294 AGAIN: Restart a FUNCTION, PROG, or REPEAT
298 Category: PROGRAM-CONTROL
300 Reference: FUNCTION, PROG, REPEAT
302 AGAIN takes one argument: an ACTIVATION. It means 'start doing
303 this again', where 'this' is specified by the ACTIVATION. Specifically,
304 AGAIN causes EVAL to return to where it started working on the body of
305 the FUNCTION, REPEAT, or PROG in the application specified by the
306 ACTIVATION. The application is not re-evaluated completely: no
307 rebinding of variables is done.
308 In a PROG or REPEAT, where there is always a defined ACTIVATION,
309 AGAIN with no arguments defaults to AGAIN of the top-level ACTIVATION
310 in the PROG or REPEAT.
314 Template: #DECL ("VALUE" ANY "OPTIONAL" ACTIVATION)
317 Argument 1 -- The ACTIVATION to restart. If not given, that of the
318 immediately surrounding PROG or REPEAT is used.
319 Returns -- Nothing, restarts the ACTIVATION.
321 Example: <PROG ((X <ILIST 20 '<MOD <RANDOM> 10>>))
322 <COND (<G=? <+ !.X> 100>
325 (ELSE <PRINT <LENGTH .X>>)>>
327 How many elements must be rested off before total of rest is less
328 than fifty? This could just as easily be a REPEAT, where the AGAIN is
331 ALLTYPES: Return the MUDDLE type VECTOR
335 Category: TYPE-MANIPULATION
337 ALLTYPES returns the user a pointer to the MUDDLE type vector.
338 Note that this is the real, honest-to-God type vector and that if you
339 clobber it you will clobber your MUDDLE, probably beyond repair.
340 The type vector contains ATOMs whose names are the types that are
341 currently defined to exist in the MUDDLE in which the ALLTYPES was
346 Template: #DECL ("VALUE" <VECTOR [REST ATOM]>)
348 Returns -- The MUDDLE type VECTOR.
351 Only possible example.
353 AND: Logical AND of its arguments.
357 Category: PREDICATE, PROGRAM-CONTROL
359 Reference: COND, OR, AND?
361 AND is an FSUBR that evaluates its arguments, one by one, until
362 either one of them returns a FALSE or it runs out of arguments.
363 The fact that it is an FSUBR means that it can be used as a
364 miniature COND. A construct of the form <AND preconditions thing> will
365 allow 'thing' to be executed only if 'preconditions' is true. In com-
366 bination with OR, fairly powerful constructs can be generated.
367 AND takes any number of arguments, returning either the result of
368 its last evaluation (T if no arguments were given) or the FALSE that
369 caused it to complete.
373 Template: #DECL ("VALUE" <OR FALSE ANY> "ARGS" LIST)
375 List of unevaluated arguments -- ANY evalable objects.
376 Returns -- Terminating FALSE or terminating non-FALSE.
378 Example: <AND <ASSIGNED? X> .X>
380 This construct attempts to take LVAL of X only if X is assigned, thus
381 avoiding the possibility of an ERROR.
383 AND?: Logical AND of its arguments, evaluated at call time
387 Category: PREDICATE, PROGRAM-CONTROL
389 Reference: OR?, AND, MAPF, MAPR
391 AND? is a SUBR that looks at its arguments, one by one, until
392 either one of them is a FALSE or it runs out of arguments.
393 The fact that it is a SUBR means that it can be used as a
394 first argument to MAPF or MAPR.
395 AND takes any number of arguments, returning either
396 its last argument (T if no arguments were given) or the FALSE that
397 caused it to complete.
401 Template: #DECL ("VALUE" <OR FALSE ANY> "TUPLE" TUPLE)
403 Tuple of evaluated arguments -- ANY objects.
404 Returns -- Terminating FALSE or terminating non-FALSE.
406 Example: <MAPF ,AND? <FUNCTION (T) <G? .T 0>> .VECTOR>
407 Are all elements of this vector positive?
409 ANDB: Bitwise logical AND
413 Category: BIT-TWIDDLING, LOGICAL
415 Reference: EQVB, ORB, XORB
417 ANDB takes any number of objects of Primtype WORD, and returns
418 a WORD containing the bitwise logical AND of the arguments.
422 Template: #DECL ("VALUE" WORD
423 "TUPLE" <TUPLE [REST <PRIMTYPE WORD>]>)
425 Tuple of arguments -- Objects of primtype WORD to be ANDed together.
426 Returns -- A WORD containing the bitwise AND of the arguments.
428 Example: <ANDB 511 4226793183>
430 Primarily useful for getting fingers directly in the bits.
432 APPLICABLE?: APPLICABLE? tests if its argument may be APPLYed.
438 APPLICABLE? takes a single object as argument, and returns T if
439 that argument may be APPLYed. That is, it may be the first element of
440 a FORM. Thus, an object of type FIX is applicable, as well as the more
441 obvious SUBR, FSUBR, RSUBR, FUNCTION, and so on.
442 If its argument is not applicable, returns FALSE.
446 Template: #DECL ("VALUE" <OR 'T FALSE> ANY)
448 Argument 1 -- ANY object to be tested for applicability.
449 Returns -- T if applicable, #FALSE() if not.
451 Example: <APPLICABLE? 69>
453 NTH makes this the case.
455 APPLY: Apply the first arg to the rest of them.
459 Category: PROGRAM-CONTROL
461 The first argument is applied to the rest of the arguments.
462 The manner in which the application is accomplished, is determined
463 by the TYPE of the first arg as follows:
465 FIX: call ,NTH with the 2nd arg and 1st arg.
467 SUBR: call the Subr with the rest of the args.
469 RSUBR or RSUBR-ENTRY: call the Rsubr with the rest of the args and
470 also compare them with the Rsubr's DECLs.
472 FUNCTION: Bind the Atoms in the parameter list of the Function
473 to the rest of the args of the APPLY matching one-to-one. Then
474 Bind the unsatisfied OPTIONALs, if any, and the EXTRAs to the
475 EVAL of their defaults. As each of the above Bindings is done,
476 the DECL for that variable is also checked. Now the elements of
477 the body of the Function are EVALed sequentially.
478 The result of the evaluation of the last element of the body
479 is the result of the Function application. It is checked against
480 the VALUE DECL of the Function, and returned.
482 CLOSURE: First Bind the Closure variables to their indicated
483 values. Then APPLY the Function part of the Closure as above.
485 Others: ERROR NON-APPLICABLE-TYPE
487 The manner in which the application is done for a particular Type can
488 be changed through the use of the subr APPLYTYPE.
492 Template: #DECL ("VALUE" ANY APPLICABLE "TUPLE"
495 Argument 1 -- The object to apply to the rest of the arguments.
496 Tuple of arguments -- The arguments the first argument is to be
498 Returns -- The result of applying the first argument to the rest.
500 Example: <APPLY <GET <TYPE .ITEM> ANALYSIS-ROUTINE> .ITEM>
502 This code will call a routine to process ITEM. The routine called
503 depends solely on the TYPE of ITEM. Therefore this represents the
504 idea of a dispatch table.
506 APPLYTYPE: Change or examine the way a TYPE is APPLYed
510 Category: TYPE-MANIPULATION, PROGRAM-CONTROL
512 Reference: APPLY, EVALTYPE
514 Changes the way a specific type is APPLYed, by either mapping
515 it into another type, or giving an explicit method via an APPLICABLE.
516 If a type is given, the type being changed will be APPLYed in the
517 same manner as that type.
518 If an APPLICABLE is given, it should take at least one argument,
519 which will be the object being APPLYed, and the rest of the arguments
520 will be what it is being APPLYed to. Whatever the APPLICABLE returns
521 will be the result of the APPLICATION. If ,APPLY is given, the type
522 will hereafter receive no special treatment in application to args.
523 If no second arg is given, APPLYTYPE returns the last second arg
524 given for this type, or #FALSE () if the type is receiving no special
525 treatment in application.
529 Template: #DECL ("VALUE" <OR ATOM APPLICABLE FALSE> ATOM "OPTIONAL"
530 <OR ATOM APPLICABLE>)
532 Argument 1 -- The type whose APPLYTYPE to change or examine.
534 Argument 2 -- A TYPE (which means 'Apply like this type'), or an
535 APPLICABLE (meaning 'use this when you APPLY this type').
536 Returns -- The TYPE which was changed or, if no second arg, the special
537 treatment this TYPE is receiving, if any.
541 '<FUNCTION (X "TUPLE" Y)
544 (<EMPTY? .Y> <RETURN .X>)
549 Make application of a LIST be like NTH
550 <(1 2 3 (4 5 6)) 4 2>
553 ARGS: Return the argument Tuple of an environment
557 Category: UTILITY, PROGRAM-CONTROL
559 Reference: FRAME, FUNCT, LEGAL?
561 Takes an environment and returns the argument TUPLE of the
562 top-level FRAME in that environment. The argument must be LEGAL? for
564 Note that the argument Tuple returned will become illegal once
565 the stack is popped past it.
569 Template: #DECL ("VALUE" TUPLE
570 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
572 Argument 1 -- The environment whose args tuple we want.
573 Returns -- The argument Tuple of the top FRAME in the environment we passed as arg 1.
575 Example: <* 3 <+ a 1>>
576 Gives an ERROR, first arg wrong type.
577 <ARGS <FRAME <FRAME>>>
579 The arguments of the frame that caused the ERROR.
581 ASCII: Convert Ascii codes to characters and back
585 Category: DATA-HANDLING
587 ASCII returns a CHARACTER given its 'ASCII' code (as a FIX)
588 or returns the ASCII code given the CHARACTER.
592 Template: #DECL ("VALUE" <OR CHARACTER FIX> <OR CHARACTER FIX>)
594 Argument 1 -- A CHARACTER or FIX to be transformed into the other.
595 Returns -- The opposite type to its argument.
599 The first returns the character A,
602 ASSIGNED?: Is an Atom locally assigned ?
606 Category: PREDICATE, IDENTIFIER
610 This routine is used to test if a particular Atom is locally
611 assigned, or in other words if it has a local value, in a given
612 environment, default the current one. It does cause the activation of
613 any read monitors on that local value.
614 It returns T if the ATOM has a local value, #FALSE () otherwise.
618 Template: #DECL ("VALUE" <OR 'T FALSE> ATOM "OPTIONAL"
619 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
621 Argument 1 -- An ATOM to test.
623 Argument 2 -- the environment in which to make the test
624 Returns -- T if the ATOM has a local value, #FALSE () otherwise.
626 Example: <SET FOO "ANYTHING">
628 This will return the Atom T, since FOO does have a local value.
631 This will return #FALSE (), since the Atom FOO has no local value.
632 <PROG (FOO) <ASSIGNED? FOO>>
633 This will also return #FALSE (), since FOO still does not have a local value
635 ASSOCIATIONS: Access the Association chain.
639 Category: ASSOCIATION
641 Reference: NEXT, AVALUE, INDICATOR, ITEM
643 ASSOCIATIONS gives the user access to the association chain in
644 much the same way as FRAME gives access to the stack. ASSOCIATIONS
645 returns the first association triad (item, indicator, value) in the
646 chain, as a type ASOC, which looks, but doesn't behave like, a LIST.
647 An ASOC may be passed to ITEM, INDICATOR, or AVALUE to retrieve
648 the elements of a triad, or to NEXT to retrieve the next association
653 Template: #DECL ("VALUE" <OR ASOC FALSE>)
655 Returns -- The first association in the association chain, FALSE if none exist.
657 Example: <ASSOCIATIONS>
658 Only possible example.
660 AT: Get a locative to a position in a Structure
664 Category: DATA-HANDLING
666 Reference: IN, SETLOC
668 Returns a locative to a position in a Structure (a VECTOR, LIST,
669 UVECTOR, STRING, etc.).
670 Takes a structure, and an optional FIX (default 1), like NTH or
671 REST, returning the locative.
675 Template: #DECL ("VALUE" LOCATIVE STRUCTURED "OPTIONAL" FIX)
677 Argument 1 -- A Structured object.
679 Argument 2 -- A FIX, default 1, the position in the structure.
680 Returns -- A Locative to the position in the structure.
682 Example: <SET FOO (1 2 3)>
691 ATAN: Arc-tangent of a tangent
699 Returns, in Radians, the angle whose tangent is the argument.
700 Note that all useful trig. functions may be derived using ATAN, COS,
705 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
707 Argument 1 -- The tangent of some angle.
708 Returns -- The angle whose tangent is argument 1.
710 Example: <ATAN </ <SIN .FOO> <COS .FOO>>>
713 ATOM: Create an ATOM not on any OBLIST
717 Category: DATA-HANDLING, IDENTIFIER
719 ATOM creates the ATOM with PNAME its argument (a STRING). The
720 resulting ATOM is not on any OBLIST, and thus has trailer !-#FALSE().
724 Template: #DECL ("VALUE" ATOM STRING)
726 Argument 1 -- The string which is the pname of the atom.
727 Returns -- The newly created ATOM.
728 Example: <ATOM "FOO">
729 FOO!-#FALSE() -- New ATOM not on any oblist.
731 AVALUE: Return the value part of an Association triad
735 Category: ASSOCIATION
737 Reference: ASSOCIATIONS, NEXT, ITEM, INDICATOR,
740 Given an ASOC, as returned by ASSOCIATIONS or NEXT, returns the
741 value part of the ASOC triad.
742 This is equivalent to <GETPROP item indicator> but uses the ASOC
743 instead of the item and indicator.
747 Template: #DECL ("VALUE" ANY ASOC)
749 Argument 1 -- An ASOC whose value field to get.
750 Returns -- The value field of the ASOC.
752 Example: <PUTPROP FOO BAR BLECH>
753 <AVALUE <ASSOCIATIONS>>
757 If this association is the most recent one made, the last two are equivalent.
759 BACK: Replace items RESTed off of a structure
763 Category: DATA-HANDLING
767 BACK replaces some items removed from a non-list stucture by
768 RESTing, that is, it moves the pointer to the structure back up the
770 It takes two arguments, the structure, and a fix which specifies
771 how many elements to return, and defaults to 1. An ERROR is generated
772 if there are not that many elements RESTed off the structure.
776 Template: #DECL ("VALUE" <OR VECTOR UVECTOR STRING TEMPLATE>
777 <PRIMTYPE <OR VECTOR UVECTOR STRING TEMPLATE>> "OPTIONAL"
780 Argument 1 -- The structure to return elements to.
782 Argument 2 -- Number of elements to return, default is 1.
783 Returns -- The structure with the elements returned.
791 .X, of course, is not changed by the BACK.
793 BIND: Execute sequential expressions without providing default activation
797 Category: PROGRAM-CONTROL
799 Reference: PROG, RETURN, AGAIN
801 This FSUBR is identical to PROG (q.v.), except that it
802 does not bind LPROG\ !-INTERRUPTS, and therefore RETURNs and AGAINs will
803 not default to it. This could prove useful to MACRO writers.
807 Template: #DECL ("VALUE" ANY "ARGS" <LIST ATOM LIST DECL ANY>)
809 Optional argument 1 -- An ATOM, to bind the activation of the BIND to.
810 Argument 2 -- A parameter LIST.
811 Optional argument 3 -- The DECL of the BIND.
812 Remainder of arguments -- At least one object, to be sequentially evaled.
813 Returns -- The last thing evaled in the BIND, or the argument to a
814 RETURN within the BIND.
816 Example: <BIND ((C <OPEN "READ" "FOO BAR">))
817 <COND (.C <FOO> <CLOSE .C>)>>
818 This will FOO only if the file FOO BAR exists.
820 BITS: Create a byte pointer.
824 Category: BIT-TWIDDLING
826 Reference: GETBITS, PUTBITS
828 BITS creates a byte pointer to a word. It takes two arguments,
829 the second optional. The first is the width of the byte in bits, the
830 second the right edge of the byte (counting from the least significant
831 bit of the word), which defaults to 0, meaning the rightmost bit.
832 A BITS is used with GETBITS and PUTBITS to get and put bytes from
833 objects of primtype WORD.
837 Template: #DECL ("VALUE" BITS FIX "OPTIONAL" FIX)
839 Argument 1 -- A FIX specifying the size of the byte pointed at.
841 Argument 2 -- A FIX specifying the right edge of the byte, default 0.
842 Returns -- A BITS, which may be used with GETBITS and PUTBITS to work
843 with bytes of actual machine words.
846 Points to a full PDP-10 word
848 Points to third Ascii character position in word
850 BLOAT-STAT: Get internal storage statistics
858 BLOAT-STAT fills its argument uvector with information about
859 the state of storage. The first 8 elements tell the number of GCs
860 attributable to various causes; the other 19 tell the sizes of various
861 areas of storage. For details see the manual, SYS.11.01.
865 Template: #DECL ("VALUE" <UVECTOR [27 FIX]>
866 "OPTIONAL" <UVECTOR [27 ANY]>)
869 Argument 1 -- a uvector of length 27 at least
870 Returns -- arg1 or a gratis uvector of storage statistics
872 Example: <BLOAT-STAT>
873 If no arg, a uvector is provided gratis.
875 BLOAT: Temporarily grow the garbage collected space.
879 Category: ENVIRONMENT
883 BLOAT provides a mechanism for temporary growth of the MUDDLE
884 garbage collected space as well as various stacks and special data
886 BLOAT takes from 0 to 15 arguments all of type FIX. The args are
887 described below in the Argument template field of this abstract.
888 Note that unless more than seven arguments are given, BLOAT will
889 not necessarily make any permanent change in the amount of space in
890 a MUDDLE -- the new space allocated may go away in the next following
891 GC if it is not filled.
892 BLOAT always returns the current number of free words.
896 Template: #DECL ("VALUE" FIX "OPTIONAL" FIX FIX FIX FIX FIX FIX FIX FIX FIX
897 FIX FIX FIX FIX FIX FIX)
900 Argument 1 -- Free space desired.
901 Argument 2 -- Main stack space desired.
902 Argument 3 -- Top level local slots desired.
903 Argument 4 -- Global value slots desired.
904 Argument 5 -- New type slots desired.
905 Argument 6 -- Non garbage collected words needed (STORAGE).
906 Argument 7 -- Auxiliary stack space desired (only useful for reading
908 Argument 8 -- Minimum space to get in all future GCs.
909 Argument 9 -- top-level local slots to add on future expansions
910 Argument 10 -- global-value slots to add on future expansions
911 Argument 11 -- type slots to add on future expansions
912 Argument 12 -- words of STORAGE to add on future expansions
913 Argument 13 -- words reserved for pure storage, if possible
914 Argument 14 -- most desirable size for auxiliary stack
915 Argument 15 -- most desirable size for main (control) stack
917 Example: <BLOAT 10000 10000 100 100 100>
918 Get lots of free and stack space.
920 BLOCK: Change the current OBLIST path.
924 Category: ENVIRONMENT
928 BLOCK changes the current OBLIST path by pushing the binding
929 of the ATOM OBLIST, and rebinding it to the arg of BLOCK.
930 BLOCK takes as argument a LIST of OBLISTs, of which one is in
931 most cases the ROOT OBLIST. An application of ENDBLOCK will return
932 the path to its previous state.
936 Template: #DECL ("VALUE" <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>
937 <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>)
939 Argument 1 -- The new LIST of OBLISTs to become the new path.
940 Returns -- Its argument.
942 Example: <BLOCK (<MOBLIST <PARSE <STRING !\I .FOO>> 23>
945 This is approximately what happens when the function RPACKAGE is
946 invoked. It creates a new path containing the internal oblist of the
947 RPACKAGE plus the ROOT.
949 BOUND?: Is an Atom locally bound ?
953 Category: PREDICATE, IDENTIFIER
957 This routine is used to test if a particular Atom is locally
958 bound, or in other words if it either has a local value or else has a
959 local binding which has not yet been assigned, in a given environment,
960 default the current one. It does cause the activation of any read
961 monitors on that local binding.
962 It returns T if the ATOM is locally bound, #FALSE() otherwise.
966 Template: #DECL ("VALUE" <OR 'T FALSE> ATOM "OPTIONAL"
967 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
969 Argument 1 -- An ATOM which may or may not have a local binding.
971 Argument 2 -- the environment in which to perform the test
972 Returns -- T if the ATOM has a local binding, #FALSE() otherwise.
974 Example: <SET FOO "ANYTHING">
976 This will return the Atom T, since FOO does have a local binding.
979 This will return #FALSE (), since the Atom FOO has no local binding.
980 <PROG (FOO) <BOUND? FOO>>
982 However this will also return the Atom T, since FOO does have a local
985 BREAK-SEQ: Stack an object for another PROCESS to EVAL when it is RESUMEd
989 Category: PROCESS-CONTROL
993 Takes an object and a PROCESS, and stacks the object in the PROCESS
994 such that when RESUMEd, the PROCESS will EVAL it before doing what it
995 would normally do. It thus 'breaks' the evaluation sequence in the
996 other PROCESS. Objects are stacked in the new process, and thus the
997 last BREAK-SEQed will be the first EVALed.
1001 Template: #DECL ("VALUE" PROCESS ANY PROCESS)
1003 Argument 1 -- The object to be stacked.
1004 Argument 2 -- The PROCESS to stack it in.
1005 Returns -- The PROCESS in which the object was stacked.
1007 Example: <BREAK-SEQ '<+ 1 1> <RESUMER>>
1008 Give the PROCESS that resumed me something to do.
1010 BUFOUT: Force out a channel's write buffer
1016 Reference: OPEN, CLOSE, RESET
1018 BUFOUT forces the buffers of a print channel out. It is used
1019 primarily as insurance against system crashes and other acts of God,
1020 to assure that all of the data created by a process will be output.
1021 It takes and returns a CHANNEL.
1025 Template: #DECL ("VALUE" CHANNEL "OPTIONAL" CHANNEL)
1027 (Optional arguments)
1028 Argument 1 -- A print CHANNEL to force buffers from.
1029 Returns -- The CHANNEL.
1031 Example: <BUFOUT .OUTCHAN>
1032 Flush buffers from OUTCHAN.
1034 BYTE-SIZE: Return the size of bytes of a BYTES
1040 Reference: BYTES, IBYTES
1042 BYTE-SIZE returns the size of all the bytes of a BYTES. This
1043 is the number of bits in all FIXes in the BYTES.
1047 Template: #DECL ("VALUE" FIX <PRIMTYPE BYTES>)
1049 Argument 1 -- A BYTES
1050 Returns -- A FIX, which is the size of bytes of the BYTES.
1052 Example: <BYTE-SIZE #2 {}>
1055 BYTES: Create a BYTES from FIXes
1059 Category: DATA-HANDLING
1063 BYTES creates a byte-string with explicit elements. These must be
1064 PRIMTYPE WORDs. They will be ANDBed with the appropriate mask and
1065 concatenated together to form a new BYTES.
1069 Template: #DECL ("VALUE" BYTES FIX "TUPLE" <TUPLE [REST <PRIMTYPE WORD>]>)
1071 Argument 1 -- the number of bits in each byte
1072 Tuple of arguments -- PRIMTYPE WORDs, the elements of the new BYTES
1073 Returns -- Newly created BYTES
1075 Example: <BYTES 2 0 1 2 3 4 5 6>
1078 CHANLIST: Get list of all open channels.
1082 Category: I/O, UTILITY
1084 Creates and returns a list of all OPEN channels in a MUDDLE.
1085 The first and second elements of this list are usually the TTY input
1086 and output channels of the MUDDLE.
1090 Template: #DECL ("VALUE" <LIST [REST CHANNEL]>)
1092 Returns -- A LIST of all the CHANNELs currently open in a MUDDLE.
1095 Only possible example
1097 CHANNEL: Create a CHANNEL.
1105 This SUBR is similar to OPEN, except that it only goes as far as
1106 creating the channel that OPEN would go on to OPEN. Its advantage
1107 is that the CHANNEL returned can be RESET just as though it had once
1109 It takes the identical arguments as OPEN but does not open the
1110 CHANNEL. For greater detail, see the Abstract of OPEN.
1114 Template: #DECL ("VALUE" CHANNEL "OPTIONAL" STRING
1118 Argument 1 -- A STRING giving the direction and type of OPEN to not do.
1119 Argument 2 -- STRINGs and/or FIXes giving the specification of the
1121 Returns -- An unOPENed CHANNEL.
1123 Example: <CHANNEL "PRINT" "FOO BAR">
1124 Return an unopened PRINT channel.
1126 CHTYPE: Change the type of a MUDDLE object.
1130 Category: TYPE-MANIPULATION
1132 Changes the type of a MUDDLE object (or, more exactly, a given
1133 type-value pair). The allowable changes are among types of the same
1134 PRIMTYPE. For example, WORDs may be CHTYPEd to FIXes, but VECTORs may
1135 not be CHTYPEd to LISTs. CHTYPE does not affect any other pointers to
1136 the object that may exist.
1137 Some objects which have the same primtype may not be CHTYPEd to
1138 each other, for example, a VECTOR may not be CHTYPEd to a CHANNEL.
1139 This is because some types (like CHANNEL) are controlled and may be
1140 created only in special ways.
1141 Takes as arguments the object to be CHTYPEd, and an ATOM giving
1142 the name of the type to CHTYPE it to.
1146 Template: #DECL ("VALUE" ANY ANY ATOM)
1148 Argument 1 -- Any (or almost any) object.
1149 Argument 2 -- An ATOM which is the name of a type.
1150 Returns -- Argument 1 with its type changed to type argument 2.
1152 Example: <SET X (+ 1 2)>
1160 But the original is untouched
1162 CHUTYPE: Change the uniform type of a UVECTOR
1166 Category: TYPE-MANIPULATION
1170 CHUTYPE changes the uniform type (UTYPE) of a UVECTOR. The
1171 types to which the UTYPE may be changed are restricted in the same way
1172 as the changes allowed by CHTYPE are restricted. Thus a UVECTOR of
1173 UTYPE LIST cannot be changed to one of UTYPE VECTOR, but one of UTYPE
1174 FORM may be changed to one of UTYPE LIST. A UTYPE of LOSE may be
1175 CHUTYPEd to anything that a UVECTOR may legally contain.
1179 Template: #DECL ("VALUE" <PRIMTYPE UVECTOR>
1180 <PRIMTYPE UVECTOR> ATOM)
1182 Argument 1 -- A UVECTOR whose UTYPE wants to be changed.
1183 Argument 2 -- An ATOM whose name is the name of the type to change the
1184 UTYPE of the UVECTOR to.
1185 Returns -- The UVECTOR with a new UTYPE.
1187 Example: <SET X ![() () () () ()!]>
1193 Note all references to UVECTOR get new UTYPE.
1195 CLOSE: Close an I/O channel
1201 Reference: OPEN, BUFOUT, RESET
1203 CLOSE takes as argument a CHANNEL, and causes it to be closed.
1204 Its buffers are written out if it is a PRINT channel. The channel
1205 may be reopened using RESET, for many types of devices.
1206 The CHANNEL closed is returned.
1210 Template: #DECL ("VALUE" CHANNEL CHANNEL)
1212 Argument 1 -- A CHANNEL to close.
1213 Returns -- The closed CHANNEL.
1215 Example: <RESET <CLOSE <OPEN "READ" "DSK:FOO BAR">>>
1217 This pointless form will cause a CHANNEL to be opened (assuming the
1218 file exists), closed, and then reopened.
1220 CLOSURE: Bind the free variables of a Function to current values
1224 Category: TYPE-MANIPULATION
1226 The CLOSURE Subr creates an object of Type CLOSURE. A CLOSURE
1227 can be applied like a FUNCTION, the only difference being that first
1228 the Atoms given in the call to the CLOSURE subr are bound to the values
1229 thay had when the CLOSURE was generated. Then the Function is applied
1230 as normal in this new environment.
1231 A CLOSURE is a poor man's FUNARG.
1235 Template: #DECL ("VALUE" CLOSURE FUNCTION "TUPLE"
1236 <TUPLE [REST ATOM]>)
1238 Argument 1 -- A FUNCTION which will be the application part of the
1240 Tuple of arguments -- ATOMs whose current values are to be stored as
1241 the binding part of the CLOSURE.
1242 Returns -- A CLOSURE.
1244 Example: <CLOSURE <FUNCTION (X)
1245 <SET .X <+ ..X .INC>>>
1248 This will create a Closure which can later be applied to an Atom.
1249 When applied it will then increment the local value of that Atom.
1250 The amount of the increment is determined by the current value of INC.
1251 Note that any future changes to the value of INC will not affect
1252 the amount of the increment peformed by the Closure.
1254 COND: CONDitional evaluation on the basis of a predicate
1258 Category: PREDICATE, PROGRAM-CONTROL
1262 COND is an FSUBR used to control evaluation on the basis of a
1263 number of predicates. It takes any non-zero number of arguments, each
1264 of which is a list of a least one element.
1265 For each list, starting with the first, the first element of the
1266 list is evaluated, and if its result is non-false, the rest of the
1267 elements of that list are evaluated and the last thing returned by
1268 one of them is returned as the value of the COND (this will be the
1269 predicate itself if it is the only object in the list.
1270 If the predicate returns a FALSE, then COND moves on to the next
1271 list, or, if there are no more lists, the last FALSE returned is the
1276 Template: #DECL ("VALUE" ANY "ARGS" <LIST LIST [REST LIST]>)
1278 Tuple of arguments -- At least one list, of which the first element
1279 is the 'IF', and the rest the 'THEN'.
1280 Returns -- The result of the last EVAL under its control.
1282 Example: <COND (<SET C <OPEN "READ" "FOO BAR">>
1286 A common use of COND is to fend off the possibility of lossage by
1287 setting up a screen of conditions. Note that if the file is not
1288 opened, the reason will be returned (the last FALSE).
1290 CONS: Add an item to the front of a LIST
1294 Category: DATA-HANDLING
1298 CONS adds an item to the front of a list, without copying it.
1299 It is equivalent to making a list of the new item and the old list
1301 <CONS .FOO .THE-LIST>
1303 are the same. In fact, the segment evaluation method is preferred, as
1304 it is compilable into a PUSHJ.
1308 Template: #DECL ("VALUE" LIST ANY LIST)
1310 Argument 1 -- An object.
1311 Argument 2 -- A LIST to which the object should be prefixed.
1312 Return -- A new list which points into the old one -- the old one is
1315 Example: <CONS 1 (2 3 4)>
1316 note that this is equivalent to (1 !'(2 3 4))
1318 COS: Cosine of an angle
1322 Category: ARITHMETIC
1324 Reference: SIN, ATAN
1329 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
1331 Argument 1 -- the angle in radians.
1332 Returns -- A FLOAT, the Cosine.
1334 Example: <+ <* <COS .X> <COS .X>>
1335 <* <SIN .X> <SIN .X>>>
1337 One of the common trig. identities.
1339 CRLF: Print a carriage-return and line-feed
1350 Template: #DECL ("VALUE" 'T "OPTIONAL" CHANNEL)
1353 Argument 1 -- the channel, default .OUTCHAN
1358 Output carriage-return and line-feed.
1360 DECL-CHECK: Change or examine the state of DECL checking
1364 Category: TYPE, UTILITY
1366 Changes the state of MUDDLE's DECL checking. Initially turned
1367 on, it may be disabled by <DECL-CHECK #FALSE()>, or enabled by
1368 <DECL-CHECK T>. When enabled, each attempt to set an ATOM is checked
1369 against any available DECL of that ATOM. An ERROR is generated if the
1370 DECL does not match the value to which the ATOM will be set.
1374 Template: #DECL ("VALUE" <OR FALSE ANY>
1375 "OPTIONAL" <OR FALSE ANY>)
1378 Argument 1 -- Any MUDDLE object. Non-false to enable DECL checking,
1379 False to disable it.
1380 Returns -- The old state.
1382 Example: <DECL-CHECK T>
1383 Enables DECL checking.
1385 DECL?: Check an object against a DECL Pattern
1389 Category: DATA-HANDLING, PREDICATE
1391 DECL? is a predicate that tells whether or not an object
1392 satisfies a type/structure declaration.
1396 Template: #DECL ("VALUE" <OR 'T FALSE>
1397 ANY <OR ATOM <FORM 'QUOTE FORM>>)
1399 Argument 1 -- an object to be checked
1400 Argument 2 -- a QUOTEd Pattern to check it against
1401 Returns -- T or a FALSE
1403 Example: <DECL? '[1 2 3] '<VECTOR [REST FIX]>>
1405 note QUOTE on Pattern
1407 DEFINE: Define a FUNCTION
1411 Category: DATA-HANDLING
1413 Reference: FUNCTION, DEFMAC
1415 DEFINE sets the global value of an atom to the function it
1416 creates from the rest of the arguments. It also checks to see if the
1417 atom was already 'defined', if so and if the atom REDEFINE is non
1418 false, it complains. Otherwise this fsubr operates like FUNCTION plus
1423 Template: #DECL ("VALUE" ATOM ATOM "ARGS" LIST)
1425 Argument 1 -- The atom whose GVAL to make the function.
1426 List of arguments -- If the first element of the list is an atom the
1427 activation is bound to it, the rest is the arg list, DECL, and
1428 body of the function.
1429 Returns -- Argument 1.
1431 Example: <DEFINE FACTORIAL (N)
1436 <FACTORIAL <- .N 1>>>)>>
1437 Then <FACTORIAL 4> returns 24
1439 DEFMAC: Define an EVAL Macro
1443 Category: IDENTIFIER
1445 Reference: DEFINE, EXPAND
1447 DEFMAC is syntactically exactly the same as DEFINE. However,
1448 instead of creating a FUNCTION, DEFMAC creates a MACRO. A MACRO is
1449 of primtype LIST, and in fact has a FUNCTION (or other applicable type)
1450 as its single element.
1451 MACROs are applied in a funny way, however. It is EVALed
1452 twice. The first EVAL causes the macro's element to be applied to the
1453 macro's arguments. Whatever it returns (usually another form) is also
1454 evaled, and the result of the second evaluation is the result of
1456 To avoid complications, the first eval (to create the object to
1457 be evaled in the second...) is done at top-level. The result of this
1458 policy is that two syntactically identical invocations of a macro
1459 should always return the same thing to be evaled in the second EVAL.
1460 EXPAND (qv) is used to perform the first EVAL without the second.
1464 Template: #DECL ("VALUE" ATOM ATOM "ARGS" LIST)
1466 Argument 1 -- The atom whose GVAL is to be the MACRO.
1467 Argument 2 -- The parameter list.
1468 Tuple of arguments -- The body of the macro.
1469 Returns -- Argument 1.
1471 Example: <DEFMAC INC (ATM "OPTIONAL" (N 1))
1483 The standard INC hack, in EVAL-macro form.
1485 DEMSIG: Signal a system Daemon
1491 DEMSIG signals to a system Daemon that it should run. It takes
1492 a STRING, which is the name of the Daemon in the system's tables, and
1493 causes a signal to it to be sent.
1494 Returns T if the Daemon exists, FALSE otherwise.
1498 Template: #DECL ("VALUE" <OR 'T FALSE> STRING)
1500 Argument 1 -- A STRING giving the name of a Daemon.
1501 Returns -- T if exists, FALSE otherwise.
1503 Example: <DEMSIG "COMDMN">
1504 Signal the communication Daemon.
1506 DISABLE: Disable an interrupt
1514 DISABLE causes the interrupt associated with the IHEADER which
1515 is its argument to be disabled. Disabled interrupts are ignored as
1520 Template: #DECL ("VALUE" IHEADER IHEADER)
1522 Argument 1 -- The IHEADER whose interrupt is to be disabled.
1523 Returns -- Argument 1.
1525 Example: <DISABLE <GET .INCHAN INTERRUPT>>
1526 Disable the ^G and ^S interrupts.
1528 DISMISS: Dismiss an interrupt
1534 Reference: INT-LEVEL, HANDLER
1536 DISMISS allows an interrupt handler to dismiss an interrupt
1537 returning a value, to an arbitrary activation, at an arbitrary int-
1538 level. Only the value is required. If the activation is not given
1539 the return is to the place interrupted from. If the int-level is not
1540 given, the int-level is restored to what it was prior to the invocation
1545 Template: #DECL ("VALUE" ANY ANY "OPTIONAL" ACTIVATION FIX)
1547 Argument 1 -- The value.
1549 Argument 2 -- The activation to return the value from. Default, the
1550 place from which the HANDLER was invoked.
1551 Argument 3 -- The interrupt level to set on return. Default the one
1552 prior to invocation of the HANDLER.
1553 Returns -- The first argument.
1555 Example: <DISMISS #FALSE ("FATAL ERROR DEEP IN GUTS")
1556 .TOP-LEVEL-ACTIVATION>
1558 A construct like this could be used to signal to a higher level that
1559 somewhere in the code below it, a fatal error occured.
1561 DISPLAY: Display a PICTURE on a Display Channel [OBSOLETE]
1563 ******* This SUBR is obsolete as of MUD55 *******
1569 Reference: ERASE, OPEN,
1570 MUDDLE GRAPHICS USER'S MANUAL, SYS.11.04, Bruce Daniels, Ed Black
1572 DISPLAY takes two arguments, a CHANNEL opened in DISPLAY mode,
1573 and a PICTURE. The picture is displayed on the device associated with
1574 the display channel. If no second argument is given, the display on
1575 that device will be refreshed. This is useful if the device is a
1576 display console such as an IMLAC or ARDS.
1580 Template: #DECL ("VALUE" CHANNEL CHANNEL "OPTIONAL" PICTURE)
1582 Argument 1 -- A CHANNEL open in display mode.
1584 Argument 2 -- A PICTURE to display on the CHANNEL. If not given, the
1585 display is refreshed only.
1586 Returns -- The CHANNEL.
1588 Example: <SET D <OPEN "DISPLAY" "E&S:">>
1590 Where PIC is a Picture created previously in some manner.
1592 ECHOPAIR: Pair up console channels for echoing
1598 ECHOPAIR makes its two argument channels 'know about each other'
1599 so that rubout, ^@, ^D, and ^L will work between them.
1603 Template: #DECL ("VALUE" CHANNEL CHANNEL CHANNEL)
1605 Argument 1 -- console-input channel
1606 Argument 2 -- console-output channel
1609 Example: <ECHOPAIR .INCHAN .OUTCHAN>
1612 EMPTY?: Does a structure have zero elements ?
1616 Category: PREDICATE, DATA-HANDLING
1620 This routine tests if a given structured object has a length of
1621 zero. Note that EMPTY? works correctly for circular Lists, which have
1622 no well-defined length.
1626 Template: #DECL ("VALUE" <OR 'T FALSE> STRUCTURED)
1628 Argument 1 -- Any structured object.
1629 Returns -- T if the structured object has no elements, #FALSE () if it
1630 has any elements at all.
1632 Example: <EMPTY? "---args---">
1633 This will return #FALSE ().
1635 However, this will return T.
1637 ENABLE: Enable an interrupt
1645 ENABLE causes the interrupt associated with the IHEADER which is
1646 its argument to be enabled. This causes the interrupt HANDLERS
1647 associated with the IHEADER to be run when the interrupt occurs.
1648 ENABLEing an already enabled interrupt does nothing.
1652 Template: #DECL ("VALUE" IHEADER IHEADER)
1654 Argument 1 -- An IHEADER whose interrupt is to be enabled.
1655 Returns -- Argument 1.
1657 Example: <ENABLE <GET CLOCK!-INTERRUPTS INTERRUPT>>
1658 Enable a clock interrupt.
1660 ENDBLOCK: Undoes the effect of BLOCK, returning a previous OBLIST path
1664 Category: IDENTIFIER, ENVIRONMENT
1668 ENDBLOCK pops a value of the ATOM OBLIST, returning the OBLIST
1669 path to a previous state. It therefore undoes the effect of a BLOCK.
1670 If no BLOCK has been done, produces an ERROR.
1671 It returns the new OBLIST path.
1675 Template: #DECL ("VALUE"
1676 <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>)
1678 Returns -- The previous OBLIST path, now restored.
1681 Only possible example.
1683 ENTRY-LOC: Return the offset of an RSUBR-ENTRY
1687 Category: DATA-HANDLING
1689 Reference: RSUBR-ENTRY, RSUBR
1691 This routine will return the offset of an RSUBR-ENTRY into an
1692 RSUBR. This will be the same offset that was supplied to create the
1697 Template: #DECL ("VALUE" FIX RSUBR-ENTRY)
1699 Argument 1 -- An RSUBR-ENTRY whose offset is to be returned.
1700 Returns -- A FIX, the offset of the RSUBR-ENTRY in its RSUBR.
1702 Example: <ENTRY-LOC <RSUBR-ENTRY [,FOO FOO1] 347>>
1704 This will return the offset given to RSUBR-ENTRY, which is the 347.
1706 EQVB: Bitwise logical EQV of its arguments
1710 Category: LOGICAL, BIT-TWIDDLING
1712 Reference: ANDB, ORB, XORB
1714 EQVB takes any number of arguments of Primtype WORD, and returns
1715 a WORD that is their bitwise logical EQV, that is, the bits they have
1720 Template: #DECL ("VALUE" WORD <TUPLE [REST <PRIMTYPE WORD>]>)
1722 Tuple of arguments -- Primtype WORDs to be EQVed together.
1725 Example: <EQVB -22906492246 22906492245>
1726 #WORD *000000000000*
1729 ERASE: Erase a picture from a Display Channel [OBSOLETE]
1731 ******* This SUBR is obsolete as of MUD55 *******
1737 Reference: DISPLAY, OPEN,
1738 MUDDLE GRAPHICS USER'S MANUAL, SYS.11.04, Bruce Daniels, Ed Black
1740 ERASE takes two arguments, the second optional. The first is a
1741 CHANNEL open in Display mode. The second is a picture. ERASE causes
1742 the picture to be removed from the display on that CHANNEL. If the
1743 second argument is not given, all the pictures on that CHANNEL will be
1744 removed, leaving an empty display.
1748 Template: #DECL ("VALUE" CHANNEL CHANNEL "OPTIONAL" PICTURE)
1750 Argument 1 -- A CHANNEL open in display mode.
1752 Argument 2 -- A PICTURE to erase from the CHANNEL. If not given, all
1753 of the pictures on the CHANNEL are ERASEd.
1754 Returns -- The CHANNEL.
1756 Example: <SET D <OPEN "DISPLAY" "E&S:">>
1760 Display PIC and then remove it. (Where PIC is a Picture created
1761 previously in some manner).
1763 ERRET: Return a value as the value of a FRAME
1767 Category: PROGRAM-CONTROL
1769 Reference: RETRY, RETURN
1771 ERRET is used to return values from FRAMEs. It takes two
1772 optional arguments, a value to return, and a FRAME. If defaulted,
1773 the FRAME is the frame of the last invocation of ERROR or LISTEN, and
1774 if both are defaulted, it means to return to TOPLEVEL and reenter the
1776 ERRET is used most often to recover from errors, by returning
1777 a reasonable argument from the frame that called ERROR.
1781 Template: #DECL ("VALUE" ANY "OPTIONAL" ANY FRAME)
1784 Argument 1 -- The value to return from the FRAME given in arg2.
1785 Argument 2 -- The FRAME from which to return the value given.
1786 Returns -- Argument 1.
1790 Single most common use of ERRET -- continue from REDEFINE ERROR,
1791 return something innocuous as value of funny atom, and so on.
1793 ERROR: Announce an ERROR
1801 ERROR is used to announce an ERROR in a program. It takes any
1802 number of arguments, which will be printed as ERROR recurses to a
1803 higher level LISTEN loop.
1804 The usual format is to give an ATOM which is the reason for the
1805 ERROR, the routine in which it occurred, and any other information of
1810 Template: #DECL ("VALUE" ANY "TUPLE" TUPLE)
1812 Tuple of arguments -- ANY number of arguments of any type.
1813 Returns -- Whatever the user ERRETs from it.
1815 Example: <ERROR RAN-OUT-OF-INPUT!-ERRORS INPUT-HANDLER>
1816 Most common ERROR call format is this.
1818 ERRORS: Returns the ERRORS OBLIST
1824 Reference: ERROR, ROOT
1826 ERRORS returns the ERRORS OBLIST. This is the OBLIST on which
1827 live the ATOMs whose PNAMEs are the MUDDLE ERROR messages.
1831 Template: #DECL ("VALUE" OBLIST)
1833 Returns -- The ERRORS OBLIST.
1836 Only possible example.
1838 EVAL: Evaluate an expression in a given envirnoment
1842 Category: PROGRAM-CONTROL
1844 EVAL is a program control subr. The first arg to EVAL is the MUDDLE
1845 expression to be evaluated. The second, optional, arg is the execution
1846 environment in which the evaluation is to take place. If the second
1847 arg is not supplied the current environment of the current process will
1849 Every Type in MUDDLE has a defined, or default, rule for evaluation
1850 of MUDDLE objects of that Type. See EVALTYPE on how to change these
1852 The initial EVAL rules for MUDDLE Types are:
1855 EVAL of empty FORM is #FALSE ()
1856 If <1 <-Form-> > is an ATOM,
1857 then, APPLY either GVAL of Atom or VALUE of the Atom to the
1858 appropriately EVALed or unEVALed args.
1859 else, APPLY the EVAL of <1 <-Form-> > to the appropriately EVALed
1861 Note that the subsequent EVAL of an arg which is of Type SEGMENT
1862 is treated specially.
1864 LIST or VECTOR or UVECTOR--
1865 make a new structured object of the same Type whose elements
1866 are the EVALuated elements of the given object.
1867 Note that the EVAL of an element of the structure
1868 which is of Type SEGMENT is also treated specially.
1871 Evaluate to themselves.
1875 Template: #DECL ("VALUE" ANY ANY "OPTIONAL"
1876 <OR ACTIVATION FRAME ENVIRONMENT PROCESS>)
1878 Argument 1 -- ANY object to be EVALed.
1880 Argument 2 -- An ACTIVATION, FRAME, ENVIRONMENT, or PROCESS in which
1881 to perform the evaluation.
1882 Returns -- The result of the EVAL, as described above.
1884 Example: <EVAL '<SET X <+ .X 1>> <RESUMER>>
1886 This will increment the local value of the Atom X in the process
1887 which last resumed the current process.
1888 Note that the value of X in the current process, if any, will not
1891 EVALTYPE: Change or examine the way a TYPE is EVALed
1895 Category: TYPE-MANIPULATION, PROGRAM-CONTROL
1897 Reference: EVAL, APPLYTYPE
1899 Changes the way a specific type is EVALed, by either mapping
1900 it into another type, or giving an explicit method via an APPLICABLE.
1901 If a type is given, the type being changed will be EVALed in the
1902 same manner as that type.
1903 If an APPLICABLE is given, it should take one argument,
1904 which will be the object being EVALed. Whatever the APPLICABLE returns
1905 will be the result of the EVALuation. If ,EVAL is given, the type
1906 will hereafter receive no special treatment in evaluation.
1907 If no second arg is given, EVALTYPE returns the last second arg
1908 that was given for this type, or #FALSE () if the type is receiving no
1909 special treatment in evaluation.
1913 Template: #DECL ("VALUE" <ATOM APPLICABLE FALSE> ATOM "OPTIONAL"
1914 <OR ATOM APPLICABLE>)
1916 Argument 1 -- The type whose EVALTYPE to change or examine.
1918 Argument 2 -- A TYPE (which means 'Eval like this type'), or an
1919 APPLICABLE (meaning 'use this when you EVAL this type').
1920 Returns -- The TYPE which was changed or, if no arg 2, the special
1921 treatment it is receiving if any.
1923 Example: <EVALTYPE LIST FORM>
1924 <EVALTYPE ATOM ,LVAL>
1927 <SETG LAMBDA ,FUNCTION>
1928 This will set up MUDDLE to look like LISP to the casual user:
1937 EVENT: Set up an IHEADER for an event
1943 Reference: DISABLE, ENABLE
1945 EVENT sets up an IHEADER for either an external or internal
1946 interrupt. No handlers are attached to the IHEADER set up by EVENT.
1947 The first argument to EVENT identifies the interrupt. It may be
1948 a string or an atom on the INTERRUPTS OBLIST. In either case if the
1949 name is associated with a physical interrupt, the real interrupt is
1950 set up. The first argument may also be a previously OFFd IHEADER.
1951 The second argument is the priority of this interrupt and it must
1952 be a positive fixed point number. The priority basically specifies
1953 how important this interrupt is relative to other interrupts.
1954 If the first argument to EVENT is either CHAR!-INTERRUPTS,
1955 READ!-INTERRUPTS or WRITE!-INTERRUPTS or the strings with those names,
1956 a third argument is required. For CHAR this must be a TTY input
1957 channel and for the others it must be the locative getting the READ or
1962 Template: #DECL ("VALUE" IHEADER <OR STRING ATOM IHEADER> FIX
1963 "OPTIONAL" <OR CHANNEL LOCATIVE>)
1965 Argument 1 -- The name of the interrupt.
1966 Argument 2 -- A priority.
1968 Argument 3 -- A CHANNEL, for character interrupts, or LOCATIVE, for monitors
1969 Returns -- An IHEADER.
1971 Example: <SET TEM <EVENT "SYSDOWN" 1>>
1972 Setup a SYSDOWN interrupt.
1974 EXP: Exponents of 'e'
1978 Category: ARITHMETIC
1982 EXP is the opposite of LOG, taking e to a power. It takes a FIX
1983 or FLOAT as argument, and returns e to that power, converted to a FLOAT
1984 whether the argument was fix or float.
1988 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
1990 Argument 1 -- A FIX or FLOAT to take e to the power of.
1991 Returns -- (e ** <argument 1>)
1993 Example: <EXP <LOG 2>>
1995 Note conversion to floating point number.
1997 EXPAND: Expand a MACRO
2001 Category: ENVIRONMENT, UTILITY
2005 EXPAND evaluates its argument in a top-level environment, that is, as
2006 if no LVALs existed. It is designed to perform the first evaluation
2007 in a MACRO application, but it can be useful in other cases.
2011 Template: #DECL ("VALUE" ANY ANY)
2013 Argument 1 -- an object to evaluate
2014 Returns -- the top-level value of the object or 'body' of the MACRO
2016 Example: <DEFMAC INC (ATM "OPTIONAL" (N 1))
2025 Note that <EVAL '<INC X>> would EVAL this last form too.
2027 FILE-EXISTS?: Check for existence of a file
2035 FILE-EXISTS? takes arguments like the second and higher arguments
2036 to OPEN (q.v.). It returns T if the file thus specified exists, otherwise
2037 a FALSE of two elements: the error message and error code returned by the
2042 Template: #DECL ("VALUE" <OR FALSE ATOM> "TUPLE" <REST STRING>)
2044 Argument 1-4 -- file names
2045 Returns -- T if file exists, a FALSE otherwise
2047 Example: <FILE-EXISTS? "DSK:FOO;.FILE. (DIR)">
2048 Will return T if FOO is a real directory.
2050 FILE-LENGTH: Get length of input file
2058 FILE-LENGTH tells the length (in characters or binary words,
2059 depending on the channel's mode) of the disk file open for input on its
2064 Template: #DECL ("VALUE" FIX CHANNEL)
2066 Argument 1 -- input disk channel
2067 Returns -- length of disk file
2069 Example: <ACCESS .IN <FILE-LENGTH .IN>>
2070 Next input will detect end of file.
2072 FILECOPY: Copy entire file from one channel to another
2078 Reference: FILE-LENGTH
2080 FILECOPY copies characters from an input channel (arg1) to an
2081 output channel (arg2) until the end of file, thus closing the input
2082 channel. A FILE-LENGTH on arg1 must win, ruling out certain devices.
2086 Template: #DECL ("VALUE" FIX "OPTIONAL" CHANNEL CHANNEL)
2089 Argument 1 -- source (input) channel, default .INCHAN
2090 Argument 2 -- destination (output) channel, default .OUTCHAN
2091 Returns -- number of characters copied
2093 Example: <FILECOPY <OPEN "READ" "TTY:.FILE. (DIR)">>
2096 FIX: Convert a FLOAT to a FIX
2100 Category: TYPE-MANIPULATION, ARITHMETIC
2104 FIX takes a FLOAT and converts it to a FIX, truncating the
2109 Template: #DECL ("VALUE" FIX <OR FLOAT FIX>)
2111 Argument 1 -- A FLOAT to convert
2112 Returns -- A FIX corresponding to the FLOAT.
2114 Example: <FIX 69.910496>
2116 Note the truncating.
2118 FLATSIZE: Return the size of an object within a maximum
2122 Category: DATA-HANDLING, I/O
2126 FLATSIZE returns the number of characters needed to PRINT an
2127 item, if it is less than the bound (thus winning on self-referencing things).
2128 If it is greater than the upper bound, returns #FALSE ().
2132 Template: #DECL ("VALUE" <OR FALSE FIX> ANY FIX "OPTIONAL" FIX)
2134 Argument 1 -- The object to 'PRINT'.
2135 Argument 2 -- The upper bound on size of the object.
2137 Argument 3 -- radix for FIX conversion
2138 Returns -- The size, if less than the bound, or #FALSE () if not.
2140 Example: <FLATSIZE (1 2 3) 10>
2141 Will be a fix result
2142 <FLATSIZE (1 2 3) 5>
2145 FLOAD: READ and EVAL every object in a file
2151 Reference: READ, EVAL, LOAD, UNWIND, OPEN
2153 FLOAD opens a file, READs and EVALs every object in it, and
2154 closes it again. If the opening fails, an ERROR occurs, giving the
2155 reason for failure. A (list of) oblist(s) may also be given for
2156 looking up atoms. Control characters in the file have no special
2157 meaning. An UNWIND is set up to close the channel on any ERRET.
2161 Template: #DECL ("VALUE" '"DONE" "TUPLE" TUPLE)
2164 Tuple of arguments -- string(s) as for OPEN and/or oblist as for READ
2167 Example: <FLOAD "MUDDLE;FIXUP">
2168 part of initialization for TS file
2170 FLOAT: Convert a FIX to a FLOAT
2174 Category: TYPE-MANIPULATION, ARITHMETIC
2181 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
2183 Argument 1 -- A FIX to convert to a FLOAT.
2184 Returns -- The new FLOAT.
2188 CHTYPE would lose, of course.
2190 FORM: Create a FORM with explicit arguments
2194 Category: DATA-HANDLING
2198 FORM creates a FORM of explicit arguments. This is the way to
2199 make a form with the elements evaluated.
2203 Template: #DECL ("VALUE" FORM "TUPLE" <TUPLE [REST ANY]>)
2205 Tuple of arguments -- Any objects, the elements of the FORM.
2206 Returns -- The FORM created.
2208 Example: <DEFINE INCR (N)
2211 <FORM + 1 <FORM LVAL .N>>>>
2212 this returns the form <SET FOO <+ 1 .FOO>> when called with FOO as arg
2214 FRAME: Walk the chain of stack frames
2218 Category: ENVIRONMENT, UTILITY
2220 Reference: FUNCT, ARGS
2222 FRAME returns the 'previous' stack-frame on the stack. This
2223 means that given a FRAME, it returns the FRAME that generated it. If
2224 no FRAME is given, it returns the topmost FRAME on the stack.
2225 Given an ACTIVATION or ENVIRONMENT, it returns the appropriate FRAME.
2226 When the stack 'runs out', i.e., the end is reached, it returns
2228 In conjunction with ARGS and FUNCT, makes a powerful debugging
2230 FRAME, ARGS, and FUNCT may also get access to the stack frames
2231 of other processes, by giving the process as an argument. If this
2232 feature is used, returns the topmost FRAME of that process.
2236 Template: #DECL ("VALUE" FRAME
2237 "OPTIONAL" <OR ENVIRONMENT
2243 Argument 1 -- Either nothing, meaning return topmost FRAME of this
2244 PROCESS, or a FRAME, meaning return next FRAME of this PROCESS,
2245 or an environment, meaning return topmost FRAME of this
2247 Returns -- As described above, a FRAME, or #FRAME TOPLEVEL when the
2248 end of the stack is reached.
2250 Example: <DEFINE FRAMES ("OPTIONAL" (PROC <ME>))
2251 <REPEAT ((X <FRAME .PROC>)
2253 <COND (<==? <FUNCT .X> TOPLEVEL>
2261 A primitive version of the FRAMES function installed in MUDDLE.
2263 FREE-RUN: Returns a PROCESS to free running state
2267 Category: PROCESS-CONTROL
2271 Puts a PROCESS back into a free running state after it has been
2272 in one-step mode. Takes a PROCESS as argument.
2276 Template: #DECL ("VALUE" <OR PROCESS FALSE> PROCESS)
2278 Argument 1 -- A PROCESS to return to normal running mode.
2279 Returns -- The PROCESS, or FALSE if PROCESS not in one-step mode.
2281 Example: <FREE-RUN .FOO>
2282 Now will run free when RESUMEd.
2284 FREE: Free non-garbage collected STORAGE [OBSOLETE]
2286 ******* This SUBR is obsolete as of MUD55 *******
2290 Category: DATA-HANDLING
2294 FREE de-allocates non-garbage collected storage (mostly used for
2295 E&S display). Once it has been free'd it will be used by STORE again.
2299 Template: #DECL ("VALUE" <PRIMTYPE STORAGE> <PRIMTYPE STORAGE>)
2301 Argument 1 -- A storage: the space to be released.
2302 Returns -- The same storage -- better not hold on to it.
2304 Example: <FREE <ISTORAGE 69 0>>
2305 Free up newly created STORAGE.
2307 FREEZE: Copy an object into non-moving storage
2311 Category: DATA-HANDLING, UTILITY
2313 FREEZE copies its argument into non-moving (garbage-collected)
2314 space. It CHTYPEs the copy to its PRIMTYPE; a TUPLE is changed to a
2315 VECTOR. FREEZEing is mostly valuable applied to the CODE of an RSUBR.
2319 Template: #DECL ("VALUE" <OR VECTOR UVECTOR STRING>
2320 <OR <PRIMTYPE VECTOR>
2325 Argument 1 -- a vector, tuple, uvector, or string to freeze
2326 Returns -- a frozen copy of arg1
2328 Example: <FREEZE <1 ,MY-RSUBR>>
2331 FUNCT: Return the function that generated a FRAME
2335 Category: ENVIRONMENT, UTILITY
2337 Reference: FRAME, ARGS
2339 FUNCT returns the ATOM which is the name of the applicable object
2340 which caused a given FRAME to be created. Takes a FRAME or other
2341 environment as an argument. If given a non-FRAME, it returns the
2342 topmost function name of that environment.
2343 Most commonly used as part of a more sophisticated program, such
2348 Template: #DECL ("VALUE" ATOM
2349 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
2351 Argument 1 -- an environment
2352 Returns -- The ATOM which is the name of the object which caused the
2353 FRAME to be created.
2355 Example: <FUNCT <FRAME>>
2357 If done at top level.
2359 FUNCTION: Create a FUNCTION
2363 Category: DATA-HANDLING
2367 FUNCTION creates a function. In cases where the function is to
2368 be made the GVAL of an ATOM, it is preferable to use DEFINE.
2369 A FUNCTION consists of an optional ACTIVATION name (an ATOM),
2370 a Parameter LIST, an optional DECL, and a body consisting of at least
2375 Template: #DECL ("VALUE" FUNCTION "ARGS" LIST)
2377 List of arguments -- if the first element of the list is an atom the
2378 activation is bound to it, the rest is the arg list, DECL, and
2379 body of the function.
2380 Returns -- A FUNCTION.
2382 Example: <FUNCTION (N) <+ 1 .N>>
2383 equivalent to #FUNCTION ((N) <+ 1 .N>)
2385 G=?: Is first argument greater than or equal to the second ?
2389 Category: PREDICATE, ARITHMETIC
2393 This routine tests if the first argument is numerically greater
2394 than or equal to the second argument, returning T if it is, #FALSE()
2399 Template: #DECL ("VALUE" <OR 'T FALSE>
2400 <OR FIX FLOAT> <OR FIX FLOAT>)
2402 Argument 1 -- A FIX or FLOAT.
2403 Argument 2 -- A FIX or FLOAT.
2404 Returns -- T if arg1 >= arg2, #FALSE() if not.
2406 Example: <G=? 2.4499998 -2>
2407 <G=? -7.2300000 -10.039999>
2409 These will return T.
2410 <G=? -0.42699999E-2 0.20409999>
2412 These will return #FALSE ().
2414 G?: Is first argument greater than the second ?
2418 Category: PREDICATE, ARITHMETIC
2422 This routine tests if the first argument is numerically greater
2423 than the second argument, returning T if it is, #FALSE() otherwise.
2427 Template: #DECL ("VALUE" <OR 'T FALSE>
2428 <OR FIX FLOAT> <OR FIX FLOAT>)
2430 Argument 1 -- A FIX or FLOAT.
2431 Argument 2 -- A FIX or FLOAT.
2432 Returns -- T if arg1 > arg2, #FALSE() if not.
2436 These will return T.
2437 <G? 0.35240000 0.34169999>
2440 These will return #FALSE ().
2442 GASSIGNED?: Is an Atom globally assigned ?
2446 Category: PREDICATE, IDENTIFIER
2448 Reference: ASSIGNED?, BOUND?
2450 This routine is used to test if a particular Atom is globally
2451 assigned, or in other words, if it has a global value. It does cause
2452 the activation of any read monitors on that global value.
2453 It returns T if the ATOM has a GLOBAL value, #FALSE() otherwise.
2457 Template: #DECL ("VALUE" <OR 'T FALSE> ATOM)
2459 Argument 1 -- An ATOM which may have a global value.
2460 Returns -- T if the ATOM has a global value, #FALSE() otherwise.
2462 Example: <SETG FOO "ANYTHING">
2464 This will simply return the Atom T, since FOO does have a global
2468 This will simply return #FALSE (), since the Atom FOO has no global
2471 GBOUND?: Does an atom have a global-value slot?
2475 Category: IDENTIFIER, PREDICATE
2477 Reference: SETG, MANIFEST, GDECL, GLOC
2479 GBOUND? tells whether or not an atom has a slot in the 'global
2480 vector', that is, whether it has ever been SETGed, MANIFEST, GDECLed,
2481 or GLOCed successfully.
2485 Template: #DECL ("VALUE" <OR 'T FALSE> ATOM)
2487 Argument 1 -- the atom to test
2488 Returns -- whether or not the atom is globally bound
2490 Example: <GBOUND? GBOUND?>
2494 GC-DUMP: Dump an object so it can be reproduced exactly
2502 GC-DUMP dumps an object via a channel so that GC-READ (q.v.)
2503 can reproduce it exactly, including sharing. Any non-stack, non-pure
2504 object can be dumped, except primtypes process, locd, and asoc.
2505 If a false is given instead of a channel, GC-DUMP returns what it
2506 would have output on the channel, as a uvector. This uvector can be
2507 stored as desired, but it must not be changed in any way to be
2512 Template: #DECL ("VALUE" <OR ANY <UVECTOR <PRIMTYPE WORD>>>
2513 ANY <OR CHANNEL FALSE>)
2515 Argument 1 -- the object to be dumped
2516 Argument 2 -- "PRINTB/O" channel or false
2517 Returns -- arg1 if arg2 is channel, else output data
2519 Example: <GC-DUMP <PROG ((L (1 2)))
2522 can dump circular objects
2524 GC-MON: Toggle state of GC monitor
2528 Category: ENVIRONMENT
2532 GC-MON is used to turn on and off the typing of GIN and GOUT
2533 and other info upon entering and leaving the garbage collector.
2534 If the argument is FALSE no typing will occur, otherwise typing
2535 will occur. The initial state of the GC-monitor is to not type.
2539 Template: #DECL ("VALUE" ANY "OPTIONAL" ANY)
2542 Argument 1 -- If non-FALSE, turn on GC-monitor, else turn it off.
2543 Returns -- The previous or current state of the monitor.
2546 Turn on GC-monitoring
2548 GC-READ: Input an object that was previously GC-DUMPed
2556 GC-READ returns one object from a given channel, open to a file
2557 produced by GC-DUMP (q.v.).
2561 Template: #DECL ("VALUE" ANY CHANNEL "OPTIONAL" ANY)
2563 Argument 1 -- a "READB" channel to read from
2565 Argument 2 -- object to eval and return at eof
2566 Returns -- an object from the file, or arg2
2570 (C <OPEN "READB" "DUMPED FILE">))
2574 <GC-READ .READB-CHNL <>>>>>>
2575 get all GC-DUMPed objects from a file
2577 GC: Cause a Garbage Collection to occur
2581 Category: ENVIRONMENT
2583 Reference: GC-MON, BLOAT
2585 GC always causes a garbage collection and returns the amount
2586 of storage reclaimed. Its first optional argument specifies the
2587 minimum amount of free space tolerable in future gc's. Its second
2588 argument tells whether this gc should be exhaustive. Its third argument
2589 changes the parameter telling how many mark-sweep gcs to do between
2590 "real" ones; this is initially 0, meaning never mark-sweep.
2594 Template: #DECL ("VALUE" FIX "OPTIONAL" FIX <OR FALSE ANY> FIX)
2597 Argument 1 -- FIX specifying amount of free space to get.
2598 Argument 2 -- whether gc should be exhaustive
2599 Argument 3 -- how many mark-sweep GCs to do between "real" ones.
2600 Returns -- A FIX giving the amount free space reclaimed.
2602 Example: <GC 30000 <>>
2603 GC and change a GC parameter
2605 GDECL: Make a declaration for a global value
2609 Category: DATA-HANDLING
2611 Reference: GET-DECL, PUT-DECL, MANIFEST
2613 GDECL is used to make a DECL for a global value or values, in
2614 much the same way as the #DECL () construct is used for local values.
2615 It takes the standard DECL syntax argument (ie, CHTYPEing REST of the
2616 GDECL form to DECL would make it look like a local DECL).
2617 ATOMs that have been GDECLed will give ERRORs on an attempt to
2618 SETG them to something that conflicts with their DECL, unless, of
2619 course, DECL-checking is disabled.
2623 Template: #DECL ("VALUE" ANY
2628 List of arguments -- Pairs consisting of a LIST of ATOMs and a
2632 Example: <GDECL (FOO)
2636 Just like local DECLs.
2638 GET-DECL: Get the DECL of an ATOM
2642 Category: DATA-HANDLING
2646 GET-DECL returns the current DECL of an ATOM's GVAL or LVAL.
2647 It takes a single argument, a locative to the value. It returns
2648 either the DECL, the ATOM MANIFEST (if the ATOM is manifest), or
2649 FALSE, if the ATOM has no DECL.
2650 The use of locatives allows the same SUBR to work for both local
2653 If given an OFFSET, returns the DECL part of the OFFSET.
2657 Template: #DECL ("VALUE" <OR ATOM FORM FALSE> <OR LOCD OFFSET>)
2659 Argument 1 -- A locative to the global or local value slot of an
2661 Returns -- The DECL of that value, or MANIFEST, or FALSE.
2663 Example: <SET FOO (1 2 3)>
2665 <GDECL (FOO BAR) LIST>
2666 <GET-DECL <GLOC FOO>>
2669 <GET-DECL <OFFSET 1 '<CHANNEL FIX>>>
2672 See also PUT-DECL, for changing declarations.
2674 GET: Get an element of a structure or the value of an association
2678 Category: DATA-HANDLING, ASSOCIATION
2680 Reference: PUT, GETPROP
2682 GET returns a given property associated with an item, or if
2683 second arg is a fix and the object is structured, returns that element
2684 of the structured object.
2685 Thus, GET is like GETPROP if the first argument is not a structure,
2686 and like NTH if it is.
2687 If GET is being used like GETPROP, an optional third argument is
2688 allowed, which is what to return if there is no association between
2689 the given item and indicator.
2693 Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY)
2695 Argument 1 -- The object with the association or structure.
2696 Argument 2 -- The indicator under which the association is stored or
2697 the FIX offset within a structure.
2699 Argument 3 -- The default to be evaled and returned if no assoc, else
2700 FALSE is the result.
2701 Returns -- The element of the structure, value of the association, or
2702 the optional third argument if given, or FALSE.
2704 Example: <PROG ((A (1 2 3 4)))
2712 Notice the difference between the PROP and non-prop subrs
2714 GETBITS: Get part of a word
2718 Category: BIT-TWIDDLING
2720 Reference: BITS, PUTBITS
2722 GETBITS takes a PRIMTYPE WORD (or a STORAGE, for which its
2723 address is used) and a BITS, and returns a word generated by picking
2724 up the bits described by the BITS. For example, a BITS of <BITS 7>
2725 describes the rightmost 7 bits of a word. Therefore, a GETBITS using
2726 it will return the rightmost 7 bits.
2727 It is functionally equivalent to the PDP-10 Load Byte (LDB)
2732 Template: #DECL ("VALUE" WORD <PRIMTYPE <OR WORD STORAGE>> BITS)
2734 Argument 1 -- An object of type WORD.
2735 Argument 2 -- A BITS, as returned by BITS.
2736 Returns -- A WORD containing the bits described by Argument 2.
2738 Example: <GETBITS -1 <BITS 3>>
2739 #WORD *000000000007*
2740 Non-WORDs need not be CHTYPEd.
2742 GETL: Get a locative to a structure or the value of an association
2746 Category: DATA-HANDLING, ASSOCIATION
2748 Reference: PUT, GETPROP, GETPL
2750 GETL returns a locative to a given association, or if second arg
2751 is a fix and the object is structured, returns a locative to that
2752 element of the structured object.
2753 Thus, GETL is like GETPL if the first argument is not a structure,
2754 and like AT if it is.
2755 If GETL is being used like GETPL, an optional third argument is
2756 allowed, which is what to return if there is no association between
2757 the given item and indicator.
2761 Template: #DECL ("VALUE" <OR LOCATIVE ANY> ANY ANY
2764 Argument 1 -- The item part of the association or a structure.
2765 Argument 2 -- The indicator under which the association is stored or
2766 the FIX offset within a structure.
2768 Argument 3 -- The default to be evaled and returned if no assoc, else
2769 FALSE is the result.
2770 Returns -- A locative to the association or element of a structure, or
2771 if acting like GETPL and there is no association, eval of the
2772 optional third argument if given, or FALSE.
2774 Example: <PROG ((A (1 2 3 4)))
2782 Notice the difference between the PROP and non-prop subrs
2784 GETPL: Get an a locative to the value of an association
2788 Category: ASSOCIATION
2790 Reference: PUT, GETPROP, GETL
2792 GETPL returns a locative to the value part of an association
2793 with given item (arg1) and indicator (arg2). It also takes a third
2794 argument (optional) which will be evaled if the association does not
2795 exist (default is FALSE).
2796 Note that GETL is identical to GETPL if its first argument is not
2797 structured and its second is not a FIX.
2801 Template: #DECL ("VALUE" <OR LOCAS ANY> ANY ANY "OPTIONAL" ANY)
2803 Argument 1 -- The object with the association.
2804 Argument 2 -- The indicator under which the association is stored.
2806 Argument 3 -- The default to be evaled and returned if no assoc, else
2807 FALSE is the result.
2808 Returns -- A locative (type LOCAS) to the association if it exists, or
2809 eval of the optional third argument if given, or FALSE.
2811 Example: <PROG ((A (1 2 3 4)))
2819 Notice the difference between the PROP and non-prop subrs
2821 GETPROP: Get the value of an association
2825 Category: DATA-HANDLING, ASSOCIATION
2827 Reference: PUT, PUTPROP, GETPL, GETL
2829 GETPROP returns a given property associated with an item. It
2830 takes two required arguments, the item and the indicator, and a third
2831 argument which is optional, and which will be evaled and returned if
2832 the item-indicator pair has no association on it (default a FALSE).
2833 GETPROP is thus one end of a triad of SUBRs, GETPROP, GET and NTH,
2834 which together make up a full association/subelement mechanism. This
2835 is paralleled by PUT and PUTPROP, and GETPL, GETL and AT.
2839 Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY)
2841 Argument 1 -- The item part of an item-indicator pair.
2842 Argument 2 -- The indicator under which the association is stored.
2844 Argument 3 -- The default to be evaled and returned if no assoc, else
2845 FALSE is the result.
2846 Returns -- The element of the structure, value of the association, or
2847 the optional third argument if given, or FALSE.
2849 Example: <PROG ((A (1 2 3 4)))
2857 Notice the difference between the PROP and non-prop subrs
2859 GLOC: Get a locative to the GVAL of an ATOM
2863 Category: DATA-HANDLING
2867 Returns a locative, type LOCD, to the GVAL of the ATOM passed
2868 as its argument. If the ATOM has no GVAL slot, ERROR, unless second
2869 arg is given and true.
2873 Template: #DECL ("VALUE" LOCD ATOM "OPTIONAL" <OR FALSE ANY>)
2875 Argument 1 -- An ATOM with a GVAL.
2877 Argument 2 -- whether not to give a no-slot error or not
2878 Returns -- A locative (LOCD) to the GVAL of the ATOM.
2880 Example: <AND <GASSIGNED? FOO> <GLOC FOO>>
2881 Guard against ATOMs with no GVALs.
2883 GO: Go elsewhere in a PROG/REPEAT
2887 Category: PROGRAM-CONTROL
2889 Reference: TAG, PROG, REPEAT
2891 GO transfers control to a given top-level object within a PROG
2892 or REPEAT. The place to go is specified by an atom label or a tag.
2893 GO is very seldom tasteful: use nested REPEAT or MAPF/R instead.
2897 Template: #DECL ("VALUE" ANY <OR ATOM TAG>)
2899 Argument 1 -- where to go to
2900 Returns -- RESUME arg, if tag lay in another process
2909 exactly what GO should do
2911 GROW: Enlarge a VECTOR or UVECTOR
2915 Category: DATA-HANDLING
2919 GROW extends the bounds of a vector or uvector. Be aware that
2920 growing causes a garbage collection and is therefore an expensive
2921 operation. That is the reason it is only done in increments of 32 or
2926 Template: #DECL ("VALUE" <PRIMTYPE <OR VECTOR UVECTOR>>
2927 <PRIMTYPE <OR VECTOR UVECTOR>> FIX FIX)
2929 Argument 1 -- The object to grow.
2930 Argument 2 -- Number to be added to the end rounded up to a multiple
2931 of 32 for VECTORs, 64 for UVECTORs.
2932 Argument 3 -- Number to be added to beginning rounded up to a multiple
2933 of 32 for VECTORs, 64 for UVECTORs.
2934 Returns -- The newly enlarged VECTOR or UVECTOR.
2936 Example: <GROW ![1 2 3!] 1 1>
2937 will grow by 32 on each end.
2939 GUNASSIGN: Removes the Global value of an ATOM
2943 Category: IDENTIFIER
2945 Reference: GVAL, GASSIGNED?
2947 GUNASSIGN removes the global value of an ATOM. After an ATOM
2948 has been GUNASSIGNED, GVAL of it will cause and error, and GASSIGNED?
2949 of it will return FALSE.
2953 Template: #DECL ("VALUE" ATOM ATOM)
2955 Argument 1 -- The ATOM to flush the GVAL of.
2956 Returns -- The ATOM you just GUNASSIGNed.
2958 Example: <GUNASSIGN GUNASSIGN>
2960 Something you only do once.
2962 GVAL: Return the Global value of an ATOM
2966 Category: IDENTIFIER
2968 Reference: GASSIGNED?, GUNASSIGN
2970 Returns the Global value of an ATOM, if any. If the ATOM has
2971 no Global value, ERROR.
2972 The expressions ,<an atom> and <GVAL <an atom>> are identical.
2976 Template: #DECL ("VALUE" ANY ATOM)
2978 Argument 1 -- An ATOM.
2979 Returns -- Its GVAL, if it has one.
2981 Example: <==? ,FOO .FOO>
2983 GVAL and LVAL are independent, but watch out using both -- the last
2984 referenced is kept in the ATOM's value slot, so switching back and
2985 forth can be expensive!
2987 HANDLER: Attach an interrupt handler to an IHEADER
2993 Reference: EVENT, ENABLE, DISABLE
2995 HANDLER attaches an interrupt handler to an IHEADER. It may
2996 build and attach a new handler or reattach a previously OFFed handler.
2997 The first argument is always the IHEADER. The second argument
2998 is either the previously OFFd handler or an applicable object.
2999 The last argument is optional and may be a
3000 process in which the handler is to run. If no process is supplied,
3001 the interrupt will run in whatever process is currently running.
3002 Note: new handlers are always added to the beginning of the list of
3007 Template: #DECL ("VALUE" HANDLER IHEADER <OR HANDLER
3011 Argument 1 -- An IHEADER, such as is returned by EVENT.
3012 Argument 2 -- An APPLICABLE object to handle the interrupt, or a
3013 previously OFFed HANDLER.
3015 Argument 3 -- A PROCESS in which to run the interrupt.
3016 Returns -- A HANDLER, which has been added to the beginning of the
3017 list of HANDLERs for that interrupt.
3019 Example: <HANDLER <SET TEM <EVENT "CHAR" 10 .INCHAN>>
3021 Setup a character interrupt with one handler.
3023 HANG: Hang interruptably forever
3027 Category: ENVIRONMENT, INTERRUPT
3031 HANG causes the MUDDLE to hang interruptably forever. It is
3032 useful if there is an activation available to return to beyond the
3033 HANG. Alternatively, it takes an optional argument which is EVALed
3034 each time an interrupt DISMISSes back to the HANG. If the argument
3035 EVALs to non-FALSE, the HANG terminates, returning the result of the
3040 Template: #DECL ("VALUE" ANY "OPTIONAL" ANY)
3043 Argument 1 -- Something to EVAL each time the HANG is dismissed to.
3044 Returns -- The result of EVALing the argument, or if it is not given,
3045 never returns (May be non-locally returned beyond, of course).
3047 Example: <HANG .FOO>
3048 Hang until someone (at interrupt level) sets FOO to a non-FALSE.
3050 IBYTES: Generate a BYTES by repeated Evaluation
3054 Category: DATA-HANDLING
3058 IBYTES returns a byte-string of given byte-size and length whose
3059 elements are generated by repeated evaluation of the third argument.
3060 Note that the third argument must return a FIX each time it is EVALed.
3064 Template: #DECL ("VALUE" BYTES FIX FIX "OPTIONAL" ANY)
3066 Argument 1 -- FIX, size of bytes
3067 Argument 2 -- FIX, number of elements.
3069 Argument 3 -- ANY, expression which when evaled, gives each element,
3071 Returns -- Newly baked BYTES.
3073 Example: <IBYTES 3 9 '<COND (<ASSIGNED? X> <SET X <+ 1 .X>>) (<SET X 0>)>>
3074 #3 {0 1 2 3 4 5 6 7 0}
3076 IFORM: Generate a FORM by repeated Evaluation
3080 Category: DATA-HANDLING
3084 IFORM returns a form of given length whose elements are generated
3085 by repeated evaluation of the second argument.
3089 Template: #DECL ("VALUE" FORM FIX "OPTIONAL" ANY)
3091 Argument 1 -- FIX, number of elements to generate.
3093 Argument 2 -- ANY, expression which when evaled, gives each element
3094 default is #LOSE *0*'s.
3095 Returns -- The newly hatched FORM.
3097 Example: <SET ROOTL <LENGTH <ROOT>>>
3098 <IFORM 5 '<1 <NTH <ROOT> <MOD <RANDOM> .ROOTL>>>>
3100 Makes a FORM by picking the first elements of 5 randomly selected
3101 buckets in the ROOT OBLIST.
3103 ILIST: Generate a LIST by repeated Evaluation
3107 Category: DATA-HANDLING
3111 ILIST returns a list of given length whose elements are generated
3112 by repeated evaluation of the second argument.
3116 Template: #DECL ("VALUE" LIST FIX "OPTIONAL" ANY)
3118 Argument 1 -- FIX, number of elements
3120 Argument 2 -- ANY, expression which when evaled, gives each element
3121 default is #LOSE *0*'s
3122 Returns -- The newly created LIST.
3124 Example: <ILIST 5 0>
3125 Create a LIST containing five 0s.
3127 IMAGE: Output a naked character
3135 IMAGE outputs precisely the character whose ASCII value is
3136 given as an arg. It does not add up-arrow, line-feed, etc.
3140 Template: #DECL ("VALUE" FIX FIX "OPTIONAL" CHANNEL)
3142 Argument 1 -- ASCII code for character to send naked
3144 Argument 2 -- the channel to send it on, default .OUTCHAN
3151 draws an I-beam on an Imlac
3153 IN: Get the object a locative points to
3157 Category: DATA-HANDLING
3159 Reference: AT, LLOC, GLOC, LEGAL?
3161 Returns the object a locative points to. The only way you can
3162 get an error using IN is to pass it a locative to an LVAL that has
3163 become unbound. Using LEGAL? will save you much grief.
3167 Template: #DECL ("VALUE" ANY LOCATIVE)
3169 Argument 1 -- A locative.
3170 Returns -- The object the locative points to.
3172 Example: <SET FOO 69>
3175 Like LVAL except independent of rebindings of FOO.
3177 INDEX: Return the index part of an OFFSET
3181 Category: STRUCTURES
3183 Reference: OFFSET, NTH, GET-DECL, PUT-DECL
3185 Given an OFFSET, returns the index part.
3189 Template: #DECL ("VALUE" FIX OFFSET)
3191 Argument 1 -- An OFFSET
3192 Returns -- The index field of the OFFSET.
3194 Example: <SET CHNUM <OFFSET 1 '<CHANNEL FIX>>>
3195 %<OFFSET 1 '<CHANNEL FIX>>
3198 Use GET-DECL to get the DECL part of the OFFSET.
3200 INDICATOR: Return the indicator part of an Association triad
3204 Category: ASSOCIATION
3206 Reference: ASSOCIATIONS, NEXT, ITEM, AVALUE,
3209 Given an ASOC, as returned by ASSOCIATIONS or NEXT, returns the
3210 indicator part of the ASOC triad.
3211 See also ITEM and AVALUE, which return the Item and Value parts
3216 Template: #DECL ("VALUE" ANY ASOC)
3218 Argument 1 -- An ASOC whose indicator field to get.
3219 Returns -- The indicator field of the ASOC.
3221 Example: <PUTPROP FOO BAR BLECH>
3222 <ITEM <ASSOCIATIONS>>
3224 <INDICATOR <ASSOCIATIONS>>
3226 <AVALUE <ASSOCIATIONS>>
3228 ASSOCIATIONS gets newest ASOC.
3230 INSERT: Create an ATOM and put it on an OBLIST
3234 Category: IDENTIFIER
3236 Reference: ATOM, LOOKUP
3238 INSERT takes as argument a STRING, which will be the PNAME of
3239 a new ATOM on the OBLIST given as the second argument. The ATOM is
3241 In the special case where the ATOM is not already on an OBLIST,
3242 INSERT will also take an ATOM as argument. In conjunction with REMOVE
3243 this feature may be used to move an ATOM from one OBLIST to another.
3244 Note that if the ATOM with the PNAME given already exists on that
3245 OBLIST, ERROR. See the example for the standard foolproof way to
3250 Template: #DECL ("VALUE" ATOM <OR ATOM STRING> OBLIST)
3252 Argument 1 -- A STRING, which is the PNAME of a new ATOM to be
3253 created, or an ATOM on no OBLIST.
3254 Argument 2 -- An OBLIST into which to insert the new ATOM.
3255 Returns -- The newly minted ATOM.
3257 Example: <INSERT "GVAL" <ROOT>>
3258 This will fail, as the ATOM is already there.
3259 <OR <LOOKUP "GVAL" <ROOT>> <INSERT "GVAL" <ROOT>>>
3262 INT-LEVEL: Read and set the current interrupt level
3268 INT-LEVEL is used to read and set the current interrupt level.
3269 If it is called with no arguments, it simply returns the current level
3270 otherwise it causes its fixed point argument to be the current
3271 interrupt level and returns the previous one.
3272 Note that 0 is the 'normal' int-level, and during handling of an
3273 interrupt, the int-level is set to the priority assigned to the int-
3274 errupt that is being handled.
3278 Template: #DECL ("VALUE" FIX "OPTIONAL" FIX)
3281 Argument 1 -- A FIX, which will be the new interrupt level. If not
3282 given, simply returns the current level.
3283 Returns -- A FIX, the interrupt level at the time of the call (ie:
3284 if changed, the old one).
3286 Example: <INT-LEVEL <MIN>>
3287 Cause all interrupts to be deferred.
3289 INTERRUPT: Generate an artificial interrupt
3295 INTERRUPT causes a software interrupt to happen. If the
3296 interrupt has an IHEADER associated with it, either run the handlers
3297 or queue them depending on the INT-LEVEL. If the IHEADER exists
3298 return T, otherwise return #FALSE (). The first argument to INTERRUPT
3299 is either an IHEADER, atom or string specifying the interrupt to do.
3300 The rest of the arguments are applied to the functions associated
3301 with the various handlers.
3302 INTERRUPT is used either to cause a 'software' interrupt (one
3303 identified by a name not normally in the INTERRUPTS OBLIST) or to test
3304 a 'real' interrupt handler.
3308 Template: #DECL ("VALUE" <OR 'T FALSE> <OR IHEADER STRING ATOM> "TUPLE"
3311 Argument 1 -- An identifier of the interrupt to be generated, either
3312 a STRING, ATOM, or IHEADER.
3313 Tuple of arguments -- The appropriate arguments for the handler for
3315 Returns -- T if an IHEADER exists for this interrupt, FALSE otherwise.
3317 Example: <INTERRUPT "FOO" 1 2 3>
3318 Causes a FOO interrupt if an IHEADER exists.
3320 INTERRUPTS: Return the INTERRUPTS OBLIST
3326 INTERRUPTS returns the INTERRUPTS oblist. This oblist contains
3327 atoms that are dangerous to play with. These include atoms associated
3328 with interrupts and the special atoms LPROG , LERR and LMAP .
3332 Template: #DECL ("VALUE" OBLIST)
3334 Example: <INTERRUPTS>
3335 Only possible invocation.
3337 IPC-HANDLER: Default IPC message handler
3341 Category: INTERNAL, INTERRUPT, SYSTEM
3343 Reference: IPC-ON, IPC-OFF, SEND, SEND-WAIT
3345 IPC-HANDLER is the default IPC message handler. It prints out
3346 the message, who it is from, the type if non-zero, and who it is to,
3347 if not uname, jname. If the type is 1, and the message is a STRING,
3348 it is parsed and evaluated as well as being printed out. See the
3349 FUNCTION INQUIRE for an application of this feature.
3350 IPC conditions are signalled with arguments as specified in the
3351 'Template' field below.
3355 Template: #DECL ("VALUE" ANY <OR STRING UVECTOR STORAGE> FIX STRING STRING
3356 "OPTIONAL" STRING STRING)
3358 (Arguments to any IPC condition handler)
3359 Argument 1 -- The message received. This may be a STRING, a UVECTOR,
3360 of UTYPE primtype FIX, or a STORAGE.
3361 Argument 2 -- The type of the message, a FIX. The interpretation of
3362 this is entirely up to the handler.
3363 Arguments 3 & 4 -- STRINGs specifying whom the message is from.
3365 Arguments 5 & 6 -- STRINGs specifying whom the message is to, if other
3369 Example: <IPC-HANDLER "HELLO, HOW ARE YOU." 0 "CLR" "MUDDLE">
3371 Just prints this out. Actually you would never see or invoke this
3372 form, since only happens at interrupt level.
3374 IPC-OFF: Stop listening for IPC messages
3380 Reference: IPC-ON, IPC-HANDLER, SEND, SEND-WAIT
3382 IPC-OFF causes the MUDDLE to stop listening for messages on the
3383 IPC. The opposite is IPC-ON, which causes the MUDDLE to listen.
3387 Template: #DECL ("VALUE" ANY)
3392 In virgin MUDDLE, disable default IPC handler, IPC-HANDLER.
3394 IPC-ON: Listen for IPC messages sent to a given pair
3400 Reference: IPC-OFF, SEND, SEND-WAIT, IPC-HANDLER
3402 IPC-ON takes two STRINGs as arguments, and listens for IPC
3403 messages addressed to that pair. If they are received, an IPC
3404 condition is signalled. There is a default handler for this condition
3405 called IPC-HANDLER. See its abstract for more details.
3409 Template: #DECL ("VALUE" ANY "OPTIONAL" STRING STRING)
3412 Arguments 1 & 2 -- A pair of names to listen on, default UNAME JNAME
3417 Usually jobs listen on their uname-jname to avoid confusion.
3419 ISTORAGE: Generate a STORAGE by repeated Evaluation
3423 Category: DATA-HANDLING
3427 ISTORAGE Return a non-g.c. storage area of given length with
3428 elements generated by repeated evaluation of the second argument.
3429 Storage is normally used for the E&S, since it does not move
3430 during garbage collection.
3431 Note that the repeatedly EVALed argument must return something
3432 suitable to be in a STORAGE (ie, no STRINGs) and also the results must
3437 Template: #DECL ("VALUE" STORAGE FIX "OPTIONAL" ANY)
3439 Argument 1 -- FIX, number of elements.
3441 Argument 2 -- ANY, expression which when evaled, gives each element
3442 default is #LOSE *0*'s.
3443 Returns -- Newly minted STORAGE.
3445 Example: <ISTORAGE 10 '<RANDOM>>
3446 Create a STORAGE with random contents.
3448 ISTRING: Generate a STRING by repeated Evaluation
3452 Category: DATA-HANDLING
3456 ISTRING returns a string of given length whose elements are
3457 generated by repeated evaluation of the second argument. Note that
3458 the second argument must return a CHARACTER each time it is EVALed.
3462 Template: #DECL ("VALUE" STRING FIX "OPTIONAL" ANY)
3464 Argument 1 -- FIX, number of elements.
3466 Argument 2 -- ANY, expression which when evaled, gives each element,
3468 Returns -- Newly baked STRING.
3470 Example: <ISTRING 20 '<CHTYPE <MOD <RANDOM> 128> CHARACTER>>
3471 Note the CHTYPEing to type CHARACTER.
3473 ITEM: Return the item part of an Association triad
3477 Category: ASSOCIATION
3479 Reference: ASSOCIATIONS, NEXT, AVALUE, INDICATOR,
3482 Given an ASOC, as returned by ASSOCIATIONS or NEXT, returns the
3483 item part of the ASOC triad. See also INDICATOR and AVALUE, which get
3484 the Indicator and Value parts of the triad.
3488 Template: #DECL ("VALUE" ANY ASOC)
3490 Argument 1 -- An ASOC whose item field to get.
3491 Returns -- The item field of the ASOC.
3493 Example: <PUTPROP FOO BAR BLECH>
3494 <ITEM <ASSOCIATIONS>>
3496 <INDICATOR <ASSOCIATIONS>>
3498 <AVALUE <ASSOCIATIONS>>
3500 ASSOCIATONS gets newest ASOC.
3502 ITUPLE: Generate a TUPLE by repeated Evaluation
3506 Category: DATA-HANDLING
3510 ITUPLE returns a TUPLE (vector on the stack) of given length whose
3511 elements are generated by repeated evaluation of the second argument.
3512 ITUPLE is exactly like IVECTOR, except for the restriction that it may
3513 only be applied at top-level inside the parameter list of a FUNCTION,
3514 in AUX or OPTIONAL atom-value pairs, or at top level inside the atom-
3515 value pairs of PROGs or REPEATs.
3516 Note also that ITUPLE does not compile very well.
3520 Template: #DECL ("VALUE" TUPLE FIX "OPTIONAL" ANY)
3522 Argument 1 -- FIX, number of elements.
3524 Argument 2 -- ANY, expression which when evaled, gives each element
3525 default is #LOSE *0*'s
3526 Returns -- Newly stacked TUPLE.
3528 Example: <PROG ((A <ITUPLE 4 0>))
3531 This is a valid usage of ITUPLE.
3535 <REST <ITUPLE !.A>>))
3538 This is not a valid usage of ITUPLE, since the application is not at
3539 top level of the atom-value pair.
3541 IUVECTOR: Generate a UVECTOR by repeated Evaluation
3545 Category: DATA-HANDLING
3549 IUVECTOR returns a uniform vector of given length whose elements
3550 are generated by repeated evaluation of the second argument.
3551 Note that the second argument must return objects all the same
3552 type and appropriate to be part of a UVECTOR (ie: no STRINGs).
3556 Template: #DECL ("VALUE" UVECTOR FIX "OPTIONAL" ANY)
3558 Argument 1 -- FIX, number of elements.
3560 Argument 2 -- ANY, expression which when evaled, gives each element
3561 (must all be of same type) default is #LOSE *0*'s.
3562 Returns -- Newly created UVECTOR.
3564 Example: <PROG ((A 2))
3570 IVECTOR: Generate a VECTOR by repeated Evaluation
3574 Category: DATA-HANDLING
3578 IVECTOR returns a vector of given length whose elements are
3579 generated by repeated evaluation of the second argument.
3583 Template: #DECL ("VALUE" VECTOR FIX "OPTIONAL" ANY)
3585 Argument 1 -- FIX, number of elements.
3587 Argument 2 -- ANY, expression which when evaled, gives each element
3588 default is #LOSE *0*'s.
3589 Returns -- Newly created VECTOR.
3591 Example: <IVECTOR 5 "ha">
3592 ["ha" "ha" "ha" "ha" "ha"]
3595 JNAME: Return the Job name of the MUDDLE
3603 Returns the JNAME, or Job-name of the MUDDLE. This is a STRING
3604 giving the JNAME, which is the second name of the job in which the
3605 MUDDLE is running. The UNAME (qv) is the first.
3609 Template: #DECL ("VALUE" STRING)
3611 Returns -- A STRING which is the JNAME of the job.
3614 Only possible example.
3616 L=?: Is first argument less than or equal to the second ?
3620 Category: PREDICATE, ARITHMETIC
3622 Reference: ==?, L?, G?, G=?
3624 This routine tests if the first argument is numerically less
3625 than or equal to the second argument, returning T if it is, #FALSE()
3630 Template: #DECL ("VALUE" <OR 'T FALSE>
3631 <OR FIX FLOAT> <OR FIX FLOAT>)
3633 Argument 1 -- A FIX or FLOAT.
3634 Argument 2 -- A FIX or FLOAT.
3635 Returns -- If arg1 <= arg2, T, else #FALSE().
3638 <L=? -5.7308998 0.95000000E-2>
3640 These will return T.
3643 <L=? -3.9530000 -4.0241000>
3644 These will return #FALSE ().
3646 L?: Is first argument less than the second?
3650 Category: PREDICATE, ARITHMETIC
3652 Reference: G?, ==?, L=?
3654 This routine tests if the first argument is numerically less
3655 than the second argument.
3659 Template: #DECL ("VALUE" <OR 'T FALSE>
3660 <OR FIX FLOAT> <OR FIX FLOAT>)
3662 Argument 1 -- A FIX or FLOAT.
3663 Argument 2 -- A FIX or FLOAT.
3664 Returns -- T if arg1 < arg2, #FALSE() otherwise.
3668 <L? -13.462000 -0.93000000E-1>
3669 These will return T.
3670 <L? -12.340000 -12.340010>
3671 <L? 3.1415899 3.1415899>
3672 These will return #FALSE ().
3674 LEGAL?: Is the argument (TUPLE, FRAME, etc.) legal ?
3680 This routine is used to verify the legality of MUDDLE objects.
3681 Although it works for all MUDDLE Types, it is only really useful for
3682 the Types: TUPLE, FRAME, ACTIVATION, ENVIRONMENT, TAG, and LOCD.
3683 For these Types it will return the Atom T if the portion of the
3684 stack in which the given item is found is still active. Otherwise, it
3685 will return #FALSE ().
3686 For any other Type it simply returns the atom T.
3690 Template: #DECL ("VALUE" <OR 'T FALSE> ANY)
3692 Argument 1 -- Any object, but most interestingly, TUPLE, FRAME, TAG
3693 ACTIVATION, ENVIRONMENT and LOCD, which are only legal if the
3694 part of the stack they are 'in' is still active.
3695 Returns -- T if the object is legal (for other than the types listed
3696 above this is always the result), #FALSE() otherwise.
3698 Example: <LEGAL? <PROG ("NAME" FOO) .FOO>>
3699 This will be False, since the activation is not legal outside the PROG.
3700 <PROG ("NAME" FOO) <LEGAL? .FOO>>
3701 However, this will be True, since the activation is legal inside the
3704 LENGTH: Number of elements in a structure
3708 Category: DATA-HANDLING
3712 LENGTH returns the number of elements in a structure.
3713 Be careful, LENGTH of a circular list never returns. For such
3714 cases consider LENGTH?, which allows you to specify a maximum length
3719 Template: #DECL ("VALUE" FIX STRUCTURED)
3721 Argument 1 -- Any structured object.
3722 Returns -- FIX, giving number of elements.
3724 Example: <LENGTH <SET X (1 2 3 4 5)>>
3727 <LENGTH <PUTREST <REST .X 4> .X>>
3728 Never returns, X is circular now.
3730 LENGTH?: Is a structure less than or equal to a given length?
3734 Category: DATA-HANDLING
3738 LENGTH? has a very misleading name. It takes a structured
3739 object and a FIX, and if the length of the s.o. is less than or equal
3740 to the FIX, it returns the length. Otherwise it returns FALSE.
3741 It is very common to see people attempt to program with this
3742 SUBR as though it were equivalent to either <==? <LENGTH s.o.> fix>
3743 or alternatively <G=? <LENGTH s.o.> fix>. Neither of these are what
3744 it does. It is actually closer to <L=? <LENGTH s.o.> fix>.
3745 LENGTH? derives its specialness from the fact that it works
3746 incrementally on LISTs, counting elements until the end is reached or
3747 the count runs out. Thus, LENGTH? will not die horribly on circular
3748 LISTs, which LENGTH will.
3752 Template: #DECL ("VALUE" <OR FIX FALSE> STRUCTURED FIX)
3754 Argument 1 -- A Structured Object.
3755 Argument 2 -- A FIX.
3756 Returns -- length of s.o. if less than or equal to FIX, and
3760 <PUTREST <REST <SET FOO (1 2 3)> 2>
3762 Returns circular list.
3769 LINK: Give an object a synonym
3773 Category: I/O, IDENTIFIER
3775 LINK gives a MUDDLE expression a synonym. It causes an object
3776 that looks vaguely like an ATOM to be placed in an OBLIST. This type,
3777 LINK, has the property that when it is read, its value is immediately
3778 substituted for what was read. This is particularly useful in inter-
3779 active work with MUDDLE, to avoid having to type long and dull streams
3780 of characters. See 'Example' for the canonication application.
3784 Template: #DECL ("VALUE" ANY ANY STRING "OPTIONAL" OBLIST)
3786 Argument 1 -- The expression which is the value of the LINK, and which
3787 is substituted whenever the LINK is read.
3788 Argument 2 -- A STRING giving the 'PNAME' of the LINK (remember, they
3789 are somewhat like ATOMs).
3791 Argument 3 -- An OBLIST for the LINK to live on, default <1 .OBLIST>.
3792 Returns -- Argument 1.
3794 Example: <LINK '<ERRET> "
\ 5">
3795 Links the ATOM of PNAME ^E to <ERRET>.
3801 Category: DATA-HANDLING
3803 LIST creates a list having explicit elements. Note that this is
3804 a SUBR, so the elements will be evaluated.
3808 Template: #DECL ("VALUE" LIST "TUPLE" <TUPLE [REST ANY]>)
3810 Tuple of arguments -- ANY, the elements
3812 Example: <SET X <LIST 1 2 3 4 5>>
3813 equivalent to (1 2 3 4 5)
3819 Slight difference does exist between explicit application of LIST and
3822 LISTEN: Go to a subsidiary READ-EVAL-PRINT loop
3826 Category: I/O, PROGRAM-CONTROL
3828 Reference: READ, EVAL, PRINT, TTYECHO, ECHOPAIR
3830 LISTEN is seldom called from a program (rather ERROR is), but it
3831 (1) ensures that .INCHAN, .OUTCHAN, and .OBLIST are reasonable
3832 (2) does <TTYECHO .INCHAN T> and <ECHOPAIR .INCHAN .OUTCHAN>
3833 (3) PRINTs its arguments on .OUTCHAN
3834 (4) PRINTs LISTENING-AT-LEVEL l PROCESS p INT-LEVEL i [as appropriate]
3835 (5) Either does <APPLY <VALUE REP>> or drops into a READ-EVAL-PRINT
3840 Template: #DECL ("VALUE" ANY "TUPLE" TUPLE)
3842 Tuple of arguments -- objects to print before listening
3843 Returns -- the argument to ERRET that makes the LISTEN return
3845 Example: <LISTEN "LISTEN UP, YOU YOYOS!">
3846 not an overly stupid example
3848 LLOC: Get a Locative to the LVAL of an ATOM
3852 Category: DATA-HANDLING
3856 LLOC of an ATOM returns a locative (type LOCD) to the LVAL of
3857 the ATOM in the current environment, or, optionally, if a second arg
3858 is given, the LVAL in that environment. The locative
3859 returned is independent of future rebindings of the ATOM. IN will
3860 always return the same value as long as that binding still exists.
3861 Once it ceases to exist, IN of that locative is no longer LEGAL?.
3865 Template: #DECL ("VALUE" LOCD ATOM "OPTIONAL"
3866 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
3868 Argument 1 -- An ATOM
3870 Argument 2 -- An Environment. If not given, the current one.
3871 Returns -- A locative (type LOCD) to the binding specified.
3873 Example: <PROG ((X 3) (XL <LLOC X>))
3874 <PROG ((X 69105)) <PRINT <IN .XL>>>>
3875 Will always print 3.
3877 LOAD: READ and EVAL every object from a channel
3883 Reference: FLOAD, READ, EVAL
3885 LOAD READs and EVALs every object in the file pointed to by
3886 its channel argument, and closes the channel. Control characters in
3887 the file have no special meaning. An oblist can be given for looking
3892 Template: #DECL ("VALUE" '"DONE" CHANNEL "OPTIONAL"
3893 <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>)
3895 Argument 1 -- the channel to load from
3897 Argument 2 -- (list of) oblist(s) for looking up atoms
3900 Example: <LOAD <OPEN "READ" "MANY ATOMS"> <ROOT>>
3901 make yourself root-bound
3903 LOCATIVE?: Is an object a locative?
3907 Category: TYPE, PREDICATE
3909 Reference: TYPE, STRUCTURED?, APPLICABLE?
3911 LOCATIVE? returns T if its argument is a locative, and FALSE if
3912 it is not. Since most of the locative related SUBRs (such as IN) take
3913 any sort of locative, and since there are several different types of
3914 locatives, it is a useful SUBR.
3918 Template: #DECL ("VALUE" <OR FALSE 'T> ANY)
3920 Argument 1 -- Any MUDDLE object.
3921 Returns -- T argument 1 is a locative, or FALSE if it is not.
3923 Example: <LOCATIVE? <GLOC ROOT>>
3925 <LOCATIVE? <AT [1 2 3] 1>>
3927 <LOCATIVE? <LLOC REDEFINE>>
3931 LOG: Logarithms to the base 'e'
3935 Category: ARITHMETIC
3939 LOG takes a FIX or FLOAT and returns the Logarithm to the base
3940 e of that FIX or FLOAT, as a FLOAT. EXP is the opposite of LOG.
3944 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
3946 Argument 1 -- A FIX or FLOAT to take the LOG of.
3947 Returns -- The log base e of argument 1.
3949 Example: <EXP <LOG 2>>
3951 Note conversion to floating point number.
3953 LOGOUT: Log out a top-level MUDDLE
3959 Reference: VALRET, QUIT
3961 This subr causes the MUDDLE it is in to attempt to log out.
3962 This will only work if the MUDDLE is top-level. Otherwise it will
3967 Template: #DECL ("VALUE" FALSE)
3969 Returns -- A FALSE, if it returns.
3972 Never returns if it wins.
3974 LOOKUP: Look up an ATOM in an OBLIST
3978 Category: IDENTIFIER
3980 Reference: ATOM, INSERT, OBLIST?
3982 LOOKUP takes the PNAME of an ATOM and an OBLIST as arguments,
3983 and looks to see if an ATOM with that PNAME exists on the OBLIST
3984 given. If one does, it is returned. If not, FALSE.
3985 LOOKUP is often used in conjunction with INSERT.
3989 Template: #DECL ("VALUE" <OR ATOM FALSE> STRING OBLIST)
3991 Argument 1 -- A STRING which represents the PNAME of an ATOM.
3992 Argument 2 -- An OBLIST to look up the PNAME in.
3993 Returns -- The ATOM found or FALSE if there wasn't one.
3995 Example: <OR <LOOKUP "FOO" .OB>
3998 Recommended way of safely inserting ATOMs. Guaranteed to return the
3999 ATOM of pname "FOO".
4001 LPARSE: PARSE several objects into a LIST.
4005 Category: DATA-HANDLING
4009 PARSE takes from 0 to 5 arguments. If parse is given no arguments,
4010 it returns the first item parsed from the local value of the string
4011 PARSE-STRING, and additionally, sets PARSE-STRING to the string having
4012 those characters which were parsed rested off. If parse is given a
4013 string to parse, the atom, PARSE-STRING, is rebound to the string within
4014 that call. If the parse table argument is given to PARSE, the value of
4015 PARSE-TABLE is rebound to it within that call to PARSE. Finally, PARSE
4016 takes a look ahead character, which is treated as if it were logically
4017 concatenated to the front of the string being parsed. The full callling
4018 sequence of PARSE is:
4020 <PARSE string radixfornumberconversion oblistorlistofoblists
4021 parsetable lookaheadchar>
4023 LPARSE is called exactly the same way as PARSE is called.
4024 It tries to parse the whole string, returning a list of the items
4025 parsed. The same action is taken with respect to optional
4026 arguments and rebindings as is taken by PARSE. All arguments are
4027 optional. The full calling sequence of LPARSE is:
4029 <LPARSE string radixfornumberconversion oblistorlistofoblists
4030 parsetable lookaheadchar>
4035 Template: #DECL ("VALUE" LIST "OPTIONAL" STRING
4037 <LIST [REST <OR OBLIST 'DEFAULT>]>>
4040 (Optional arguments)
4041 Argument 1 -- A STRING to be PARSEd.
4042 Argument 2 -- FIX radix for number conversion.
4043 Argument 3 -- An OBLIST or LIST of OBLISTs.
4044 Argument 4 -- A Parse-table (VECTOR).
4045 Argument 5 -- A CHARACTER for lookahead.
4046 Returns -- A LIST of objects.
4048 Example: <LPARSE "() 1 A">
4050 Will return a list of three elements.
4056 Category: BIT-TWIDDLING, LOGICAL
4060 LSH takes an object of Primtype WORD and a FIX, and it returns a
4061 WORD containing the bits in the first argument, shifted left (positive
4062 argument) or right (negative argument) the number of bits specified by
4063 the second argument (mod 256). Zero bits are brought in at the end
4064 being vacated; bits shifted out at the other end are lost.
4068 Template: #DECL ("VALUE" WORD
4069 <PRIMTYPE WORD> FIX)
4071 Arg 1 -- a Primtype WORD containing the bits to shift
4072 Arg 2 -- a FIX specifying the amount to shift
4073 Returns -- A WORD containing the shifted bits.
4076 #WORD *000000001000*
4078 #WORD *000000000000*
4079 Primarily useful for getting fingers directly in the bits.
4081 LVAL: Get the local value of an atom
4085 Category: IDENTIFIER
4087 Reference: ASSIGNED?, LLOC
4089 LVAL gets the local value of its atom argument, relative to its
4090 environment argument. With only one arg, it can be written .<-atom-> .
4094 Template: #DECL ("VALUE" ANY ATOM "OPTIONAL"
4095 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
4097 Argument 1 -- the atom whose local value is desired
4099 Argument 2 -- the environment in which to find a value
4100 Returns -- the value
4103 default input channel
4105 MAIN: Returns the main MUDDLE process
4109 Category: PROCESS-CONTROL
4113 MAIN returns the initial MUDDLE PROCESS. This is always
4114 PROCESS 1, and cannot be terminated.
4118 Template: #DECL ("VALUE" PROCESS)
4120 Returns -- The initial, PROCESS 1, PROCESS of the MUDDLE.
4122 Example: <==? <MAIN> <ME>>
4123 Is the PROCESS I am in the main process?
4125 MANIFEST: Declare the global value of an ATOM to be a constant
4129 Category: DATA-HANDLING
4131 Reference: MANIFEST?, GDECL
4133 MANIFEST declares that the current global value of an ATOM is
4134 a constant. Any attempt to SETG it will generate an error, assuming
4135 that DECL-checking is on.
4136 MANIFEST is useful to the compiler because if an ATOM is a
4137 constant its value may be placed directly into the RSUBR, and thus
4138 references to it will be considerably faster. Note that manifesting
4139 a FIX will make applications of it (NTH's, that is) open-compile.
4140 It is not usually a good idea to MANIFEST a GVAL that is large
4141 and complex and used by several FUNCTIONs -- each FUNCTION will get
4142 a copy of it in the result RSUBR.
4146 Template: #DECL ("VALUE" 'T "TUPLE" <TUPLE [REST ATOM]>)
4148 Tuple of arguments -- ATOMs whose GVALs are constants.
4154 Most common use of MANIFEST.
4156 MANIFEST?: Has an ATOM been MANIFESTed?
4160 Category: DATA-HANDLING, PREDICATE
4162 Reference: MANIFEST, UNMANIFEST
4164 MANIFEST? returns T if its argument (an ATOM) has been MANIFESTed,
4165 and #FALSE () otherwise.
4169 Template: #DECL ("VALUE" <OR 'T FALSE> ATOM)
4171 Argument 1 -- An ATOM.
4172 Returns -- T if it is MANIFEST, FALSE if it is not.
4174 Example: <SETG FOO 1>
4181 Make it a constant, then make it not a constant.
4183 MAPF: Map routine onto elements of structured objects.
4187 Category: PROGRAM-CONTROL
4189 Reference: MAPR, MAPRET, MAPSTOP, MAPLEAVE
4191 This is used to map, or apply, a routine to succesive elements
4192 of one or more structured objects. This routine is the second argument
4193 to MAPF and it must take n args, where n is the number of structured
4194 args supplied to the MAPF. In addition another routine can be supplied
4195 to be applied to the results of all of the previous applications.
4196 Usually this routine will take an arbitrary number of arguments. This
4197 secondary routine is given as the first argument to MAPF. However, if
4198 #FALSE () is supplied as the first argument, this indicates that no
4199 such additional application is desired.
4200 Finally the desired structured arguments for mapping are supplied
4201 after the first two arguments.
4202 The primary routine is repeatedly applied to a bunch of the
4203 successive elements from all the structured objects supplied. The
4204 bunch consists of exactly one element from each of the structured
4206 The repeated application continues until one of the structured
4207 objects runs out of elements for the application, OR until the MAPF is
4208 stopped within the application by use of the SUBRs MAPSTOP or MAPLEAVE.
4209 Note that at least one such structured object must be supplied.
4210 The value returned by the MAPF is the result returned by the
4211 application of the additional routine, if any.
4212 If the additional routine is not supplied (the first arg is
4213 #FALSE ()), the value returned is the result of the last application
4214 of the primary routine to the last bunch of elements.
4218 Template: #DECL ("VALUE" ANY <OR FALSE APPLICABLE> APPLICABLE
4219 "TUPLE" <TUPLE STRUCTURED [REST STRUCTURED]>)
4221 Argument 1 -- An applicable object to be used after the mapping phase
4222 is finished, or a FALSE, to simply finish.
4223 Argument 2 -- An applicable object to apply to the elements of the
4225 Tuple of arguments -- At least one structured object, whose elements
4226 will be passed in order as arguments to the second argument of
4228 Returns -- Either the result of APPLYing the first argument to the
4229 stacked results of the repeated application of the second
4230 argument, or the last thing returned by applying the second
4231 argument, or #FALSE () if all of the structured objects were
4234 Example: <MAPF ,LIST ,+ '(1 2 3 4) '(10 11 12 13)>
4235 This will perform the element-wise sum of two lists
4237 MAPLEAVE: Leave from the current MAPF/MAPR with a given value.
4241 Category: PROGRAM-CONTROL
4243 Reference: MAPF, MAPR, MAPRET, MAPSTOP
4245 Leaves from the current MAPF/MAPR without doing the normal
4246 application of a routine to the stacked args. If the optional argument
4247 to MAPLEAVE is supplied, it will be the result of the MAPF/MAPR.
4248 If no such argument is supplied the Atom T will be used instead.
4252 Template: #DECL ("VALUE" ANY "OPTIONAL" ANY)
4255 Argument 1 -- The result of the MAPF/R. If not given, T will be used.
4256 Returns -- Nothing. Terminates a MAPF/R.
4260 <COND (<N==? .X 0> <MAPLEAVE .X>)>>
4262 This example will find and return the first non-zero element of STRUC
4264 MAPR: Map routine onto RESTs of structured objects.
4268 Category: PROGRAM-CONTROL
4270 Reference: MAPF, MAPRET, MAPSTOP, MAPLEAVE
4272 This is used to map, or apply, a routine to succesive RESTs of
4273 one or more structured objects.
4274 Works just like MAPF, see its description, except that instead
4275 of applying the second arg to the elements of the structured objects,
4276 MAPR applys the second arg to the successive RESTs of the structured
4277 objects. This makes it possible to change the arguments that will be
4278 passed to future applications of the second argument before they are
4283 Template: #DECL ("VALUE" ANY <OR FALSE APPLICABLE> APPLICABLE
4284 "TUPLE" <TUPLE STRUCTURED [REST STRUCTURED]>)
4286 Argument 1 -- FALSE or an applicable object to apply to the results
4287 of the repeated applications of the second argument.
4288 Argument 2 -- An applicable object to apply repeatedly to the RESTs of
4289 the remaining arguments.
4290 Tuple of arguments -- At least one structured object to supply RESTs
4291 for the second argument.
4292 Returns -- The result of applying argument 1 to the results of the
4293 repeated applications of argument 2, or the result of the last
4294 such application if argument 1 is FALSE, or #FALSE () if all the
4295 structures were empty and no applications were performed.
4299 <PUT .OB 1 <* <1 .OB> 2>>>
4301 This will change the structure STRUC to contain double its values.
4303 MAPRET: Return an arbitrary number of objects to a MAPF/MAPR.
4307 Category: PROGRAM-CONTROL
4309 Reference: MAPF, MAPR, MAPSTOP, MAPLEAVE
4311 This routine is used to return an arbitrary number of elements
4312 to the current MAPF/R. An invocation of MAPRET ends the current
4313 application of the second argument of MAPF/R. The arguments to MAPRET
4314 are added to the objects being collected to be passed as arguments to
4315 the application of the first argument to MAPF/R.
4316 MAPRET makes it possible to return no arguments or several argu-
4317 ments from one of these intermediate applications.
4321 Template: #DECL ("VALUE" ANY "TUPLE" <TUPLE [REST ANY]>)
4323 Tuple of arguments -- Any number of objects to be added to the group
4324 of potential arguments to the ending application of a MAPF/R.
4325 Returns -- Nothing, really, as the application is ended by MAPRET.
4328 This is used when one desires to return nothing.
4330 MAPSTOP: Stop looping of the current MAPF/MAPR and do the application.
4334 Category: PROGRAM-CONTROL
4336 Reference: MAPF, MAPR, MAPRET, MAPLEAVE
4338 First this Subr acts like MAPRET and causes an arbitrary number
4339 of MUDDLE objects to be stacked for the current MAPF/MAPR. Then it
4340 stops the normal looping operation of this MAPF/MAPR and causes the
4341 normal application of the previously saved applicative object to the
4342 current group of stacked objects.
4343 The result of this application is then returned as the result
4348 Template: #DECL ("VALUE" ANY "TUPLE" <TUPLE [REST ANY]>)
4350 Tuple of arguments -- Any number of arguments to add to the stacked
4351 objects that the final application will apply to.
4352 Returns -- Nothing, terminates MAPF/R looping.
4354 Example: <PROG ((I 10))
4357 <COND (<L? <SET I <- .I 1>> 0>
4362 This example produces a list out of the first ten elements of STRUC.
4363 If there are fewer than ten elements in STRUC, then all are used.
4365 MAX: Maximum of a set of numbers
4369 Category: ARITHMETIC
4373 MAX (Maximum) takes any number of FIXes or FLOATs, and returns
4374 the greatest as its result. If any of the arguments are FLOATs, the
4375 result will be FLOAT. If no argument is given, MAX returns the least
4376 floating-point number. If one argument is given, MAX returns that
4381 Template: #DECL ("VALUE" <OR FIX FLOAT>
4382 "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
4385 Tuple of arguments -- FIXes and FLOATs
4386 Returns -- FIX or FLOAT, floating is contagious.
4388 Example: <MAX 1 2.0>
4390 Floating is contagious.
4392 ME: Returns the process id of the the current process
4396 Category: PROCESS-CONTROL
4398 Reference: MAIN, RESUMER
4400 ME is similar to MAIN, except that it returns the PROCESS ID of
4401 the process it is evaled in, rather than the initial process.
4405 Template: #DECL ("VALUE" PROCESS)
4407 Returns -- The PROCESS Id of the PROCESS it is EVALed in.
4409 Example: <==? <MAIN> <ME>>
4410 Am I the main process?
4412 MEMBER: Is there a similar object in a structure?
4420 MEMBER is used to find a structural copy of an object in a
4421 structure. It takes as arguments and object and a structure. Each
4422 element of the structure is examined in turn, using =?, and if one of
4423 them is =? to the object, the structure is returned, RESTed down to a
4424 point where its first element is the copy.
4425 If no element is structurally identical to the first argument,
4426 #FALSE() is returned.
4430 Template: #DECL ("VALUE" <OR FALSE STRUCTURED> ANY STRUCTURED)
4432 Argument 1 -- Any MUDDLE object.
4433 Argument 2 -- A STRUCTURED object.
4434 Returns -- Either the structure RESTed down to the copy, or FALSE if
4437 Example: <MEMBER 69 [105 104 32 69 81]>
4439 MEMQ would do the same for this example.
4440 <MEMBER "FOO" ["BAR" "FOO" "BLECH"]>
4441 But not for this example. Different strings are =? not ==?.
4443 MEMQ: Is there an identical object in a structure?
4449 Reference: MEMBER, ==?
4451 MEMQ is used to find a copy of an object in a structure. It
4452 takes as arguments and object and a structure. Each element of the
4453 structure is examined in turn, using ==?, and if one of them is ==?
4454 to the object, the structure is returned, RESTed down to a point
4455 where its first element is the copy.
4456 If no element is identical to the first argument, #FALSE() is
4461 Template: #DECL ("VALUE" <OR FALSE STRUCTURED> ANY STRUCTURED)
4463 Argument 1 -- Any MUDDLE object.
4464 Argument 2 -- A STRUCTURED object.
4465 Returns -- Either the structure RESTed down to the copy, or FALSE if
4468 Example: <MEMQ 69 [105 104 32 69 81]>
4470 The copy is now the first element.
4472 MIN: Minumum of a set of numbers
4476 Category: ARITHMETIC
4480 MIN (Minimum) takes any number of FIXes or FLOATs, and returns
4481 the least as the result. If no argument is given, MIN returns the
4482 greatest floating-point number; if one argument is given, MIN returns
4484 If any of the arguments is a FLOAT, the result will be a FLOAT,
4485 no matter what type it was originally.
4489 Template: #DECL ("VALUE" <OR FIX FLOAT>
4490 "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
4493 Tuple of arguments -- FIXes and FLOATs
4494 Returns -- FIX or FLOAT, depending on whether any args were FLOAT.
4496 Example: <MIN 1 2.0>
4498 Takes any number of args
4500 MOBLIST: Create an OBLIST
4504 Category: DATA-HANDLING
4508 MOBLIST creates an oblist--repository for atoms. It is not put
4509 anywhere automatically. If the user wants it in his oblist path, that
4510 must be done explicitly, as in the example.
4511 Note that it is the location of the ATOM passed as argument to
4512 MOBLIST that determines where the new OBLIST will exist.
4513 An association is automatically created for the oblist under the
4514 atom and the indicator OBLIST. Note that this association is checked
4515 by MOBLIST, and a new OBLIST will not be created if one already exists
4516 with the name given.
4520 Template: #DECL ("VALUE" OBLIST ATOM "OPTIONAL" FIX)
4522 Argument 1 -- ATOM, name of OBLIST.
4524 Argument 2 -- FIX, number of hashing buckets, default 13
4525 Returns -- New OBLIST, or old one if one already exists with that name.
4527 Example: <PROG ((OBLIST (<MOBLIST MY-OBLIST> !.OBLIST)))
4529 <GET MY-OBLIST OBLIST>>
4530 The oblist is placed in the path by the setting of the atom OBLIST
4532 MOD: Take a number modulus another number
4536 Category: ARITHMETIC
4538 MOD (Modulus) takes two FIXes and returns the remainder when the
4539 first is divided by the second. This is the standard arithmetic Mod
4544 Template: #DECL ("VALUE" FIX FIX FIX)
4546 Argument 1 -- A FIX.
4547 Argument 2 -- A FIX.
4548 Returns -- FIX, remainder of argument 1 divided by argument 2.
4550 Example: <MOD <RANDOM> 30>
4551 How to get a random number between 0 and 30.
4553 MONAD?: Will NTH and REST fail on this object?
4559 Reference: STRUCTURED?, EMPTY?
4561 MONAD? returns T if and only if NTH and REST will fail on the
4562 object passed as its argument. Obviously this is true of any non-
4563 structured object, but additionally, MONAD? returns T if its argument
4564 is an empty structured object.
4565 MONAD? is thus similar to ORing <NOT <STRUCTURED? object>> and
4570 Template: #DECL ("VALUE" <OR 'T FALSE> ANY)
4572 Argument 1 -- Any MUDDLE object.
4573 Returns -- T if NTH and REST will not work on the object, FALSE if
4576 Example: <OR <NOT <STRUCTURED? .FOO>>
4579 Result is the same for these two forms.
4581 N==?: Test for physical non-identity of two objects.
4589 N==? is the logical complement of ==?. For every case in which
4590 ==? would return T, N==? returns #FALSE() and vice versa.
4591 ==? tests two objects for physical identity. For ==? to return
4592 T (true), the two objects must have the same identical type-value pair.
4593 For example, two STRINGs typed in from the console will not be ==?, but
4594 two ATOMS, FIXes, or nil LISTs will be.
4595 If the two objects are not the same, ==? returns FALSE.
4599 Template: #DECL ("VALUE" <OR 'T FALSE> ANY ANY)
4601 Argument 1 -- Any object.
4602 Argument 2 -- Another object.
4603 Returns -- T if the two objects are different objects, FALSE otherwise.
4605 Example: <N==? "FOO" "FOO">
4607 These two STRINGs look identical, but are not.
4609 N=?: Test for structural non-identity of two objects.
4617 N=? is the logical complement of =?. For every case in which
4618 N==? returns T, =? would have returned FALSE, and vice versa.
4619 =? is a less stringent, but more expensive, test for identity
4620 than ==?. It also takes two objects as arguments, but tests only for
4621 structural identity of the objects, rather than physical identity. If
4622 two objects print the same, they will be =? to each other, except for
4623 numeric fuzz. For example, two STRINGs typed in from the console will
4624 be =? to each other, but not ==?. Any objects that are ==? will also
4625 be =?, and if ==? applies, it should be used. =? is much more
4626 expensive than ==?, in general, as it must test an entire structure
4628 =? returns T if the objects are structurally identical, and FALSE if
4633 Template: #DECL ("VALUE" <OR 'T FALSE> ANY ANY)
4635 Argument 1 -- Any object.
4636 Argument 2 -- Any other object.
4637 Returns -- T if the arguments are not structurally equal, FALSE if they
4640 Example: <N=? <SET V <VECTOR 1 2 3>> <EVAL .V>>
4642 If the test were =?, the result would be T.
4644 NETACC: Network Listening socket accept
4650 Reference: OPEN, NETSTATE, NETS
4652 NETACC takes a network listening socket and accepts a connection.
4653 It will return FALSE if the connection is in the wrong state.
4657 Template: #DECL ("VALUE" <OR FALSE CHANNEL> CHANNEL)
4659 Argument 1 -- A Network channel (a listening socket).
4660 Returns -- The channel, or FALSE if it is in the wrong state.
4662 Example: <NETACC <OPEN "READ" -1 -1 "NET">>
4663 Accept the listening socket.
4665 NETS: Force out the Network buffers of a Network channel
4671 Reference: OPEN, NETSTATE, NETACC
4673 NETS forces any system buffered network output to be sent. The ITS
4674 system normally does this every 1/2 second anyway. Note that this is
4675 similar to the function of BUFOUT for normal channels but more thorough.
4679 Template: #DECL ("VALUE" CHANNEL CHANNEL)
4681 Argument 1 -- A Network channel.
4682 Returns -- The Network channel, with buffers output.
4684 Example: <NETS .NETCHAN>
4687 NETSTATE: Return the state of an ARPA-net connection
4693 Reference: OPEN, NETACC, NETS
4695 NETSTATE returns a UVECTOR of three elements. The first is the
4696 state of the connection, the second is a code specifying why a connection
4697 was closed, and the last is the number of bits available for input.
4698 The meaning of the state and close codes is specified in the
4699 documentation of the ITS NCP (Network Control Program).
4703 Template: #DECL ("VALUE" <UVECTOR FIX FIX FIX> CHANNEL)
4705 Argument 1 -- A MUDDLE channel open to the NETWORK.
4706 Returns -- A UVECTOR containing 3 FIXes, a connection state, a close
4707 code, and the number of bits available on the connection for
4710 Example: <NETSTATE <OPEN "READ" -1 -1 "NET">>
4711 Give state of a network channel open for listening.
4713 NEWTYPE: Create a new MUDDLE type
4717 Category: TYPE-DEFINITION
4721 NEWTYPE creates and specifies a new MUDDLE type. It takes the
4722 name of the new type (an ATOM), the primtype of the new type (also an
4723 ATOM), and optionally, the DECL of the new type.
4724 A new type will print as:
4726 #<name of type> <print representation of primtype>
4728 For example, a <NEWTYPE FOO LIST> would make FOOs that print as:
4732 The new type is added to the type vector (as returned by ALLTYPES),
4733 and becomes legal to DECL, etc. Note that a newtype is not given the
4734 EVALTYPE, APPLYTYPE and so on of its primtype! If you wish it to have
4735 these you must explicitly give them to it. For example, the type FOO
4736 above, when EVALed, will not generate a new FOO with the elements
4737 EVALed. To cause this to happen you must say <EVALTYPE FOO LIST>.
4738 The third (optional) argument allows you to more strongly specify
4739 the makeup of the new type. It is a DECL-body, and it will be assoc-
4740 itated with the type-name under the indicator DECL. Each type an
4741 object is CHTYPEd to the newtype it will be checked against the DECL,
4742 and ERROR will occur if they don't match.
4743 NEWTYPE returns the ATOM given as the name of the new type.
4747 Template: #DECL ("VALUE" ATOM ATOM ATOM
4748 "OPTIONAL" <OR ATOM <FORM 'QUOTE FORM>>)
4750 Argument 1 -- The ATOM name of the new type.
4751 Argument 2 -- The ATOM name of the primtype of the new type.
4753 Argument 3 -- The DECL of the new type.
4754 Returns -- The name of the new type (arg 1).
4756 Example: [<NEWTYPE BAR LIST>
4760 '<<PRIMTYPE LIST> BAR [REST FIX FLOAT]>>
4761 "More strongly specified, even recursive."]
4763 NEXT: Access the next Association in the Association chain.
4767 Category: ASSOCIATION
4769 Reference: ASSOCIATIONS, AVALUE, INDICATOR, ITEM
4771 NEXT returns the next Association in the association chain, given
4772 an ASOC. It is used to access associations further down the chain
4773 than the first, which must be gotten with ASSOCIATIONS. Applying NEXT
4774 to the last association in the chain will return FALSE.
4775 ASSOCIATIONS gives the user access to the association chain in
4776 much the same way as FRAME gives access to the stack. ASSOCIATIONS
4777 returns the first association triad (item, indicator, value) in the
4778 chain, as a type ASOC, which looks, but doesn't behave like, a LIST.
4779 An ASOC may be passed to ITEM, INDICATOR, or AVALUE to retrieve
4780 the elements of a triad, or to NEXT to retrieve the next association
4785 Template: #DECL ("VALUE" <OR FALSE ASOC> ASOC)
4787 Argument 1 -- An ASOC, as returned by NEXT or ASSOCIATIONS.
4788 Returns -- The next association in the association chain, or FALSE if
4789 NEXT was passed the last association.
4791 Example: <NEXT <ASSOCIATIONS>>
4792 Get second association in chain.
4794 NEXTCHR: Return the next input character from an I/O channel
4802 NEXTCHR returns the character which READCHR will return the
4803 next time it is called. Successive calls, with no intervening input
4804 operations, all return the same thing.
4808 Template: #DECL ("VALUE" <OR CHARACTER FIX> "OPTIONAL" CHANNEL
4812 Argument 1 -- the channel
4813 Argument 2 -- object to eval and return at end of file
4814 Returns -- the next character (-1 if empty STY device)
4818 what you get if called by itself
4820 NOT: Change the truth value of an object to its complement
4824 Category: LOGICAL, CONDITIONAL
4826 Reference: AND, OR, COND
4828 NOT complements the truth value of its argument. If its
4829 argument was a FALSE, NOT returns T, if its argument was non-FALSE,
4830 NOT returns a FALSE.
4834 Template: #DECL ("VALUE" <OR 'T FALSE> ANY)
4836 Argument 1 -- ANY object.
4837 Returns -- The logical complement of the truth value of the object.
4839 Example: <NOT <NOT #FALSE ("FILE NOT FOUND")>>
4841 Note the loss of detail in complementing the complement.
4843 NTH: Get the Nth element of a structure
4847 Category: DATA-HANDLING
4851 NTH returns the n'th element of a stucture. It takes the
4852 structure and the number of the element to return, where 1 is the
4853 first element, and so on.
4854 If the structure does not have an Nth element, an ERROR occurs.
4855 LENGTH can be used to help find out if a structure has an Nth element.
4856 Note that NTH is cheap on VECTORs, UVECTORs and such, and
4858 An application of a FIX, or something that EVALs to a FIX, to
4859 a structure is equivalent to an application of NTH, assuming that the
4860 order of evaluation is not important:
4866 <NTH .X <LENGTH <SET X .Y>>>
4867 and <<LENGTH <SET X .Y>> .X>
4869 are not equivalent, the order of evaluation makes a difference.
4873 Template: #DECL ("VALUE" ANY STRUCTURED "OPTIONAL" FIX)
4875 Argument 1 -- A Structured object.
4877 Argument 2 -- A FIX, the element number to return, default 1.
4878 Returns -- The contents of the Arg-2th element of the structure.
4880 Example: <2 (4 5 6)>
4883 The first is equivalent to the second as long
4884 as order of evaluation makes no difference.
4886 OBLIST?: Return the OBLIST that contains a given ATOM
4890 Category: IDENTIFIER, CONDITIONAL
4892 Reference: INSERT, ATOM, REMOVE
4894 OBLIST? returns the OBLIST that contains a given ATOM, or FALSE
4895 if the ATOM is not on an OBLIST (hence the ?). It is usually used for
4896 the first purpose (to find out what OBLIST an ATOM is on).
4900 Template: #DECL ("VALUE" <OR OBLIST FALSE> ATOM)
4902 Argument 1 -- An ATOM.
4903 Returns -- Either the OBLIST that ATOM is on, or FALSE if it is not on
4906 Example: <OBLIST? FOO>
4908 <OBLIST? <REMOVE FOO>>
4911 If you type in the ATOM as part of the form, it will naturally be on
4914 OFF: Turn off an interrupt IHEADER or HANDLER
4920 OFF permits the user to remove an IHEADER or HANDLER. OFFing the
4921 IHEADER causes MUDDLE to completely ignore the interrupt and OFFing a
4922 HANDLER causes the function associated with that particular HANDLER
4924 OFF may also be used with strings or atoms to identify IHEADERs
4925 as in EVENT. As usual "CHAR" requires the channel as an additional
4926 argument, and "READ" and "WRITE" require the locative as an
4927 additional argument.
4931 Template: #DECL ("VALUE" <OR FALSE IHEADER HANDLER>
4932 <OR IHEADER HANDLER STRING ATOM> "OPTIONAL"
4933 <OR CHANNEL LOCATIVE>)
4935 Argument 1 -- An IHEADER, HANDLER, STRING or ATOM identifying exactly
4936 what interrupt or interrupt handler to remove.
4938 Argument 2 -- If the CHAR interrupt is the one being OFFed, the
4939 channel is also needed with which the interrupt was paired.
4940 If the READ or WRITE interrupt is the one being OFFed, the
4941 locative is also needed with which the interrupt was paired.
4942 Returns -- The OFFed IHEADER or HANDLER, if successful, or FALSE if
4943 there was nothing to remove.
4945 Example: <OFF "CLOCK">
4946 Turns off the CLOCK interrupt.
4948 OFFSET: Create an OFFSET
4952 Category: STRUCTURES
4954 Reference: NTH, INDEX, GET-DECL, PUT-DECL
4956 An OFFSET is a "frozen" NTH. Given a fix and a DECL, it creates
4957 an APPLICABLE object which may be applied to structures to get the fixth
4958 element or to a structure and an object to change the fixth element to
4963 Template: #DECL ("VALUE" OFFSET FIX <OR ATOM FORM>)
4965 Argument 1 -- The element of the structure the offset refers to.
4966 Argument 2 -- A DECL which describes the structure (the entire structure,
4967 not the element) the offset is an offset into.
4968 Returns -- The OFFSET.
4970 Example: <SET O <OFFSET 1 '<CHANNEL FIX>>>
4971 %<OFFSET 1 '<CHANNEL FIX>>
4974 ON: Create and turn on an interrupt handler
4980 Reference: OFF, EVENT, HANDLER
4982 ON is equivalent to a call to EVENT followed by a call to HANDLER.
4983 It causes an interrupt handler to be created and added to the list of
4984 handlers for a given interrupt.
4986 <ON "CLOCK" ,FOO 1 ,P>
4990 <HANDLER <EVENT "CLOCK" 1> ,FOO ,P>
4992 In the case of "CHAR" or "READ"/"WRITE", the channel or
4993 locative is the last argument. In this case the process argument may
4994 be zero and is equivalent to no process being given.
4998 Template: #DECL ("VALUE" HANDLER <OR STRING ATOM> APPLICABLE FIX "OPTIONAL"
4999 <OR FIX PROCESS> <OR CHANNEL LOCATIVE>)
5001 Argument 1 -- The name of the interrupt. Note that if it is not one
5002 of the existing interrupts in the INTERRUPTS OBLIST, no ERROR,
5003 the interrupt is assumed to be a software one!
5004 Argument 2 -- An APPLICABLE, to be called with the appropriate number
5005 of arguments when the interrupt occurs.
5006 Argument 3 -- The priority of the interrupt.
5008 Argument 4 -- the PROCESS in which to run the interrupt, 0 means the
5010 Argument 5 -- If a "CHAR" interrupt, the CHANNEL.
5011 If a "READ" or "WRITE" interrupt, the LOCATIVE.
5012 Returns -- The HANDLER for the interrupt.
5014 Example: <ON "CLOCK" <FUNCTION () <PRINC " TICK ">> 1>
5016 OPEN-NR: Create and open an I/O channel without changing file's reference date
5024 OPEN-NR is the same as OPEN (q.v.), except that the date of last
5025 reference of the opened file is not changed.
5029 Template: #DECL ("VALUE" <OR CHANNEL <FALSE STRING STRING FIX>>
5030 "OPTIONAL" STRING "TUPLE" TUPLE)
5034 Tuple of arguments -- 'file specification'
5035 Returns -- channel or false giving reason for failure & filename
5037 Example: <OPEN-NR "READ" "OLD FILE">
5038 so it will be reaped sooner
5040 OPEN: Create and open an I/O channel
5046 Reference: CHANNEL, RESET
5048 OPEN creates a channel for subsequent input or output.
5049 All arguments are optional. The first arg is the mode for the channel,
5050 a string from the list ("READ" "PRINT" "READB" "PRINTB" "PRINTO"
5051 "DISPLAY"), default "READ". The other arguments specify the file
5052 or other 'external storage medium' involved. These can be:
5053 . a string giving the complete file name
5054 . several strings giving name1, name2, device, and directory
5055 . the string "INT:" and a function, a source or sink for characters
5056 . two fixes, the string "NET", and two more fixes
5057 Omitted parts of the file specification follow these defaults:
5058 <VALUE NM1>, if any, else "INPUT"
5059 <VALUE NM2>, if any, else ">"
5060 <VALUE DEV>, if any, else "DSK"
5061 <VALUE SNM>, if any, else the 'working directory'
5062 For more details, see the manual, SYS.11.01.
5066 Template: #DECL ("VALUE" <OR CHANNEL <FALSE STRING STRING FIX>>
5067 "OPTIONAL" STRING "TUPLE" TUPLE)
5071 Tuple of arguments -- 'file' specification
5072 Returns -- a channel or a false giving the reason for failure & filename
5074 Example: <OPEN "PRINT" "TPL:">
5075 Make a channel for line-printer output.
5077 OR: Logical OR of its arguments.
5081 Category: PREDICATE, PROGRAM-CONTROL
5083 Reference: COND, AND, OR?
5085 OR is an FSUBR that evaluates its arguments, one by one, until
5086 either one of them returns a non-FALSE or it runs out of arguments.
5087 The fact that it is an FSUBR means that it can be used as a
5088 miniature COND. A construct of the form <OR preconditions thing> will
5089 allow 'thing' to be executed only if 'preconditions' is false. In
5090 combination with AND, fairly powerful constructs can be generated.
5091 OR takes any number of arguments, returning either the result of
5092 its last evaluation (#FALSE () if no arguments were given) or the
5093 non-FALSE that caused it to complete.
5097 Template: #DECL ("VALUE" <OR FALSE ANY> "ARGS" LIST)
5099 List of arguments -- ANY evalable objects.
5100 Returns -- Terminating non-FALSE or FALSE if all elements were FALSE.
5102 Example: <OR <LOOKUP "FOO" <ROOT>> <INSERT "FOO" <ROOT>>>
5104 This construct only attempts to insert FOO in the ROOT if it is not
5105 already there, avoiding the possibility of an ERROR.
5107 OR?: Logical OR of its arguments, evaluated at call time
5111 Category: PREDICATE, PROGRAM-CONTROL
5113 Reference: AND?, OR, MAPF, MAPR
5115 OR is a SUBR that looks at its arguments, one by one, until
5116 either one of them is a non-FALSE or it runs out of arguments.
5117 The fact that it is a SUBR means that it can be used as a
5118 first argument to MAPF or MAPR.
5119 OR takes any number of arguments, returning either
5120 its last argument (#FALSE () if no arguments were given) or the
5121 non-FALSE that caused it to complete.
5125 Template: #DECL ("VALUE" <OR FALSE ANY> "TUPLE" TUPLE)
5127 Tuple of arguments -- ANY objects.
5128 Returns -- Terminating non-FALSE or FALSE if all elements were FALSE.
5130 Example: <MAPF ,OR? <FUNCTION (T) <G? .T 0>> .VECTOR>
5131 Is any element of VECTOR positive?
5133 ORB: Bitwise logical OR
5137 Category: ARITHMETIC, BIT-TWIDDLING
5139 Reference: EQVB, XORB, ANDB
5141 ORB takes any number of objects of Primtype WORD, and returns
5142 a WORD containing the bitwise logical OR of the arguments.
5146 Template: #DECL ("VALUE" WORD
5147 "TUPLE" <TUPLE [REST <PRIMTYPE WORD>]>)
5149 Tuple of arguments -- Objects of primtype WORD to be ORed together.
5150 Returns -- A WORD containing the bitwise OR of the arguments.
5152 Example: <ORB #WORD *000000000001*
5153 #WORD *000000000001*
5154 #WORD *000000042260*>
5155 #WORD *000000042261*
5156 Primarily useful for getting fingers directly in the bits.
5158 OVERFLOW: Enable or disable overflow error
5162 Category: ARITHMETIC
5164 Reference: +, -, *, /
5166 OVERFLOW disables or enables -- if its argument is a FALSE or not,
5167 respectively -- overflow and underflow errors caused by arithmetic
5168 SUBRs. Initially these errors are enabled.
5172 Template: #DECL ("VALUE" <OR 'T '#FALSE ()>
5173 "OPTIONAL" <OR ANY FALSE>)
5176 Argument 1 -- whether or not to enable over/underflow errors
5177 Returns -- the previous state, initially true, or current state if no arg
5179 Example: <OVERFLOW T>
5182 PARSE: Parse a string into a MUDDLE object
5186 Category: DATA-HANDLING
5188 Reference: UNPARSE, LPARSE
5190 Parse a string into a MUDDLE object, just like reading from a
5191 string instead of a channel.
5192 PARSE takes from 0 to 5 arguments. If parse is given no arguments,
5193 it returns the first item parsed from the local value of the string
5194 PARSE-STRING, and additionally, sets PARSE-STRING to the string having
5195 those characters which were parsed rested off. If parse is given a
5196 string to parse, the atom, PARSE-STRING, is rebound to the string within
5197 that call. If the parse table argument is given to PARSE, the value of
5198 PARSE-TABLE is rebound to it within that call to PARSE. Finally, PARSE
5199 takes a look ahead character, which is treated as if it were logically
5200 concatenated to the front of the string being parsed. The full calling
5201 sequence of PARSE is:
5203 <PARSE string radixfornumberconversion oblistorlistofoblists
5204 parsetable lookaheadchar>
5209 Template: #DECL ("VALUE" ANY "OPTIONAL" STRING
5211 <LIST [REST <OR OBLIST 'DEFAULT>]>>
5215 Argument 1 -- STRING to parse, if not given, LVAL of PARSE-STRING.
5216 Argument 2 -- FIX, radix for number conversion.
5217 Argument 3 -- An OBLIST or LIST of OBLISTs.
5218 Argument 4 -- A parse-table.
5219 Argument 5 -- A prefix character.
5220 Returns -- A MUDDLE object.
5222 Example: <PARSE "<+ 1 2>">
5223 Returns the FORM <+ 1 2>.
5225 PCODE: Create pointer to pure RSUBR code
5231 PCODE returns a pure code vector for an RSUBR, given a name
5232 in the internal table of pure RSUBRs and the offset in the block of
5233 code where the RSUBR entry point is. It is most often seen when
5234 a pure code vector is output, as %<PCODE "&" &>.
5238 Template: #DECL ("VALUE" PCODE STRING FIX)
5240 Argument 1 -- name in pure-RSUBR table
5241 Argument 2 -- offset in the code
5242 Returns -- a pure code vector
5244 Example: <PCODE "PPRINT" 0>
5245 Calls like this fill FBIN files.
5247 PNAME: Create a distinct STRING which is the name of an ATOM
5251 Category: IDENTIFIER
5253 Reference: ATOM, INSERT, SPNAME
5255 PNAME takes as argument an ATOM, and returns the STRING which
5256 is the PNAME (printing name) of that ATOM. This name does not include
5257 any oblist trailers or the backslashes that are sometimes printed out
5258 for the convenience of the reader. Several other SUBRs, notably
5259 INSERT, LOOKUP, and ATOM, use the pname of atoms as arguments.
5260 PRINC of the PNAME of an ATOM is one guaranteed way of printing
5261 an ATOM-name without trailers, backslashes, or quotes.
5265 Template: #DECL ("VALUE" STRING ATOM)
5267 Argument 1 -- An ATOM.
5268 Returns -- A STRING which contains the atom's pname.
5270 Example: <PNAME \ \ \ !-FOO!-BAR>
5272 Just three spaces, no backslashes, no trailers.
5274 PRIMTYPE-C: Get a primtype code for an object
5278 Category: TYPE-DEFINITION
5280 Reference: PRIMTYPE TYPE-C
5282 PRIMTYPE-C returns the 'storage type code' for an object.
5283 This gives no more info than PRIMTYPE (q.v.), except for TEMPLATEs:
5284 each TYPE of TEMPLATE has a different PRIMTYPE-C.
5288 Template: #DECL ("VALUE" PRIMTYPE-C ATOM)
5290 Argument 1 -- the type to get a code for
5291 Returns -- a 'storage type code'
5293 Example: <PRIMTYPE-C <NEWTYPE FOO TEMPLATE>>
5294 returns a 'storage type code' for my template
5296 PRIMTYPE: Return the primitive type of an object
5302 Reference: UTYPE, TYPE, TYPEPRIM
5304 PRIMTYPE is applied to any MUDDLE object to return an ATOM which
5305 is the name of the PRIMITIVE type of that object. TYPE, which is
5306 similar, returns the type of the object given. TYPEPRIM returns the
5307 primitive type given the name of the type.
5311 Template: #DECL ("VALUE" ATOM ANY)
5313 Argument 1 -- Any MUDDLE object.
5314 Returns -- ATOM, the name of the primitive type of the argument.
5321 PRIMTYPE will obviously return the same result for a larger class of
5322 objects than will TYPE.
5324 PRIN1: Print an object on an I/O channel
5332 PRIN1 is exactly like PRINT (q.v.) except that it omits the new-line
5333 before and the space afterward.
5337 Template: #DECL ("VALUE" ANY ANY "OPTIONAL" CHANNEL)
5339 Argument 1 -- the object
5341 Argument 2 -- the output channel, default .OUTCHAN
5342 Returns -- the object
5345 boring example, sorry
5347 PRINC: Print an object on an I/O channel without indicators
5353 Reference: PRIN1, PRINT
5355 PRINC is exactly like PRIN1 (q.v.) except that it omits "s around
5356 strings, !\s before characters, and \s and trailers for atoms.
5360 Template: #DECL ("VALUE" ANY ANY "OPTIONAL" CHANNEL)
5362 Argument 1 -- the object
5364 Argument 2 -- the output channel, default .OUTCHAN
5365 Returns -- the object
5369 <PRINC "LISTENING-AT-LEVEL MEZZANINE PROCESS CHEESE">
5373 PRINT: Print an object on an I/O channel on a new line
5379 PRINT outputs the character representation (unparsing) of its first
5380 argument, preceded by carriage-return/line-feed and succeeded by a space.
5384 Template: #DECL ("VALUE" ANY ANY "OPTIONAL" CHANNEL)
5386 Argument 1 -- the object
5388 Argument 2 -- the output channel, default .OUTCHAN
5389 Returns -- the object
5392 not a very wonderful example
5394 PRINTB: Write binary words on an I/O channel
5400 PRINTB writes the entire contents of its first argument into a given
5401 channel, as 36-bit binary words.
5405 Template: #DECL ("VALUE" <OR UVECTOR STORAGE>
5406 <<OR UVECTOR STORAGE> [REST <PRIMTYPE WORD>]> CHANNEL)
5408 Argument 1 -- the buffer whose contents to write
5409 Argument 2 -- the output channel, open in PRINTB or PRINTO mode
5412 Example: <PRINTB .BUFFER .PRINTB-CHNL>
5413 Can't use a console channel.
5415 PRINTSTRING: Write contents of string on an I/O channel
5421 PRINTSTRING writes the entire contents or initial characters of a
5422 string on a given channel. The output appears identical to that
5427 Template: #DECL ("VALUE" FIX STRING "OPTIONAL" CHANNEL FIX)
5429 Argument 1 -- the string to write out
5431 Argument 2 -- the output channel, default .OUTCHAN
5432 Argument 3 -- number of characters to output, default all
5433 Returns -- number of characters output
5435 Example: <READSTRING .TRASH
5437 <PRINTSTRING "HI THERE!" .STY-OUT>>
5438 Suck out the echoed characters on your pseudo-console.
5440 PRINTTYPE: Change or examine the way a TYPE is PRINTed
5444 Category: TYPE-MANIPULATION, PROGRAM-CONTROL, I/O
5448 Changes the way a specific type is PRINTed, by either mapping
5449 it into another type, or giving an explicit method via an APPLICABLE.
5450 If a type is given, the type being changed will be PRINTed in the
5451 same manner as that type. Note that in this case the two types must
5452 be of the same PRIMTYPE or else ERROR.
5453 If an APPLICABLE is given, it should take one argument, which
5454 will be the object being PRINTed. If ,PRINT is given, the type will
5455 receive no special treatment in printing.
5456 If no second argument is given, PRINTTYPE returns the last arg
5457 given it for that TYPE, or else #FALSE () if the type is receiving no
5458 special treatment in printing.
5462 Template: #DECL ("VALUE" <OR ATOM APPLICABLE FALSE> ATOM "OPTIONAL"
5463 <OR ATOM APPLICABLE>)
5465 Argument 1 -- The type whose PRINTTYPE to change or examine.
5467 Argument 2 -- A TYPE (which means 'Print like this type'), or an
5468 APPLICABLE (meaning 'use this when you PRINT this type').
5469 Returns -- The TYPE which was changed or, if no arg 2, the way the
5470 TYPE is being printed.
5472 Example: <PRINTTYPE FORM LIST>
5473 Combine with example for EVALTYPE and make MUDDLE look like LISP.
5474 <PRINTTYPE FORM <FUNCTION (X) <PRINC "FOO">>>
5475 Confuse your friends.
5477 PROCESS: Create a new PROCESS
5481 Category: TYPE-MANIPULATION, PROCESS-CONTROL
5483 Reference: RESUME, STATE
5485 PROCESS creates a new PROCESS with a given start up function.
5486 This must be an APPLICABLE of one argument, which must be evaled.
5487 If the starter of a PROCESS ever returns a value, that PROCESS is DEAD.
5488 Note that creating a PROCESS will often cause a GC.
5492 Template: #DECL ("VALUE" PROCESS APPLICABLE)
5494 Argument 1 -- An APPLICABLE which takes a single evaluated argument.
5495 Returns -- A new PROCESS.
5498 <SET P <PROCESS ,LISTEN>>
5499 Creates a process which is a read-eval-print loop like <MAIN>.
5502 Means P has never run.
5506 To treat a process like a simple function:
5507 <RESUME T <PROCESS <FUNCTION (X) .X>>>
5508 Starts it, returns the result of applying arg1 (T) to the function,
5511 PROG: Execute sequential expressions
5515 Category: PROGRAM-CONTROL
5519 This FSUBR is used to bind variables and sequentially execute
5520 MUDDLE expressions and perform appropriate GOs, RETURNs, and AGAINs.
5521 If the first argument to PROG is an atom, it is bound to the
5522 Activation of the PROG.
5523 Otherwise the next object must be the argument list of the PROG.
5524 It contains either Atoms or Lists of an Atom and a MUDDLE expression.
5525 Each single Atom in the argument list is Bound but not Assigned. Each
5526 'listified' Atom is Bound and Assigned to the evaluation of the MUDDLE
5527 expression which appears with it.
5528 If the next argument to the PROG is of type DECL, it is used as
5529 the declaration for the variables of the PROG.
5530 The remaining arguments, at least one must exist, constitute the
5531 body of the PROG. They are executed in sequence with the value of the
5532 last being the value for the entire PROG, unless a RETURN from the
5533 activation of the PROG (explicit or with only one argument) is done.
5537 Template: #DECL ("VALUE" ANY "ARGS" <LIST ATOM LIST DECL ANY>)
5539 Optional argument 1 -- An ATOM, to bind the activation of the PROG to.
5540 Argument 2 -- A parameter LIST.
5541 Optional argument 3 -- The DECL of the PROG.
5542 Remainder of arguments -- At least one object, to be sequentially evaled.
5543 Returns -- The last thing evaled in the PROG, or the argument to a
5544 RETURN within the PROG.
5546 Example: <PROG ((C <OPEN "READ" "FOO BAR">))
5550 This will FOO only if the file FOO BAR exists.
5552 PURIFY: Purify objects everywhere
5558 Reference: SUBSTITUTE, FSAVE, RESTORE
5560 PURIFY causes a mini-GC, like SUBSTITUTE, resulting in its args
5561 becoming pure and sharable, and ignored by the garbage collector.
5562 No arg can live on the stack or be of primtype process, locd, or
5563 asoc. Sharing between jobs/forks actually occurs after FSAVE/RESTORE.
5567 Template: #DECL ("VALUE" ANY "TUPLE" TUPLE)
5569 Tuple of Arguments -- the objects to be purified, not RSUBRs
5570 Returns -- its last arg, now pure
5572 Example: <PURIFY .GROUP>
5573 OK if no RSUBRs in the group
5575 PUT-DECL: Give a value a DECL or change the existing one
5579 Category: DATA-HANDLING
5583 PUT-DECL gives a DECL to a global or local value, or changes
5584 the existing DECL. It takes a locative to the value and a DECL, which
5585 cannot be FALSE or MANIFEST. It modifies the DECL of the value to
5586 be that second argument.
5587 Note that the new DECL must correspond with the type of the
5588 value, if <DECL-CHECK> is T. For example, if the value is a FIX, you
5589 cannot change the DECL to be VECTOR, without first changing the value.
5591 PUT-DECL may also be used to make a new OFFSET from an old one, given
5592 a new DECL part for the OFFSET.
5596 Template: #DECL ("VALUE" LOCD <OR LOCD OFFSET> <OR ATOM <FORM 'QUOTE FORM>>)
5598 Argument 1 -- A locative to a value of an ATOM, or an OFFSET.
5599 Argument 2 -- A new DECL for that value, or a new OFFSET.
5600 Returns -- Argument 1.
5602 Example: <SETG FOO 1>
5604 <GDECL (FOO) <PRIMTYPE WORD>>
5606 <GET-DECL <GLOC FOO>>
5608 <PUT-DECL <GLOC FOO> FIX>
5609 returns locative here
5610 <PUT-DECL <GLOC FOO> VECTOR>
5611 here ERROR, type mismatch, as GVAL of FOO is FIX.
5613 <PUT-DECL <SET X <OFFSET 1 '<FOO FIX>>> '<CHANNEL FIX>>
5614 %<OFFSET 1 '<CHANNEL FIX>>
5615 Note that this is a new OFFSET:
5617 %<OFFSET 1 '<FOO FIX>>
5620 PUT: Change an element of a structure or make an association
5624 Category: DATA-HANDLING, ASSOCIATION
5626 Reference: PUTPROP, GET
5628 PUT associates a property with an item or (as with GET) if arg 1
5629 is structured and arg 2 is fix, insert the third arg as the fix'th
5631 PUT is thus exactly like PUTPROP if the first argument is not
5632 structured or the second not FIX. If used as PUTPROP, and no third
5633 argument is given, removes any association between ARG 1 and ARG 2.
5634 Returns the first argument.
5638 Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY)
5640 Argument 1 -- ANY, the object with the association, or the structure
5641 whose Nth element to replace.
5642 Argument 2 -- ANY, the indicator under which the association is
5643 stored, if fix and first arg a structure, clobber the fix'th
5644 element with the value instead.
5646 Argument 3 -- ANY, the value to be associated, if none, the previous
5647 association is removed.
5648 Returns -- The result is the first argument.
5650 Example: <PUT FOO 1 BAR>
5653 If .FOO is structured, clobber its first element.
5655 PUTBITS: Change part of a WORD
5659 Category: BIT-TWIDDLING
5661 Reference: BITS, GETBITS
5663 PUTBITS changes part of a PRIMTYPE WORD, as described by a BITS
5664 and a PRIMTYPE WORD. It takes the rightmost bits of the third
5665 argument, which defaults to 0, and clobbers the bit positions
5666 indicated by the BITS in the first argument.
5667 It is functionally equivalent to the PDP-10 Deposit Byte (DPB)
5672 Template: #DECL ("VALUE" <PRIMTYPE WORD> <PRIMTYPE WORD> BITS
5673 "OPTIONAL" <PRIMTYPE WORD>)
5675 Argument 1 -- A PRIMTYPE WORD, the destination of the bits.
5676 Argument 2 -- A BITS, describes how many bits to move and where in the
5677 output word to put them.
5679 Argument 3 -- A PRIMTYPE WORD, the source of the bits to move, default 0.
5680 Returns -- The new version of argument 1. Arg 1 itself is not changed.
5682 Example: <PUTBITS -1 <BITS 6 3>>
5684 Args need not be of type WORD.
5686 PUTPROP: Change or create an association
5690 Category: DATA-HANDLING, ASSOCIATION
5694 PUTPROP associates a property with an item under a given
5695 indicator. If no property (or value) is given, any association of the
5696 item and indicator is removed. Note that if PUT's first argument is
5697 not structured and its second argument is not FIX, it is identical to
5699 Returns the first argument.
5703 Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY)
5705 Argument 1 -- ANY, the object with the association
5706 Argument 2 -- ANY, the indicator under which the association is to be
5709 Argument 3 -- ANY, the value to be associated, if none, the previous
5710 association is removed.
5711 Returns -- The result is the first argument.
5713 Example: <PUTPROP .FOO 1 BAR>
5716 If .FOO is structured, clobber its first element, else make association.
5718 PUTREST: Make REST of a LIST a given LIST
5722 Category: DATA-HANDLING
5726 PUTREST replaces the rest of a list making arg2 be REST of arg1.
5727 Notice that this does not copy the lists, so it can be used to produce
5732 Template: #DECL ("VALUE" <PRIMTYPE LIST>
5733 <PRIMTYPE LIST> <PRIMTYPE LIST>)
5735 Argument 1 -- A LIST, rest of which will be replaced by Argument 2.
5736 Argument 2 -- A LIST, which will become the new REST of Argument 1.
5737 Returns -- The new LIST.
5739 Example: <PUTREST <REST <SET X (1 2 3)> 2> (4 5 6)>
5741 .X will now be (1 2 3 4 5 6).
5742 <PUTREST <SET CIRCULAR (0)> .CIRCULAR>
5743 Create a circular LIST of one element.
5751 Reference: LOGOUT, VALRET
5753 Causes a MUDDLE to VALRET the string ':KILL<cr>' to its
5754 superior. This will cause the superior to kill the MUDDLE job.
5763 Only possible example.
5765 QUITTER: Default character interrupt SUBR
5773 QUITTER is not normally called by user programs. It is the
5774 default character interrupt SUBR that handles ^S and ^G
5778 Template: #DECL ("VALUE" ANY CHARACTER CHANNEL)
5780 Argument 1 -- The CHARACTER typed.
5781 Argument 2 -- The CHANNEL which produced the interrupt.
5782 Returns -- The CHARACTER typed.
5784 Example: For the best example, type ^G and then <FRAMES> to a MUDDLE.
5786 QUOTE: Return its first argument unEVALed.
5794 The QUOTE Fsubr takes unEVALuated arguments and returns the first.
5795 It is the way to circumvent the normal EVALuation mechanism.
5796 Note that 'object is an abbreviation for <QUOTE object>.
5800 Template: #DECL ("VALUE" ANY "ARGS" LIST)
5802 Arguments -- ANY objects; the first will be returned untouched by QUOTE.
5803 Returns -- Its first argument, untouched by interpreted hands.
5812 This will cause the Vector to be returned unEVALuated and therefore
5813 without the overhead of copying.
5817 This will return a list of Forms.
5819 RANDOM: Generate a random FIX
5823 Category: ARITHMETIC
5825 RANDOM generates a random FIX. If the seeds of the MUDDLE
5826 random number generator are not touched, repeated invocations of
5827 RANDOM will return the exact same sequence of numbers. This is for
5828 convenience in debugging. 'Debugged' code should pass the first and
5829 second optional arguments to RANDOM, which change the two seeds it
5830 uses to generate its numbers. Popular choices of new seeds are the
5831 numbers returned by TIME and the contents of various UVECTOR buffers.
5835 Template: #DECL ("VALUE" FIX "OPTIONAL" FIX FIX)
5838 Arguments 1 and 2 -- New seed settings for the random number generator.
5839 Returns -- A random FIX.
5841 Example: <MOD <RANDOM> 30>
5842 How to generate a random number between 0 and N.
5844 READ: Read one object from an I/O channel
5850 READ returns the entire object whose character representation is next
5851 in the input stream. If there is a comment on the object, it is PUT
5852 on the channel used with indicator COMMENT.
5856 Template: #DECL ("VALUE" ANY "OPTIONAL" CHANNEL ANY
5857 <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>
5861 Argument 1 -- input channel, default .INCHAN
5862 Argument 2 -- object to eval and return at end of file, default
5863 <ERROR END-OF-FILE!-ERRORS>
5864 Argument 3 -- oblist or list therof for looking up atoms, default .OBLIST
5865 Argument 4 -- READ-TABLE giving special characters, default .READ-TABLE
5866 Returns -- the object read
5868 Example: <SET NEWOBJ <READ>>
5869 Calls like this make you CALICO-incompatible.
5871 READB: Read binary words from an I/O channel
5877 READB fills a buffer with 36-bit binary words and returns the
5878 number of words read. If the end of file is reached, this number will
5879 be less than the size of the buffer. If another READB is attempted,
5880 the end-of-file arg will be evaled and returned.
5884 Template: #DECL ("VALUE" FIX
5885 <<OR UVECTOR STORAGE> [REST <PRIMTYPE WORD>]> CHANNEL
5888 Argument 1 -- buffer to fill
5889 Argument 2 -- "READB" channel
5891 Argument 3 -- object to eval and return at end of file
5892 Returns -- number of binary words read
5894 Example: <READB <OPEN "READB" "DSK:.FILE. (DIR)">
5896 Get your file directory in binary form.
5898 READCHR: Read one character from an I/O channel
5906 READCHR returns the next character in the input stream from a
5907 given channel. Successive calls return successive characters. If the
5908 channel is open to a console, receipt of a character is held off until
5909 an ESC is typed. If it is open to a pseudo-console in "READ" mode
5910 and no input is available, READCHR returns -1.
5914 Template: #DECL ("VALUE" <OR CHARACTER FIX> "OPTIONAL" CHANNEL
5918 Argument 1 -- the channel to read from
5919 Argument 2 -- object to eval and return at end of file
5920 Returns -- the character read (-1 if empty STY device)
5924 If called alone, you get the ESC.
5926 READSTRING: Read into a string from an I/O channel
5934 READSTRING is the string analog to READB (q.v.). It fills a string
5935 buffer with characters from a channel, returning the number of characters
5936 input. One argument tells when to stop reading: after a certain number
5937 of characters or upon reading one of a set of characters.
5941 Template: #DECL ("VALUE" FIX STRING "OPTIONAL" CHANNEL <OR FIX STRING>
5944 Argument 1 -- buffer to read into
5946 Argument 2 -- channel to read from, default .INCHAN
5947 Argument 3 -- number of chars to read or char to stop reading on
5948 Argument 4 -- object to eval and return at end of file
5949 Returns -- number of characters read
5951 Example: <READSTRING " ">
5953 You get the ESC if called alone.
5955 REALTIMER: Set interval between Real-time interrupts
5963 REALTIMER sets the interval (in seconds) between REALT (real-
5964 time) interrupts. The MUDDLE will be interrupted each time this many
5969 Template: #DECL ("VALUE" <OR FIX FLOAT> <OR FIX FLOAT>)
5971 Argument 1 -- Interval between Real-time interrupts (in seconds).
5972 Returns -- Argument 1.
5974 Example: <REALTIMER <* 10 60>>
5975 Interrupt every ten minutes.
5977 REMOVE: Remove an ATOM from its OBLIST
5981 Category: IDENTIFIER
5983 Reference: INSERT, LOOKUP
5985 REMOVE is the opposite of INSERT. It takes a single argument, an
5986 ATOM, and removes that ATOM from its OBLIST. It can also take two
5987 arguments, a STRING and an OBLIST, and removes the ATOM of that PNAME
5988 from that OBLIST. The ATOM, which now is on no OBLIST, and therefore
5989 has a trailer of !-#FALSE(), is returned. If the ATOM was originally
5990 on no OBLIST, or if the STRING names no ATOM on the OBLIST, REMOVE
5995 Template: #DECL ("VALUE" <OR ATOM FALSE> <OR ATOM STRING> "OPTIONAL"
5998 Argument 1 -- The ATOM to flush from its OBLIST, or a STRING.
6000 Argument 2 -- If arg 1 was a STRING, this is the OBLIST to mung.
6001 Returns -- The now homeless ATOM.
6003 Example: <INSERT <REMOVE FOO> <ROOT>>
6004 You can move ATOMs from one OBLIST to another with REMOVE and INSERT.
6006 RENAME: Rename or delete a disk file
6012 RENAME is for renaming and deleting files. It takes three
6014 (a) two file names (one or more strings) separated by the atom TO,
6015 (b) one file name, or
6016 (c) a channel (output mode) and a file name.
6017 Omitted file-name parts use the OPEN defaults. The action is, respectively,
6018 (a) rename the file named first to the second name,
6019 (b) delete the file, or
6020 (c) rename the file while open for writing.
6024 Template: #DECL ("VALUE" <OR 'T <FALSE STRING FIX>>
6025 "TUPLE" <TUPLE <OR STRING CHANNEL>>)
6027 Tuple of arguments -- rename or delete action (see description)
6028 Returns -- whether it succeeded
6030 Example: <RENAME "FOO 3" TO "BAR">
6032 Rename FOO 3 to BAR >.
6033 <RENAME "FOO FOO DSK:HARRY;">
6037 REP: Enter a READ-EVAL-PRINT loop
6043 Reference: LISTEN, ERRET, RETRY
6045 REP causes an endless READ-EVAL-PRINT loop, which is left only by a
6046 non-local return. It is the last thing that LISTEN does, unless there
6047 is a substitute <VALUE REP>.
6051 Template: #DECL ("VALUE" ANY)
6053 Returns -- argument to ERRET
6058 REPEAT: Execute repeatedly sequential expressions.
6062 Category: PROGRAM-CONTROL
6064 Reference: PROG, RETURN, GO, AGAIN
6066 This FSUBR is used to bind varialbes and repeatedly and
6067 sequentially execute MUDDLE expressions and perform appropriate GOs,
6068 RETURNs, and AGAINs.
6069 If the first argument to REPEAT is an atom, it is bound to the
6070 Activation of the REPEAT.
6071 Otherwise the next object must be the argument list of the REPEAT.
6072 It contains either Atoms or Lists of an Atom and a MUDDLE expression.
6073 Each single Atom in the argument list is Bound but not Assigned. Each
6074 'listified' Atom is Bound and Assigned to the evaluation of the MUDDLE
6075 expression which appears with it.
6076 If the next argument to the REPEAT is of type DECL, it is used as
6077 the declaration for the variables of the REPEAT.
6078 The remaining arguments, at least one must exist, constitutes the
6079 body of the REPEAT. They are executed in sequence. When the last has
6080 been evaluated, evaluation begins again with the first expression in
6081 the body. Unless a RETURN or non-local AGAIN or GO is executed at
6082 some time by the body of the REPEAT, the REPEAT will never return.
6086 Template: #DECL ("VALUE" ANY "ARGS" <LIST ATOM LIST DECL ANY>)
6088 Optional argument 1 -- ATOM to which to bind the activation of the
6090 Argument 2 -- Parameter list of the REPEAT.
6091 Optional argument 3 -- DECL of the REPEAT.
6092 Tuple of arguments -- At least one evalable object.
6093 Returns -- the argument to a RETURN from the REPEAT's activation.
6095 Example: <REPEAT ((C ()))
6096 <COND (<N==? <1 <SET C (<RANDOM> !.C)>> 69>)
6097 (ELSE <RETURN .C>)>>
6098 This will create a LIST of random numbers until RANDOM returns 69.
6100 RESET: Reopen a channel at its beginning
6106 Reference: ACCESS, OPEN
6108 RESETting a channel means:
6109 for input, empty all buffers and ACCESS the file (if any) to 0;
6110 for output, return to beginning of file, destroying all output if not
6111 "PRINTO". If the channel is closed, it is first opened. RESET on
6112 either console channel causes the interpreter to update device specs.
6116 Template: #DECL ("VALUE" <OR CHANNEL <FALSE STRING STRING FIX>> CHANNEL)
6118 Argument 1 -- the channel to reset
6119 Returns -- arg1 or a false if reopen failed
6121 Example: <RESET ,INCHAN>
6122 after detaching and moving to a different console
6124 REST: Remove elements from the front of a structure
6128 Category: DATA-HANDLING
6130 Reference: BACK, TOP
6132 REST removes the first N elements from a structure, that is,
6133 moves N places down the structure. N defaults to 1 if not given.
6134 For some structures, the effect of REST may be undone with BACK.
6135 Note that the result of REST is always CHTYPEd to its PRIMTYPE,
6136 thus FORMs become LISTs when RESTed, and so on.
6140 Template: #DECL ("VALUE" STRUCTURED STRUCTURED "OPTIONAL" FIX)
6142 Argument 1 -- A Structured object.
6144 Argument 2 -- FIX, default 1.
6145 Returns -- The result is the structured object, CHTYPEd to its
6148 Example: <SET A <REST [1 2 3 4] 3>>
6158 <SET F <REST "XYZ">>
6161 The relationships between REST, BACK, and TOP are illustrated.
6162 Note that only REST can work on lists
6164 RESTORE: Restore a previously SAVEd core image
6168 Category: ENVIRONMENT
6170 Reference: SAVE, FSAVE
6172 RESTORE replaces the entire current MUDDLE environment with one
6173 from a file generated by SAVE. It is much faster than FLOAD for very
6174 large programs. RESTORE does not return; the SAVE that originally
6175 created the file returns again with the string "RESTORED" as its
6177 All arguments are optional with a default file name of
6179 DSK:<-user's sname>-;MUDDLE SAVE
6181 Note that RESTORE attempts to restore the state of all channels.
6182 If the SNAME of the MUDDLE doing the SAVE was "", the current
6183 SNAME will not be changed by the RESTORE. This feature is useful
6184 if a SAVE file is to be used by more than one person.
6188 Template: #DECL ("VALUE" STRING "OPTIONAL" STRING STRING STRING
6192 Arguments -- Up to four STRINGs specifying the file name to RESTORE.
6193 Returns -- The STRING "RESTORED".
6195 Example: <RESTORE "MUDDLE;NCOMP">
6196 Restore the compiler.
6198 RESUME: Resume running a PROCESS
6202 Category: PROCESS-CONTROL
6204 Reference: RESUMER, PROCESS
6206 RESUME starts a PROCESS running. It takes something to return
6207 as the 'value' of the current PROCESS, and the PROCESS to resume. If
6208 not given, the PROCESS to RESUME is defaulted to be the last PROCESS to
6209 RESUME the PROCESS doing the RESUME, if there was one.
6210 If the process that is doing the RESUME is ever itself RESUMEd,
6211 the first argument to that RESUME will be returned as its value. In
6212 fact, a PROCESS may be treated in the simpler cases as a routine called
6213 by invoking RESUME, which returns the result as RESUME's value.
6217 Template: #DECL ("VALUE" ANY ANY "OPTIONAL" PROCESS)
6219 Argument 1 -- Something to be returned to the resumed process.
6221 Argument 2 -- The PROCESS to resume, default <RESUMER> if there is one.
6222 Returns -- Whatever is passed to RESUME later in another PROCESS to
6225 Example: <COND (<RESUMER> <RESUME T <RESUMER>>)>
6226 Resumer our RESUMER, if we have one.
6228 RESUMER: Return the last PROCESS to RESUME a PROCESS
6232 Category: PROCESS-CONTROL
6236 RESUMER takes an optional process, and returns the last
6237 PROCESS to RESUME it. If not given, the PROCESS is <ME>. If no
6238 process has ever RESUMEd the process given, returns FALSE.
6242 Template: #DECL ("VALUE" <OR FALSE PROCESS> "OPTIONAL" PROCESS)
6245 Argument 1 -- A PROCESS, default <ME>.
6246 Returns -- A PROCESS, which last RESUMEd Arg 1, or FALSE if none ever
6249 Example: <PROG ((R <RESUMER>))
6250 <COND (<AND .R <==? <STATE .R> RESUMABLE>>
6252 RESUME RESUMER if o.k. to do so.
6254 RETRY: Retry a previous Subroutine call from the error level
6258 Category: ERROR, PROGRAM-CONTROL
6262 RETRY pops the stack down to a given frame and then causes the
6263 Subroutine call that generated that frame to be done again. It is
6264 mostly useful for restarting some program after fixing the cause of an
6269 Template: #DECL ("OPTIONAL" FRAME)
6272 Argument 1 -- the frame to be redone, default the last call to ERROR/LISTEN
6273 Returns -- really nothing
6275 Example: <RETRY <FRM 1>>
6276 Often you want to restart from just before the error.
6278 RETURN: Return something from an activation
6282 Category: PROGRAM-CONTROL
6284 Reference: ERRET, GO, RETRY
6286 RETURN takes a value and an ACTIVATION and returns the value
6287 from the ACTIVATION. The ACTIVATION is optional, and defaults to the
6288 most nearly surrounding ACTIVATION, usually that of the current PROG
6289 or REPEAT. The value is also optional, default T.
6290 The result of RETURN is that the ACTIVATION terminates and the
6291 value is returned as its 'result'.
6292 ACTIVATIONs may be implicit, as in they often are in PROGs and
6293 REPEATs, or explicit as in the optional first argument for PROG,
6294 REPEAT, FUNCTION, and second argument for DEFINE. In these cases the
6295 LVAL of the ATOM given is the ACTIVATION of that PROG, REPEAT, etc.
6296 See the Abstracts of these FSUBRs and the Abstract of AGAIN for more
6298 One final note. An ACTIVATION may be CHTYPEd to a FRAME and used
6299 by ERRET, RETRY and so on.
6300 The ACTIVATION argument to RETURN may literally be any legal
6301 activation in the MUDDLE, even one from another PROCESS.
6305 Template: #DECL ("VALUE" ANY "OPTIONAL" ANY ACTIVATION)
6308 Argument 1 -- the value to return from the activation, default T.
6309 Argument 2 -- the ACTIVATION to return the value from, default the
6310 most closely surrounding ACTIVATION, as of the current PROG
6311 or REPEAT that is running.
6312 Returns -- Argument 1 (from the ACTIVATION).
6314 Example: <REPEAT (X)
6315 <COND (<EMPTY? .X> <RETURN "DONE">)
6316 (ELSE <PRINT <1 .X>>)>
6318 Simple use of RETURN in a REPEAT.
6320 RGLOC: Get a locative to the GVAL of an ATOM for pure-program use
6324 Category: DATA-HANDLING
6326 Reference: LLOC, GLOC
6328 Returns a locative, type LOCR, to the GVAL of the ATOM passed
6329 as its argument. If the ATOM has no GVAL slot, ERROR, unless second
6330 arg is given and true. Pure RSUBRs must use this instead of GLOC.
6334 Template: #DECL ("VALUE" LOCR ATOM "OPTIONAL" <OR FALSE ANY>)
6336 Argument 1 -- An ATOM with a GVAL.
6338 Argument 2 -- whether not to give a no-slot error or not
6339 Returns -- A locative (LOCR) to the GVAL of the ATOM.
6341 Example: <AND <GASSIGNED? FOO> <RGLOC FOO>>
6342 Guard against ATOMs with no GVALs.
6344 ROOT: Return the ROOT oblist
6348 Category: IDENTIFIER
6350 ROOT returns the ROOT OBLIST. This OBLIST is almost always
6355 Template: #DECL ("VALUE" OBLIST)
6357 Returns -- The ROOT OBLIST.
6366 Category: BIT-TWIDDLING, LOGICAL
6370 ROT takes an object of Primtype WORD and a FIX, and it returns a
6371 WORD containing the bits in the first argument, rotated the number of
6372 bits specified by the second argument (mod 256). A positive second
6373 argument specifies rotation to the left, a negative FIX specifies
6374 rotating to the right. Rotation is a cyclic logical shift where bits
6375 shifted out at one end are put back in at the other.
6379 Template: #DECL ("VALUE" WORD
6380 <PRIMTYPE WORD> FIX)
6382 Arg 1 -- a Primtype WORD containing the bits to rotate
6383 Arg 2 -- a FIX specifying the amount to rotate
6384 Returns -- A WORD containing the rotated bits.
6387 #WORD *000000001000*
6389 #WORD *100000000000*
6390 Primarily useful for getting fingers directly in the bits.
6392 RSUBR-ENTRY: Create entry point to an RSUBR.
6396 Category: DATA-HANDLING
6398 Reference: RSUBR, ENTRY-LOC
6400 This routine will create an alternate entry point to an RSUBR.
6401 The ATOM supplied will be the name of this alternate entry point. The
6402 DECL will be used for argument and result checking at the new entry.
6403 The FIX is the offset into the actual code of the RSUBR of this entry.
6407 Template: #DECL ("VALUE" RSUBR-ENTRY
6408 <VECTOR <OR RSUBR ATOM> ATOM DECL> FIX)
6410 Argument 1 -- a vector containing the RSUBR (or its name) and the new
6411 entry's name and DECL
6412 Argument 2 -- a FIX, an offset in the RSUBR
6413 Returns -- an RSUBR-ENTRY into the RSUBR
6415 Example: <RSUBR-ENTRY [,FOO FOO1 #DECL ("VALUE" LIST STRING)]
6418 This will make a new entry point into the RSUBR FOO. This entry will
6419 have the name FOO1 and have a DECL as given. The offset into the CODE
6420 of FOO for this entry will be 245.
6422 RSUBR-LINK: Change state of automatic RSUBR linking feature
6426 Category: ENVIRONMENT
6430 RSUBR-LINK is used to enable and disable the automatic RSUBR
6431 linking feature of MUDDLE. Normally, as they are called, RSUBRs link
6432 up to each other. If RSUBRs are being debugged, this can be a problem
6433 as several different versions may be loaded and reloaded.
6434 Calling RSUBR-LINK with FALSE disables the feature, with non-FALSE
6435 enables it. It is normally enabled.
6439 Template: #DECL ("VALUE" <OR ANY FALSE>
6440 "OPTIONAL" <OR ANY FALSE>)
6443 Argument 1 -- FALSE disables automatic RSUBR linking, non-FALSE
6445 Returns -- The previous state, or the current state if no arg
6447 Example: <RSUBR-LINK <>>
6448 <GROUP-LOAD "FOO BINARY">
6453 RSUBR: Create an object of type RSUBR (Relocatable SUBR)
6457 Category: DATA-HANDLING
6459 RSUBR is a routine that is rarely if ever used other than in the
6460 MUDDLE Assembler. The user (almost) always sees the type RSUBR already
6462 RSUBR creates an object of RSUBR, which stands for Relocatable
6463 SUBR. RSUBRs are created in one of several ways. They can be created
6464 by hand-coding a routine and assembling it. They can be the result of
6465 the assembly of a compiled FUNCTION.
6466 Internally, an RSUBR consists of a code uvector, a name, a DECL,
6467 and (optionally) references, which are all the objects the
6468 RSUBR references outside of itself.
6472 Template: #DECL ("VALUE" RSUBR
6473 <VECTOR <OR CODE PCODE> ATOM DECL [REST ANY]>)
6475 Argument 1 -- A VECTOR containing the code (impure or pure), an ATOM (the
6476 name of the RSUBR), a DECL, and references.
6477 Returns -- The argument CHTYPEd to an RSUBR.
6479 Example: <RSUBR [#CODE ![1!] FOO #DECL ()]>
6480 Will create a useless RSUBR
6482 RUNINT: Apply interrupt handler (for internal use only)
6486 Category: SYSTEM, INTERRUPT
6490 RUNINT is just like APPLY, except that it is called internally to
6491 execute an interrupt handler. It may cause another PROCESS to run.
6495 Template: #DECL ("VALUE" ANY APPLICABLE "TUPLE" TUPLE)
6497 Argument 1 -- the handler to be applied
6498 Tuple of arguments -- its args, supplied by interrupt system
6499 Returns -- whatever handler returns
6501 Example: <RUNINT <3 .HANDLER> !.ARGS>
6502 Of course only the interpreter does this.
6504 RUNTIMER: Set time of Run-time interrupt
6510 Reference: REALTIMER
6512 RUNTIMER sets the amount of Run-time (in seconds) the MUDDLE
6513 must have used for a RUNT (run-time) interrupt to occur.
6517 Template: #DECL ("VALUE" <OR FIX FLOAT> <OR FIX FLOAT>)
6519 Argument 1 -- The amount of run-time (fix or float) the MUDDLE must
6520 have used for a RUNT (run-time) interrupt to occur.
6521 Returns -- Argument 1.
6523 Example: <RUNTIMER <* 60 60>>
6524 Cause interrupt after one hour time (seconds) used.
6526 SAVE: Saves the core image of a MUDDLE in a continuable state.
6532 Reference: FSAVE, RESTORE
6534 SAVE saves the impure part of a MUDDLE's core image in a file on
6535 the disk. This file can later be RESTOREd (q.v.) and whatever was in
6537 SAVE files are zero compressed, and normally a garbage collection
6538 is performed before the SAVE is done to further reduce the rather
6539 considerable size of the resulting file.
6540 SAVE takes the name of the file to SAVE into as its argument, and
6541 optionally, an argument which if given and FALSE, causes the garbage
6542 collect to not occur. The default name of the SAVE file is DSK:MUDDLE
6544 SAVE returns the string "SAVED". RESTORE, which 'returns again'
6545 from the SAVE, returns the string "RESTORED", and thus the caller can
6547 SAVE files are RESTOREable only into MUDDLEs with the same
6548 version number as the MUDDLE that SAVEd them. To check if a SAVE file
6549 is compatible with a MUDDLE, compare the version number with <READ> on
6550 a channel open to the SAVE file.
6554 Template: #DECL ("VALUE" '"SAVED" "TUPLE" TUPLE)
6556 (Tuple of arguments)
6557 First element(s) -- STRING(s) specifying the file to SAVE into.
6558 Last element (optional) -- An object, which, if FALSE, inhibits pre-SAVE garbage
6560 Returns -- the STRING "SAVED"
6563 Will save core image to DSK:<sname>;MUDDLE SAVE.
6565 SEND-WAIT: Send an IPC message and wait until someone takes it
6571 Reference: SEND, IPC-ON, IPC-OFF
6573 SEND-WAIT sends an IPC message to a specific destination from your
6574 MUDDLE, using the ITS IPC (Inter-process communication) feature. SEND
6575 takes 3, 4, or 6 arguments: Two string specifying whom to send the
6576 message to, a message, and optionally a message type number, and a
6577 pair of strings specifying whom the message is from.
6578 Using SEND-WAIT, it is possible to hang until someone takes the
6579 message. SEND returns T if someone takes the message, #FALSE()
6581 When your process receives an IPC message, the condition "IPC"
6582 is signalled. There is a default handler for this condition, called
6583 IPC-HANDLER. See its abstract for more details.
6587 Template: #DECL ("VALUE" 'T STRING STRING
6588 <OR STRING <UVECTOR [REST <PRIMTYPE WORD>]> STORAGE>
6589 "OPTIONAL" FIX STRING STRING)
6591 Arguments 1 & 2 -- STRINGs specifying the destination of the message.
6592 Any one who is listening on this pair will receive the message.
6593 They correspond to an ITS UNAME, JNAME pair.
6594 Argument 3 -- A message. This can be a STRING, a UVECTOR of UTYPE
6595 Primtype WORD, or a STORAGE.
6597 Argument 4 -- A message type. This is just an identifying type for
6598 the recipient to look at if he is interested.
6599 Arguments 5 & 6 -- Two STRINGs specifying whom the message is from. If
6600 not given, they are from UNAME JNAME of the MUDDLE.
6601 Returns -- T when the message is taken. Hangs until then.
6603 Example: <SEND-WAIT "CLR" "MUDDLE" "HOW ARE YOU CHRIS?">
6604 Will return T when CLR MUDDLE takes the IPC message.
6606 SEND: Send an IPC message
6612 Reference: SEND-WAIT, IPC-ON, IPC-OFF
6614 SEND sends an IPC message to a specific destination from your
6615 MUDDLE, using the ITS IPC (Inter-process communication) feature. SEND
6616 takes 3, 4, or 6 arguments: Two strings specifying whom to send the
6617 message to, a message, and optionally a message type number, and a
6618 pair of strings specifying whom the message is from.
6619 SEND returns T if someone takes the message, #FALSE() otherwise.
6620 Using SEND-WAIT, it is possible to hang until someone takes the message.
6621 When your process receives an IPC message, the condition "IPC"
6622 is signalled. There is a default handler for this condition, called
6623 IPC-HANDLER. See its abstract for more details.
6627 Template: #DECL ("VALUE" <OR 'T '#FALSE ()> STRING STRING
6628 <OR STRING <UVECTOR [REST <PRIMTYPE WORD>]> STORAGE>
6629 "OPTIONAL" FIX STRING STRING)
6631 Arguments 1 & 2 -- STRINGs specifying the destination of the message.
6632 Any one who is listening on this pair will receive the message.
6633 They correspond to an ITS UNAME, JNAME pair.
6634 Argument 3 -- A message. This can be a STRING, a UVECTOR of UTYPE
6635 Primtype WORD, or a STORAGE.
6637 Argument 4 -- A message type. This is just an identifying type for
6638 the recipient to look at if he is interested.
6639 Arguments 5 & 6 -- Two STRINGs specifying whom the message is from. If
6640 not given, they are from UNAME JNAME of the MUDDLE.
6641 Returns -- T if the message is taken, else #FALSE ().
6643 Example: <SEND "CLR" "MUDDLE" "HOW ARE YOU CHRIS?">
6644 Will return T only if CLR MUDDLE is listening for IPC messages.
6646 SET: Give an atom a local value
6650 Category: IDENTIFIER
6652 Reference: ASSIGNED?, LVAL
6654 SET gives an atom (arg1) a local value (arg2) in a given
6655 environment (arg3, optional).
6659 Template: #DECL ("VALUE" ANY ATOM ANY
6660 "OPTIONAL" <OR ENVIRONMENT
6665 Argument 1 -- the atom to set
6666 Argument 2 -- the local value to give it
6668 Argument 3 -- the environment for this to occur in
6671 Example: <SET REDEFINE T>
6672 allows redefinitions
6674 SETG: Assign a global value to an atom
6678 Category: IDENTIFIER
6680 Reference: GVAL, GASSIGNED?, DEFINE
6685 Template: #DECL ("VALUE" ANY ATOM ANY)
6687 Argument 1 -- the atom
6688 Argument 2 -- the global value to give it
6691 Example: <SETG REAL-PLUS ,+>
6692 often the first step in redefining primitives
6694 SETLOC: Change the object a locative points to
6698 Category: DATA-HANDLING
6700 Reference: IN, LEGAL?
6702 Change the object a locative points to. The advantage of SETLOC
6703 is that it is independent of exactly what is pointed to by the locative
6704 passed it. It works equally well for LVALs, GVALs, structures, and
6706 Note that it is possible to lose if an LVAL to which an LLOC
6707 points has become unbound. Use LEGAL? to check when in doubt.
6711 Template: #DECL ("VALUE" ANY LOCATIVE ANY)
6713 Argument 1 -- A locative.
6714 Argument 2 -- Anything, to be the new contents of the thing the
6716 Returns -- Argument 2.
6718 Example: <SET FOO (1 2 3)>
6719 <SET FOOL <AT .FOO 2>>
6722 <SETLOC .FOOL "BAR">
6725 Just like PUT, right?
6727 SIN: Sine of an angle
6731 Category: ARITHMETIC
6733 Reference: COS, ATAN
6738 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
6740 Argument 1 -- the angle in radians.
6741 Returns -- A FLOAT, the Sine.
6743 Example: <+ <* <COS .X> <COS .X>>
6744 <* <SIN .X> <SIN .X>>>
6746 One of the common trig. identities.
6748 SLEEP: Sleep interruptably for a given number of seconds
6752 Category: ENVIRONMENT, INTERRUPT
6756 SLEEP allows a process to sleep (using the system call) for
6757 a given period of time. It is also possible to give an object to be
6758 evaluated each time an interrupt occurs and is dismissed back into
6759 the SLEEP. If the result of the evaluation is non-FALSE, the result
6760 is returned as the value of the SLEEP. This enables a switch to be
6761 set at interrupt level and looked at to terminate a SLEEP.
6765 Template: #DECL ("VALUE" ANY <OR FIX FLOAT> "OPTIONAL" ANY)
6767 Argument 1 -- the number of seconds to SLEEP.
6769 Argument 2 -- Something to evaluate each time an interrupt dismisses
6770 back into the SLEEP, and terminates the SLEEP if it returns
6772 Returns -- The non-FALSE result of the second argument.
6774 Example: <SLEEP 60 .TYPEIN>
6776 Sleep for a minute but stop early if an interrupt handler sets the
6777 ATOM to a non-FALSE.
6779 SNAME: Read or change MUDDLE's SNAME
6785 Reads or changes MUDDLE's SNAME, which is the default name for
6786 opening files. If no arguments are given, returns the current SNAME.
6787 If a STRING is given, it is made the current SNAME and returned.
6788 The ATOM SNM may also be set, locally or globally, to change
6789 (temporarily or permanently) the default SNAME of the MUDDLE.
6793 Template: #DECL ("VALUE" STRING "OPTIONAL" STRING)
6796 Argument 1 -- A STRING to set the SNAME to. If none is given, just
6797 read the current SNAME.
6798 Returns -- The current SNAME.
6800 Example: <SNAME "FOO">
6806 SORT: Sort VECTORs, UVECTORs, or TUPLEs
6810 Category: DATA-HANDLING
6812 SORT is used to order VECTORs, UVECTORs, and TUPLEs. It is a
6813 fairly complex SUBR, which however has good defaults and is fairly
6814 easy to use with them.
6815 It works most efficiently if the sort keys are of primtype WORD,
6816 ATOM, or STRING. However, the keys may be of any type, and SORT will
6817 still work. SORT acts on records which consist of one or more contig-
6818 uous entries in the structure being sorted. One item in the record is
6819 declared to be the sort key. Also, any number of additional structures
6820 may be rearranged based on how the main structure is sorted.
6822 <SORT function ; either FALSE or something applicable
6823 ; to two sort keys which returns FALSE
6824 ; if the first is not bigger than the
6825 ; second. I.e, arg1 > arg2 ??
6827 s1 ; the structure to sort
6829 l1 ; length of sort records in s1, default 1
6831 offset ; REST offset from start of record of
6832 ; sort key. Optional, default 0.
6834 s2 l2 - sN lN> ; the VECTORs, UVECTORs, or TUPLEs to
6835 ; rearrange, and record lengths in them
6837 If the function is FALSE, then the types of all the sort keys
6838 must be the same, and they must be of primtype WORD, ATOM, or STRING.
6839 In this case a Radix Exchange Sort is used (stolen from TECO). If
6840 function is something applicable, a Shell Sort is used.
6841 Note that if you give your own 'function' it is possible to make
6842 a non-terminating sort. If the condition you create by your function
6843 does not map into the normal one 'return FALSE if first not bigger than
6844 second' then the SORT may not terminate.
6845 See 'Example' section for several examples of the use of SORT.
6849 Template: #DECL ("VALUE" <PRIMTYPE <OR VECTOR UVECTOR TUPLE>>
6850 <OR FALSE APPLICABLE> <PRIMTYPE <OR VECTOR UVECTOR TUPLE>>
6851 "OPTIONAL" FIX FIX "TUPLE"
6853 <PRIMTYPE <OR VECTOR UVECTOR TUPLE>>
6856 Argument 1 -- The Sorting routine, or FALSE if the internal one is to
6857 be used. Remember internal one only works if keys are WORD,
6858 ATOM, STRING primtypes.
6859 Argument 2 -- The PRIMTYPE VECTOR, UVECTOR, or TUPLE to sort.
6861 Argument 3 -- FIX giving the record size in the
6862 structure given for argument 2. Defaults to 1 if not
6864 Argument 4 -- The REST offset of the sort key in the records of the main
6865 structure. Default is 0.
6866 Tuple of arguments -- Alternating structures and respective record sizes.
6867 These records are permuted the same way as the sorted ones in
6869 Returns -- the sorted arg 1
6871 Example: <SET A <IUVECTOR 500 '<RANDOM>>>
6874 This is the simplest use of SORT. Note that only one argument is
6875 really given, the FALSE simply defaulting the sorting method to the
6888 This sorts the vector based on the atom names, considering records
6889 to be two elements and defaulting the offset to 0. If the offset had
6890 been 1 would sort based on the numbers.
6891 <SORT <FUNCTION (X Y)
6893 [(101 "FOOBAR") (17 "MUMBLE") (86 "BLECH") (34 "GRITCH")]
6910 This sorts two structures based on the first element of the main
6911 structure. Note that records in the second structure are 3 elements
6914 SPECIAL-CHECK: Change or examine the state of interpreter SPECIAL checking
6918 Category: ENVIRONMENT
6920 Reference: SPECIAL-MODE, DECL-CHECK
6922 SPECIAL-CHECK turns interpreter SPECIAL checking on or off,
6923 returning the old state, or, if given no argument, returns the current
6924 state. (T indicates special checking is on, #FALSE() off).
6928 Template: #DECL ("VALUE" <OR 'T FALSE>
6929 "OPTIONAL" <OR ANY FALSE>)
6931 (Optional arguments)
6932 Argument 1 -- A FALSE or T, indicating which state special checking is
6933 to be put in. If not given, just return current state.
6934 Returns -- The state of special-checking when SPECIAL-CHECK was called.
6936 Example: <SPECIAL-CHECK <>>
6937 This sets the normal initial state -- no special checking.
6939 SPECIAL-MODE: Change or examine the default Special Mode
6943 Category: ENVIRONMENT
6945 Reference: SPECIAL-CHECK
6947 SPECIAL-MODE is used to change or examine the default special
6948 mode. It takes as argument the atoms SPECIAL or UNSPECIAL, and sets
6949 the default mode accordingly, returning the old mode. If no argument
6950 is given, it just returns the old mode.
6954 Template: #DECL ("VALUE" <OR 'SPECIAL 'UNSPECIAL>
6955 "OPTIONAL" <OR 'SPECIAL 'UNSPECIAL>)
6957 (Optional arguments)
6958 Argument 1 -- SPECIAL or UNSPECIAL, the new mode.
6959 Returns -- The mode at the time of the call.
6961 Example: <SPECIAL-MODE UNSPECIAL>
6962 Set the initial state.
6964 SPNAME: Create a shared STRING which is the name of an ATOM
6968 Category: IDENTIFIER
6970 Reference: ATOM, INSERT, PNAME
6972 SPNAME takes as argument an ATOM, and returns the STRING which
6973 is the PNAME (printing name) of that ATOM. This name does not include
6974 any oblist trailers or the backslashes that are sometimes printed out
6975 for the convenience of the reader. Several other SUBRs, notably
6976 INSERT, LOOKUP, and ATOM, use the pname of atoms as arguments.
6977 PRINC of the PNAME of an ATOM is one guaranteed way of printing
6978 an ATOM-name without trailers, backslashes, or quotes.
6979 SPNAME is more efficient than PNAME (q.v.) if the string will not
6980 be modified. Any attempt to PUT into the string will cause an error.
6984 Template: #DECL ("VALUE" STRING ATOM)
6986 Argument 1 -- An ATOM.
6987 Returns -- A STRING which shares the atom's pname.
6989 Example: <SPNAME \ \ \ !-FOO!-BAR>
6991 Just three spaces, no backslashes, no trailers.
6993 SQRT: Square root of a number
6997 Category: ARITHMETIC
7004 Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
7006 Argument 1 -- A FIX or FLOAT.
7007 Returns -- FLOAT, the square root of argument 1.
7011 Floating is always done.
7013 SQUOTA: Get the address of an internal interpreter symbol (for internal use only)
7014 "VALUE" <OR FIX FALSE>
7017 STACKFORM: Apply a function to generated arguments. [OBSOLETE]
7019 ******* This FSUBR is obsolete as of MUD54 *******
7023 Category: DATA-HANDLING
7025 STACKFORM is obsolete and replaced by a MAPF of only two arguments.
7026 It is documented for historical reasons only. The compiler transforms
7027 applications of STACKFORM into appropriate MAPFs.
7029 The STACKFORM Fsubr was used to APPLY a function to a variable
7030 number of generated arguments. This could also be done by constructing
7031 the appropriate Form and EVALing it. STACKFORM is more efficient; it
7032 builds the Form on the stack and therefore produces no garbage. This
7033 is where STACKFORM obtains its name.
7034 STACKFORM operates as follows:
7035 (0) EVALuate the 1st arg, and save as the applicative object.
7036 (1) EVALuate the 3rd arg, the boolean expression.
7037 (2) If the 3rd arg EVALuated to an object not of Type FALSE
7038 Then, EVALuate the 2nd arg, the argument expression
7039 and save on the stack. GO TO (1)
7040 Else APPLY the saved applicative object
7041 to the stacked arguments and return the result.
7045 Template: #DECL ("VALUE" ANY "ARGS" <LIST APPLICABLE ANY ANY>)
7047 Arguments -- see Description.
7048 Returns -- see Description.
7050 Example: <STACKFORM ,STRING
7052 <NOT <==? <NEXTCHR> <ASCII 27>>>>
7054 This reads characters from the current input channel until an alt-mode
7055 is read. It then returns what was read as one String.
7057 STATE: Return the state of a PROCESS
7061 Category: PROCESS-CONTROL
7063 STATE returns the state of a PROCESS, as an ATOM from the
7066 a) RUNNABLE -- PROCESS has never been run.
7067 b) RUNNING -- running now (ie: applied STATE).
7068 c) RESUMABLE -- has run and may run again.
7069 d) DEAD -- has run and may not run again.
7073 Template: #DECL ("VALUE" ATOM PROCESS)
7075 Argument 1 -- A PROCESS whose state should be returned.
7076 Returns -- The state of the PROCESS
7078 Example: <STATE <ME>>
7080 This should always be the case.
7082 STORE: Create a non-garbage collected storage area [OBSOLETE]
7084 ******* This SUBR is obsolete as of MUD55 *******
7088 Category: DATA-HANDLING
7090 Reference: ISTORAGE, FREE
7092 STORE creates non-g.c. storage (for E&S etc.). It looks just like
7093 a uvector, but does not move during garbage collection. It takes as
7094 argument a UVECTOR whose contents will be copied into the STORAGE.
7098 Template: #DECL ("VALUE" STORAGE UVECTOR)
7100 Argument 1 -- UVECTOR, desired contents of the store.
7101 Returns -- STORAGE, containing old contents of the UVECTOR.
7104 <SET A <STORE ![1 2 3!]>>
7105 (.A <1 .A> <FREE .A>)>
7106 Notice that once the space is free'd it should not be accessed
7108 STRCOMP: Compare two STRINGs
7112 Category: PREDICATE, CHARACTER
7116 STRCOMP alphabetically compares two STRINGs or ATOMs. It
7117 actually is not a predicate, since it can return one of three values:
7118 0 if the first string is =? to the second,
7119 1 if the first is greater (sorts alphabetically after the
7121 and -1 if the second is greater.
7123 If STRCOMP is given ATOMs, it of course uses their pnames to
7126 Alphabetically means, in this case, according to the numeric
7127 order of ASCII, which gives the standard alphabetizing rules.
7131 Template: #DECL ("VALUE" FIX <OR ATOM STRING> <OR ATOM STRING>)
7133 Argument 1 -- STRING or ATOM
7134 Argument 2 -- STRING or ATOM
7135 Returns -- 0 if argument 1 is =? to argument 2.
7136 1 if argument 1 is greater than argument 2.
7137 -1 if argument 1 is less than argument 2.
7139 Example: <STRCOMP "FOO" "BAR">
7141 <G? <STRCOMP "FOO" "BAR"> 0>
7143 Converts STRCOMP into a predicate suitable for SORT.
7145 STRING: Create a STRING from CHARACTERs and STRINGs
7149 Category: DATA-HANDLING
7153 STRING creates a string with explicit elements. These must be
7154 other STRINGs or CHARACTERs. They will be concatenated together to
7159 Template: #DECL ("VALUE" STRING
7160 "TUPLE" <TUPLE [REST <OR STRING CHARACTER>]>)
7162 Tuple of arguments -- STRINGs or CHARACTERs, the elements of the new
7164 Returns -- Newly created STRING.
7166 Example: <STRING "This is " !\a " string">
7169 STRUCTURED?: Is an object structured?
7173 Category: TYPE, PREDICATE
7175 Reference: TYPE?, LOCATIVE?, APPLICABLE?
7177 STRUCTURED? tests if an object is one of the group of types
7178 known as structured objects. It is similar to applying TYPE? to
7179 the object and the list of structured objects, but relieves the user
7180 from knowing the list, and thus will work for any new structured types
7182 A structured object is defined as an object which potentially may
7183 have NTH applied to it.
7187 Template: #DECL ("VALUE" <OR FALSE 'T> ANY)
7189 Argument 1 -- Any MUDDLE object.
7190 Returns -- T if argument 1 is structured, or FALSE if it is not.
7192 Example: <STRUCTURED? <ROOT>>
7194 Lots of types are structured.
7196 SUBSTITUTE: Substitute one type-value pair for another throughout MUDDLE
7200 Category: DATA-HANDLING
7204 SUBSTITUTE causes one type-value pair to be substituted for
7205 another throughout MUDDLE. It is not to be used unless you really
7206 know what you are doing. In fact, one of the few legitimate uses for
7207 it (other than just having fun by doing <SUBSTITUTE 2 1>) is to
7208 substitute the 'right' atom for the 'wrong' one, where OBLISTs have
7209 gotten in a bad state.
7213 Template: #DECL ("VALUE" ANY ANY ANY)
7215 Argument 1 -- Object to be substituted.
7216 Argument 2 -- Object to be substituted for.
7217 Returns -- Argument 2.
7219 Example: <SUBSTITUTE FOO!-BAR FOO>
7221 Only reasonable use so far found. ATOM impurification is done this
7224 SUBSTRUC: Copy part of a structure into another
7228 Category: DATA-HANDLING
7230 SUBSTRUC facilitates the construction of structures that are
7231 composed of sub-parts of existing structures. It copies a set of
7232 contiguous elements of one (non-TEMPLATE) structure into the first
7233 elements of another, old or new, structure, all in one swell foop.
7237 Template: #DECL ("VALUE" <OR LIST VECTOR UVECTOR STRING BYTES>
7245 <OR LIST VECTOR UVECTOR STRING BYTES>)
7247 Argument 1 -- object to copy out of
7249 Argument 2 -- amount to REST arg1 (temporarily) before copying, default 0
7250 Argument 3 -- number of elements to copy, default all
7251 Argument 4 -- object to copy into, TYPE must be <PRIMTYPE arg1> (VECTOR
7252 if arg1 is TUPLE), must not share with arg1 if LIST
7253 Returns -- new object (doesn't share with arg1, VECTOR if arg1 is TUPLE)
7256 Example: <SUBSTRUC '(1 2 3) 0 2>
7259 <SUBSTRUC "SUM OF PARTS" 7 4 <ISTRING 4>>
7263 SUICIDE: Kill the PROCESS you are in and resume another
7267 Category: PROCESS-CONTROL
7269 Reference: PROCESS, RESUME, DEAD
7271 SUICIDE is exactly like RESUME, except that the PROCESS it is
7272 EVALed in is made DEAD after it is left, and thus cannot be RESUMEd
7274 Note that <MAIN> cannot be SUICIDEd.
7278 Template: #DECL ("VALUE" ANY ANY "OPTIONAL" PROCESS)
7280 Argument 1 -- The value of the process doing the SUICIDE.
7282 Argument 2 -- A PROCESS to RESUME, default <RESUMER>, if there is one.
7283 Returns -- Nothing really, as the PROCESS SUICIDEd cannot be RESUMEd,
7284 since it will be dead.
7286 Example: <SUICIDE T>
7287 Won't work if <ME> is <MAIN>
7289 TAG: Create a tag within an activation
7293 Category: PROGRAM-CONTROL
7297 TAG creates a tag for a non-local GO. GO with a tag argument
7298 allows returning to the middle of any PROG or REPEAT still active.
7302 Template: #DECL ("VALUE" TAG ATOM)
7304 Argument 1 -- a legal argument for local GOs
7305 Returns -- a TAG for non-local GOs
7312 <LOWER .BAR <TAG LABEL>>
7314 See how easy it is to make confusing programs?
7316 TERPRI: Print a carriage-return and line-feed
7327 Template: #DECL ("VALUE" '#FALSE () "OPTIONAL" CHANNEL)
7330 Argument 1 -- the channel, default .OUTCHAN
7331 Returns -- #FALSE ()
7335 Terminate printing on this line.
7337 TIME: Return the Run time of the MUDDLE
7341 Category: UTILITY, SYSTEM
7343 TIME returns a FLOAT giving the run time of the MUDDLE in
7345 TIME takes any number of optional arguments, however, and is thus
7346 often used to pass arguments for examination at a DDT break point.
7350 Template: #DECL ("VALUE" FLOAT "TUPLE" <TUPLE [REST ANY]>)
7353 Tuple of arguments -- ANY objects.
7354 Returns -- FLOAT, the run time of the MUDDLE in seconds.
7360 TOP: Replace elements of a structure removed by REST
7364 Category: DATA-HANDLING
7366 Reference: BACK, REST
7368 TOP replaces all items removed from a non-list structure by
7369 RESTing. For PRIMTYPE VECTORs, UVECTORs, STRINGs, and TEMPLATEs, TOP
7370 returns the object passed after having returned the pointer to the top
7371 of the object and changed the type to the PRIMTYPE. Since list
7372 structures have no back pointers, it is impossible to either BACK them
7377 Template: #DECL ("VALUE" <OR VECTOR UVECTOR STRING TEMPLATE>
7378 <PRIMTYPE <OR VECTOR UVECTOR STRING TEMPLATE>>)
7380 Argument 1 -- A structured object that can be BACKed (VECTOR, UVECTOR,
7381 STRING, or TEMPLATE.
7382 Returns -- The object with the RESTed elements (if any) returned and
7383 changed to its PRIMTYPE.
7385 Example: <==? <TOP <REST <SET X "FOOBARBLECH"> 6>>
7388 This will return T, as the same object is always there, just with a
7389 different pointer into it.
7391 TTYECHO: Turn TTY echoing for a CHANNEL on and off
7399 TTYECHO takes a channel and a FALSE or non-FALSE, ands sets
7400 the TTY echoing for that channel to 'off' if FALSE, 'on' if non-FALSE.
7401 This is useful in conjunction with the SUBR TYI (qv) for applic-
7402 ations where TTY echoing is not straight character at a time.
7403 ERROR and LISTEN automatically do <TTYECHO .INCHAN T> when they
7408 Template: #DECL ("VALUE" CHANNEL CHANNEL <OR ANY FALSE>)
7410 Argument 1 -- A TTY CHANNEL.
7411 Argument 2 -- non-FALSE to turn on echoing, FALSE to turn it off.
7412 Returns -- The channel.
7414 Example: <TTYECHO .INCHAN T>
7415 ERROR and LISTEN do this automatically.
7417 TUPLE: Create a TUPLE with explicit elements
7421 Category: DATA-HANDLING
7425 TUPLE creates a tuple (vector on the stack) with explicit
7426 elements. TUPLE can only be invoked at top level of an atom-value
7427 pair in a parameter list, such as AUX or OPTIONALs, or the top binding
7428 pairs of PROG or REPEAT.
7429 Note that a TUPLE cannot be returned past the FRAME in which it
7434 Template: #DECL ("VALUE" TUPLE "TUPLE" TUPLE)
7436 Tuple of arguments -- ANY, the elements of the TUPLE.
7437 Returns -- Newly stacked TUPLE.
7439 Example: <PROG ((X <TUPLE 1 2 3 4>)) <+ !.X>>
7440 This is a legitimate, if trivial, use of TUPLE.
7441 <PROG ((X <REST <TUPLE 1 2 3 4>>))
7444 This use of TUPLE is both trivial and illegal: it is not at top level
7445 of the atom-value pair.
7447 TYI: Read a single character as it is typed on the TTY
7455 TYI is used to read characters from the TTY as they are typed
7456 rather than after an alt-mode is typed, as is the case with READCHR
7457 and READ. It may be used in conjunction with TTYECHO by programs
7458 that wish to do their own reading and echoing.
7462 Template: #DECL ("VALUE" CHARACTER "OPTIONAL" CHANNEL)
7464 Argument 1 -- A TTY channel on which to read a character, default .INCHAN.
7465 Returns -- The character read.
7467 Example: <TTYECHO .INCHAN <>>
7469 <PRINC <CHTYPE <+ 32 <CHTYPE <TYI .INCHAN> FIX>> CHARACTER>
7471 Turn echoing off and echo characters read as their value plus 40.
7473 TYPE-C: Get a type code for pure-program use
7477 Category: TYPE-DEFINITION
7479 Reference: NEWTYPE, TYPE-W
7484 Template: #DECL ("VALUE" TYPE-C ATOM "OPTIONAL" ATOM)
7486 Argument 1 -- the newtype to get a code for
7488 Argument 2 -- its primtype, as a check
7489 Returns -- a type code
7491 Example: <TYPE-C MYLIST LIST>
7492 makes or gets a type code for my newtype
7494 TYPE-W: Get a type word for pure RSUBR use
7498 Category: TYPE-DEFINITION
7500 Reference: NEWTYPE, TYPE-C
7505 Template: #DECL ("VALUE" TYPE-W ATOM "OPTIONAL"
7506 ATOM <PRIMTYPE WORD>)
7508 Argument 1 -- name of newtype
7510 Argument 2 -- primtype thereof, as a check
7511 Argument 3 -- right half to include in result
7512 Returns -- a type word
7514 Example: <TYPE-W MYLIST LIST 69>
7515 a type word for NEWTYPE MYLIST
7517 TYPE: Return the type of an object
7523 Reference: UTYPE, TYPE?, PRIMTYPE, TYPEPRIM
7525 TYPE is applied to any MUDDLE object to return an ATOM which is
7526 the name of the type of that object. PRIMTYPE, which is similar,
7527 returns the primitive type of the object given. TYPEPRIM returns the
7528 primitive type given the name of the type.
7532 Template: #DECL ("VALUE" ATOM ANY)
7534 Argument 1 -- Any MUDDLE object.
7535 Returns -- ATOM, the name of the type of the argument.
7537 Example: <TYPE TYPE>
7539 <TYPE "Comments on example">
7542 TYPE?, which checks to see if its argument is one of a series of
7543 types, is often used instead of TYPE in conditionals.
7545 TYPE?: Is an object one of a group of types?
7549 Category: PREDICATE, TYPE
7553 TYPE? takes as arguments an object and at least one type name.
7554 If the object is one of the types given, that type is returned. If it
7555 is not, returns FALSE. TYPE? is essentially the same as MEMQing the
7556 TYPE of the object in a list of types, but is syntactically clearer
7557 and better understood by the compiler.
7561 Template: #DECL ("VALUE" <OR FALSE ATOM> ANY "TUPLE"
7562 <TUPLE ATOM [REST ATOM]>)
7564 Argument 1 -- Any MUDDLE object.
7565 Tuple of arguments -- Any number (at least one, though) type names.
7566 Returns -- The type if it is in the tuple, or FALSE if it is not.
7568 Example: <TYPE? 1 FIX FLOAT WORD>
7570 Will take any number of type names.
7572 TYPEPRIM: Return the primitive type of a type
7578 Reference: UTYPE, TYPE?, PRIMTYPE, TYPE
7580 TYPEPRIM returns the primitive type given the name of the type
7581 of a MUDDLE object. It is thus different from PRIMTYPE, which takes
7586 Template: #DECL ("VALUE" ATOM ATOM)
7588 Argument 1 -- An ATOM which is the name of a type.
7589 Returns -- ATOM, the name of the primitive type of the argument.
7597 Illustrates difference between PRIMTYPE and TYPEPRIM.
7599 UNAME: Return the User-name of the MUDDLE
7605 Returns the UNAME, or login-name of the MUDDLE. This is the
7606 name under which the person running the MUDDLE logged in. It is also
7607 one of the names of the MUDDLE job.
7611 Template: #DECL ("VALUE" STRING)
7613 Returns -- A STRING giving the UNAME of the job.
7616 Only possible example.
7618 UNASSIGN: Removes the local value of an ATOM
7622 Category: IDENTIFIER
7624 Reference: LVAL, ASSIGNED?
7626 UNASSIGN removes the local value of an ATOM. After an ATOM
7627 has been UNASSIGNED, LVAL of it will cause an error, and ASSIGNED?
7628 of it will return FALSE.
7632 Template: #DECL ("VALUE" ATOM ATOM "OPTIONAL"
7633 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
7635 Argument 1 -- The ATOM to flush the LVAL of.
7637 Argument 2 -- the environment of the LVAL
7638 Returns -- The ATOM you just UNASSIGNed.
7640 Example: <UNASSIGN SNM>
7642 if it's giving you trouble
7644 UNMANIFEST: Declare the global value of an ATOM to no longer be a constant
7648 Category: DATA-HANDLING
7650 Reference: MANIFEST, MANIFEST?, GDECL
7652 UNMANIFEST declares that the current global value of an ATOM is
7653 no longer a constant. Generally a ATOM passed to UNMANIFEST will have
7654 previously been passed to MANIFEST.
7655 UNMANIFEST is generally used to remove the restriction on changing
7656 an MANIFEST variable so that it CAN be changed.
7660 Template: #DECL ("VALUE" 'T "TUPLE" <TUPLE [REST ATOM]>)
7662 Tuple of arguments -- ATOMs whose GVALs are no longer constants.
7671 Most common use of UNMANIFEST.
7673 UNPARSE: Recreate the STRING representation of a MUDDLE object
7677 Category: DATA-HANDLING
7679 Reference: PARSE, LPARSE
7681 UNPARSE create a string representation of a MUDDLE object, just
7682 like printing into a string instead of a channel.
7686 Template: #DECL ("VALUE" STRING ANY "OPTIONAL" FIX)
7688 Argument 1 -- ANY, object to be 'printed' into a string.
7690 Argument 2 -- radix for FIX conversion, default ten
7691 Returns -- A STRING, the unparsed object.
7693 Example: <PARSE <UNPARSE (1 2 3 4)>>
7694 This is one way of creating a non-shared copy of a structure.
7698 Category: PROGRAM-CONTROL
7700 UNWIND is an FSUBR that takes two forms. It EVALs the first
7701 one, and, if the EVAL returns normally, the value of that EVAL is the
7702 value of UNWIND. If, however, during the EVAL a non-local return
7703 attempts to return beyond the UNWIND in the stack, then the second
7704 form is EVALed, its value is ignored, and the non-local return is
7705 completed. The second form is evaluated in the environment that was
7706 present when the call to UNWIND was made.
7707 This facility is useful for cleaning up data bases that are in
7708 inconsistent states and closing temporary channels that may be left
7709 around. FLOAD sets up an UNWIND to close its CHANNEL if the user
7710 attempts to ERRET without finishing the FLOAD.
7714 Template: #DECL ("VALUE" ANY "ARGS" <LIST ANY ANY>)
7716 Argument 1 -- A form to be EVALed.
7717 Argument 2 -- A form to EVAL if a non-local return beyond the UNWIND
7719 Returns -- The result of EVALing argument 1 (only local return that
7722 Example: <DEFINE FOO ACT ("AUX" (C
7725 <UNWIND <PROG () "...&..."> <CLOSE .C>>>
7727 Channel C will be closed if the PROG returns non-locally, as from
7730 UTYPE: Return the Uniform type of a UVECTOR
7736 Reference: UVECTOR, CHUTYPE
7738 UTYPE returns the name of the uniform type of a UVECTOR. This
7739 is the type of all objects in the UVECTOR. It may be changed by using
7740 CHUTYPE (within limits).
7744 Template: #DECL ("VALUE" ATOM <PRIMTYPE UVECTOR>)
7746 Argument 1 -- A UVECTOR
7747 Returns -- An ATOM, which is the name of the UVECTOR's uniform type.
7749 Example: <UTYPE ![1 2 3 4!]>
7751 Allows you to get the utype without accessing any individual element.
7753 UVECTOR: Create a UVECTOR with explicit elements
7757 Category: DATA-HANDLING
7761 UVECTOR creates a uvector with explicit elements. Note that all
7762 of these elements must be of the same type, else ERROR. UVECTOR is
7763 different from an explicit usage of excl-[, because in such usage all
7764 the elements must be the same when read in -- they are already a
7765 UVECTOR before evaluation.
7769 Template: #DECL ("VALUE" UVECTOR "TUPLE" <TUPLE [REST ANY]>)
7771 Tuple of arguments -- ANY, the elements must all be of same type, and
7772 can't be strings, LOCDs, or on the stack.
7773 Returns -- A new UVECTOR.
7775 Example: <UVECTOR 1 2 3>
7776 Equivalent to ![1 2 3]
7777 <UVECTOR 1 .FOO .BAR>
7778 Not equivalent to ![1 .FOO .BAR!], which is illegal
7780 VALID-TYPE?: Is an ATOM the name of a type?
7784 Category: TYPE-DEFINITION, PREDICATE
7788 VALID-TYPE? returns #FALSE () if its argument is not the name of a
7789 TYPE, and TYPE-C of its argument if it is. It is much more efficient
7790 than <MEMQ .arg <ALLTYPES>> .
7794 Template: #DECL ("VALUE" <OR TYPE-C FALSE> ATOM)
7796 Argument 1 -- an ATOM that might be the name of a TYPE
7797 Returns -- whether or not it really is
7799 Example: <VALID-TYPE? FOO>
7801 <NEWTYPE FOO CHARACTER>
7804 now returns %<TYPE-C FOO CHARACTER>
7806 VALRET: Returns a string to MUDDLE's superior
7810 Category: ENVIRONMENT
7812 Reference: LOGOUT, QUIT
7814 VALRET returns a string to the MUDDLE's superior. This is
7815 usually only useful if the superior is a MONIT or DDT (which are the
7816 two normal superiors on ITS). VALRET's can be used to execute
7817 commands in DDT and then return to MUDDLE, but because they are
7818 limited to use on ITS, it is untasteful to use VALRET where other
7819 means would suffice.
7823 Template: #DECL ("VALUE" ANY STRING)
7825 Argument 1 -- A STRING to return to MUDDLE's superior.
7828 Example: <VALRET "
\17..SENDRP/-1
7833 This example is a VALRET string that will cause DDT to stop printout
7834 of unsolicited messages.
7836 VALUE: Return the local or else the global value of an atom
7840 Category: IDENTIFIER
7842 Reference: LVAL, GVAL
7844 If its argument has a local value (in a given environment),
7845 VALUE returns the value; else, if it has a global value, returns that;
7850 Template: #DECL ("VALUE" ANY ATOM "OPTIONAL"
7851 <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
7853 Argument 1 -- the atom whose value to get
7855 Argument 2 -- the environment to look for a local value in
7856 Returns -- local or else global value
7858 Example: <VALUE SNM>
7859 default disk directory for I/O
7861 VECTOR: Create a VECTOR with explicit elements
7865 Category: DATA-HANDLING
7869 VECTOR creates a vector with explicit elements. It is the
7870 same as enclosing the arguments to VECTOR in [ and ].
7874 Template: #DECL ("VALUE" VECTOR "TUPLE" <TUPLE [REST ANY]>)
7876 Tuple of arguments -- ANY, the elements
7877 Returns -- A new VECTOR.
7879 Example: <VECTOR 1 2 3>
7880 equivalent to [1 2 3]
7882 XORB: Bitwise logical Exclusive OR
7886 Category: ARITHMETIC
7888 Reference: EQVB, ORB, ANDB
7890 XORB takes any number of objects of Primtype WORD, and returns
7891 a WORD containing the bitwise logical exclusive OR of the arguments.
7895 Template: #DECL ("VALUE" WORD
7896 "TUPLE" <TUPLE [REST <PRIMTYPE WORD>]>)
7898 Tuple of arguments -- Objects of primtype WORD to be XORed together.
7899 Returns -- A WORD containing the bitwise XOR of the arguments.
7901 Example: <XORB #WORD *000000000001*
7902 #WORD *000000000001*
7903 #WORD *000000042263*>
7904 #WORD *000000042263*
7905 Primarily useful for getting fingers directly in the bits.
projects / pdp10-muddle.git / blob