From: Lars Brinkhoff Date: Thu, 15 Nov 2018 06:34:54 +0000 (+0100) Subject: ITS Muddle 54 documentation, from TOPS-20 directory. X-Git-Url: https://jxself.org/git/?p=pdp10-muddle.git;a=commitdiff_plain;h=adde408b9f5795c5a2892fe9e031f7ff0d221c08 ITS Muddle 54 documentation, from TOPS-20 directory. --- diff --git a//muddle.order.1 b//muddle.order.1 new file mode 100644 index 0000000..ab93ba0 --- /dev/null +++ b//muddle.order.1 @@ -0,0 +1,7906 @@ +MUDDLE F/SUBRS: (for MUDDLE 55) PDL/SWG 3/8/79 + + The following is a very brief description of all the +primitives currently available in MDL. These descriptions are in +no way to be considered a definition of the effects or values +produced by the primitives. They just try to be as complete and +as accurate as is possible in a single-statement description. +However, because of the complexity of most primitives, many +important defaults and restrictions have been omitted. + +*: Multiplication of fixes and floats. + +Object-type: SUBR + +Category: ARITHMETIC + + * (Multiply) takes any number of FIXes or FLOATs, and multiplies +them together, returning the result. If any of the arguments are +FLOATs, the result will be FLOAT. If no argument is given, * returns +1, if one argument is given, * returns that argument. + * will given an arithmetic overflow error (unless disabled by OVERFLOW) +if the word size of the PDP-10 is exceeded. + +Argument: + + Template: #DECL ("VALUE" + "TUPLE" ]>) + +(Optional) +Tuple of arguments -- FIXes and FLOATs +Returns -- FIX or FLOAT, floating is contagious. + +Example: <* 1 2.0> + 2.0 +Floating is contagious. + ++: Add fixes and floats. + +Object-type: SUBR + +Category: ARITHMETIC + + + adds together any number of FIXes or FLOATs, returning the +result. Floating is contagious, as in all arithmetic SUBRs. If no +argument is given, + returns 0, if one argument, + returns the argument. + + will give an arithmetic overflow error (unless disabled by +OVERFLOW) if the result (or an intermediate result) exceeds the word +size of the PDP-10. + +Argument: + + Template: #DECL ("VALUE" + "TUPLE" ]>) + +(Optional) +Tuple of arguments -- FIXes and FLOATs. +Returns -- FIX or FLOAT, sum of arguments. + +Example: <+ !> + 6 +Sum of elements of list. + +-: Subtract fixes and floats. + +Object-type: SUBR + +Category: ARITHMETIC + + - takes any number of fixes or floats and subtracts from the first +one all of the remaining ones. If no argument is given, returns 0. If +one argument is given, returns its negation. Floating is contagious, +and - will give an arithmetic overflow error (unless disabled by OVERFLOW) +if the word size of the PDP-10 is exceeded. + +Argument: + + Template: #DECL ("VALUE" + "TUPLE" ]>) + +(Optional) +Tuple of arguments -- FIXes and FLOATs. +Returns -- The FIX or FLOAT result of the subtraction. + +Example: <- 5 3 2> + 0 +All but first argument are subtracted from first. + +/: Divide fixes and floats. + +Object-type: SUBR + +Category: ARITHMETIC + + / divides any number of fixes and floats. The first is divided +successively by each of the remaining arguments. If no arguments are +given, returns 1. If one argument is given, returns its reciprocal. +Floating is contagious. If the arguments are FIX, the result is +always completely fixed point division, with no rounding. +/ will give an arithmetic overflow error (unless disabled by OVERFLOW) +if the word size of the PDP-10 is exceeded. + +Argument: + + Template: #DECL ("VALUE" + "TUPLE" ]>) + +(Optional) +Tuple of arguments -- FIXes and FLOATs +Returns -- FIX or FLOAT quotient. + +Example: + 0.5 +First division gave 1, then .5 after second. + +0?: Tests if a fix or float is zero. + +Object-type: SUBR + +Category: ARITHMETIC + + 0? tests a FIX or FLOAT to see if it is equal to zero. If it is +not, a FALSE is returned. If it is, T is returned. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- A FIX or FLOAT. +Returns -- FALSE if not equal to 0, T if equal to zero. + +Example: <0? 1> + #FALSE () +Trivial, isn't it? + +1?: Tests if a fix or float is equal to one. + +Object-type: SUBR + +Category: ARITHMETIC + + 1? takes a fix or float and tests its equality to one. If it is +not equal, returns FALSE. If it is equal, returns T. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- FIX or FLOAT to test. +Returns -- FALSE if not 1, T if 1. + +Example: <1? 1.0> + T +Works for floats, too. + +1STEP: Put a PROCESS in One-step mode + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: RESUME, FREE-RUN + + 1STEP puts a PROCESS in single step mode. It takes as argument +a PROCESS. When RESUMEd, the PROCESS will be in one-step mode, running +until an EVAL is either entered or left. + The PROCESS which executed the 1STEP will then be RESUMEd. It +will be passed a tuple. If EVAL was being entered, the tuple will +contain the ATOM EVLIN and the arguments to EVAL. If EVAL was being +left, the tuple will contain the ATOM EVLOUT and the result of the +evaluation. + The PROCESS will remain in 1STEP mode until FREE-RUN is done on +it. RESUME will thus stop at each EVAL until then. + +Argument: + + Template: #DECL ("VALUE" PROCESS PROCESS) + +Argument 1 -- A PROCESS to put in one-step mode. +Returns -- The PROCESS. + +Example: <1STEP .FOO> +returns #PROCESS i + + [EVLIN <+ 1 1>] + + [EVLOUT 2] +Two successive steps of the process. + +==?: Test for physical identity of two objects. + +Object-type: SUBR + +Category: PREDICATE + +Reference: =? + + ==? tests two objects for physical identity. For ==? to return +T (true), the two objects must have the same identical type-value pair. +For example, two STRINGs typed in from the console will not be ==?, but +two ATOMS, FIXes, or nil LISTs will be. + If the two objects are not the same, ==? returns FALSE. + +Argument: + + Template: #DECL ("VALUE" ANY ANY) + +Argument 1 -- Any object. +Argument 2 -- Another object. +Returns -- T if the two objects are the same, FALSE otherwise. + +Example: <==? "FOO" "FOO"> + #FALSE () +These two STRINGs look identical, but are not. + +=?: Test for structural identity of two objects. + +Object-type: SUBR + +Category: PREDICATE + +Reference: ==? + + =? is a less stringent, but more expensive, test for identity +than ==?. It also takes two objects as arguments, but tests only for +structural identity of the objects, rather than physical identity. If +two objects print the same, they will be =? to each other, except for +numeric fuzz. For example, two STRINGs typed in from the console will +be =? to each other, but not ==?. Any objects that are ==? will also +be =?, and if ==? applies, it should be used. =? is much more +expensive than ==?, in general, as it must test an entire structure +piece by piece. + =? returns T if the objects are structurally identical, and FALSE if +they are not. + +Argument: + + Template: #DECL ("VALUE" ANY ANY) + +Argument 1 -- Any object. +Argument 2 -- Any other object. +Returns -- T if the arguments are structurally equal, FALSE if they + are not. + +Example: <=? > > + T +If the test were ==?, the result would be FALSE. + +ABS: Returns the Absolute value of a FIX or FLOAT. + +Object-type: SUBR + +Category: ARITHMETIC + + Returns the absolute value of its argument. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- A FIX or FLOAT to take the absolute value of. +Returns -- A FIX or FLOAT guaranteed non-negative. + +Example: + 69105 +Simple SUBR, simple example. + +ACCESS: Position channel to given point in file + +Object-type: SUBR + +Category: I/O + +Reference: FILE-LENGTH + + ACCESS makes the next character or binary word (depending on +the channel's mode) which will be input from or output to a channel +the (arg2+1)st one from the beginning of the file. + +Argument: + + Template: #DECL ("VALUE" CHANNEL CHANNEL FIX) + +Argument 1 -- the channel, open (not in "PRINT" mode) to DSK, USR, etc. +Argument 2 -- where to point for next i/o +Returns -- the channel + +Example: +starts reading again from beginning of file + +ACTIVATE-CHARS: Set or inspect interrupt characters for console typing (TENEX only) +"VALUE" STRING +"OPTIONAL" STRING + +AGAIN: Restart a FUNCTION, PROG, or REPEAT + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: FUNCTION, PROG, REPEAT + + AGAIN takes one argument: an ACTIVATION. It means 'start doing +this again', where 'this' is specified by the ACTIVATION. Specifically, +AGAIN causes EVAL to return to where it started working on the body of +the FUNCTION, REPEAT, or PROG in the application specified by the +ACTIVATION. The application is not re-evaluated completely: no +rebinding of variables is done. + In a PROG or REPEAT, where there is always a defined ACTIVATION, +AGAIN with no arguments defaults to AGAIN of the top-level ACTIVATION +in the PROG or REPEAT. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ACTIVATION) + +(Optional) +Argument 1 -- The ACTIVATION to restart. If not given, that of the + immediately surrounding PROG or REPEAT is used. +Returns -- Nothing, restarts the ACTIVATION. + +Example: 10>>)) + 100> + > + ) + (ELSE >)>> + +How many elements must be rested off before total of rest is less +than fifty? This could just as easily be a REPEAT, where the AGAIN is +implicit. + +ALLTYPES: Return the MUDDLE type VECTOR + +Object-type: SUBR + +Category: TYPE-MANIPULATION + + ALLTYPES returns the user a pointer to the MUDDLE type vector. +Note that this is the real, honest-to-God type vector and that if you +clobber it you will clobber your MUDDLE, probably beyond repair. + The type vector contains ATOMs whose names are the types that are +currently defined to exist in the MUDDLE in which the ALLTYPES was +executed. + +Argument: + + Template: #DECL ("VALUE" ) + +Returns -- The MUDDLE type VECTOR. + +Example: +Only possible example. + +AND: Logical AND of its arguments. + +Object-type: FSUBR + +Category: PREDICATE, PROGRAM-CONTROL + +Reference: COND, OR, AND? + + AND is an FSUBR that evaluates its arguments, one by one, until +either one of them returns a FALSE or it runs out of arguments. + The fact that it is an FSUBR means that it can be used as a +miniature COND. A construct of the form will +allow 'thing' to be executed only if 'preconditions' is true. In com- +bination with OR, fairly powerful constructs can be generated. + AND takes any number of arguments, returning either the result of +its last evaluation (T if no arguments were given) or the FALSE that +caused it to complete. + +Argument: + + Template: #DECL ("VALUE" "ARGS" LIST) + +List of unevaluated arguments -- ANY evalable objects. +Returns -- Terminating FALSE or terminating non-FALSE. + +Example: .X> + +This construct attempts to take LVAL of X only if X is assigned, thus +avoiding the possibility of an ERROR. + +AND?: Logical AND of its arguments, evaluated at call time + +Object-type: SUBR + +Category: PREDICATE, PROGRAM-CONTROL + +Reference: OR?, AND, MAPF, MAPR + + AND? is a SUBR that looks at its arguments, one by one, until +either one of them is a FALSE or it runs out of arguments. + The fact that it is a SUBR means that it can be used as a +first argument to MAPF or MAPR. + AND takes any number of arguments, returning either +its last argument (T if no arguments were given) or the FALSE that +caused it to complete. + +Argument: + + Template: #DECL ("VALUE" "TUPLE" TUPLE) + +Tuple of evaluated arguments -- ANY objects. +Returns -- Terminating FALSE or terminating non-FALSE. + +Example: > .VECTOR> +Are all elements of this vector positive? + +ANDB: Bitwise logical AND + +Object-type: SUBR + +Category: BIT-TWIDDLING, LOGICAL + +Reference: EQVB, ORB, XORB + + ANDB takes any number of objects of Primtype WORD, and returns +a WORD containing the bitwise logical AND of the arguments. + +Argument: + + Template: #DECL ("VALUE" WORD + "TUPLE" ]>) + +Tuple of arguments -- Objects of primtype WORD to be ANDed together. +Returns -- A WORD containing the bitwise AND of the arguments. + +Example: + #WORD *000000000337* +Primarily useful for getting fingers directly in the bits. + +APPLICABLE?: APPLICABLE? tests if its argument may be APPLYed. + +Object-type: SUBR + +Category: PREDICATE + + APPLICABLE? takes a single object as argument, and returns T if +that argument may be APPLYed. That is, it may be the first element of +a FORM. Thus, an object of type FIX is applicable, as well as the more +obvious SUBR, FSUBR, RSUBR, FUNCTION, and so on. + If its argument is not applicable, returns FALSE. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Argument 1 -- ANY object to be tested for applicability. +Returns -- T if applicable, #FALSE() if not. + +Example: + T +NTH makes this the case. + +APPLY: Apply the first arg to the rest of them. + +Object-type: SUBR + +Category: PROGRAM-CONTROL + + The first argument is applied to the rest of the arguments. + The manner in which the application is accomplished, is determined +by the TYPE of the first arg as follows: + +FIX: call ,NTH with the 2nd arg and 1st arg. + +SUBR: call the Subr with the rest of the args. + +RSUBR or RSUBR-ENTRY: call the Rsubr with the rest of the args and + also compare them with the Rsubr's DECLs. + +FUNCTION: Bind the Atoms in the parameter list of the Function + to the rest of the args of the APPLY matching one-to-one. Then + Bind the unsatisfied OPTIONALs, if any, and the EXTRAs to the + EVAL of their defaults. As each of the above Bindings is done, + the DECL for that variable is also checked. Now the elements of + the body of the Function are EVALed sequentially. + The result of the evaluation of the last element of the body + is the result of the Function application. It is checked against + the VALUE DECL of the Function, and returned. + +CLOSURE: First Bind the Closure variables to their indicated + values. Then APPLY the Function part of the Closure as above. + +Others: ERROR NON-APPLICABLE-TYPE + +The manner in which the application is done for a particular Type can +be changed through the use of the subr APPLYTYPE. + +Argument: + + Template: #DECL ("VALUE" ANY APPLICABLE "TUPLE" + ) + +Argument 1 -- The object to apply to the rest of the arguments. +Tuple of arguments -- The arguments the first argument is to be + applied to. +Returns -- The result of applying the first argument to the rest. + +Example: ANALYSIS-ROUTINE> .ITEM> + +This code will call a routine to process ITEM. The routine called +depends solely on the TYPE of ITEM. Therefore this represents the +idea of a dispatch table. + +APPLYTYPE: Change or examine the way a TYPE is APPLYed + +Object-type: SUBR + +Category: TYPE-MANIPULATION, PROGRAM-CONTROL + +Reference: APPLY, EVALTYPE + + Changes the way a specific type is APPLYed, by either mapping +it into another type, or giving an explicit method via an APPLICABLE. + If a type is given, the type being changed will be APPLYed in the +same manner as that type. + If an APPLICABLE is given, it should take at least one argument, +which will be the object being APPLYed, and the rest of the arguments +will be what it is being APPLYed to. Whatever the APPLICABLE returns +will be the result of the APPLICATION. If ,APPLY is given, the type +will hereafter receive no special treatment in application to args. + If no second arg is given, APPLYTYPE returns the last second arg +given for this type, or #FALSE () if the type is receiving no special +treatment in application. + +Argument: + + Template: #DECL ("VALUE" ATOM "OPTIONAL" + ) + +Argument 1 -- The type whose APPLYTYPE to change or examine. +(Optional) +Argument 2 -- A TYPE (which means 'Apply like this type'), or an + APPLICABLE (meaning 'use this when you APPLY this type'). +Returns -- The TYPE which was changed or, if no second arg, the special + treatment this TYPE is receiving, if any. + +Example: ) + ( FIX> + >>) + ()>>>> +Make application of a LIST be like NTH + <(1 2 3 (4 5 6)) 4 2> + 5 + +ARGS: Return the argument Tuple of an environment + +Object-type: SUBR + +Category: UTILITY, PROGRAM-CONTROL + +Reference: FRAME, FUNCT, LEGAL? + + Takes an environment and returns the argument TUPLE of the +top-level FRAME in that environment. The argument must be LEGAL? for +it to work. + Note that the argument Tuple returned will become illegal once +the stack is popped past it. + +Argument: + + Template: #DECL ("VALUE" TUPLE + ) + +Argument 1 -- The environment whose args tuple we want. +Returns -- The argument Tuple of the top FRAME in the environment we passed as arg 1. + +Example: <* 3 <+ a 1>> +Gives an ERROR, first arg wrong type. + >> + [a 1] +The arguments of the frame that caused the ERROR. + +ASCII: Convert Ascii codes to characters and back + +Object-type: SUBR + +Category: DATA-HANDLING + + ASCII returns a CHARACTER given its 'ASCII' code (as a FIX) +or returns the ASCII code given the CHARACTER. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- A CHARACTER or FIX to be transformed into the other. +Returns -- The opposite type to its argument. + +Example: + +The first returns the character A, +the second *101*. + +ASSIGNED?: Is an Atom locally assigned ? + +Object-type: SUBR + +Category: PREDICATE, IDENTIFIER + +Reference: BOUND? + + This routine is used to test if a particular Atom is locally +assigned, or in other words if it has a local value, in a given +environment, default the current one. It does cause the activation of +any read monitors on that local value. + It returns T if the ATOM has a local value, #FALSE () otherwise. + +Argument: + + Template: #DECL ("VALUE" ATOM "OPTIONAL" + ) + +Argument 1 -- An ATOM to test. +(Optional) +Argument 2 -- the environment in which to make the test +Returns -- T if the ATOM has a local value, #FALSE () otherwise. + +Example: + +This will return the Atom T, since FOO does have a local value. + + +This will return #FALSE (), since the Atom FOO has no local value. + > +This will also return #FALSE (), since FOO still does not have a local value + +ASSOCIATIONS: Access the Association chain. + +Object-type: SUBR + +Category: ASSOCIATION + +Reference: NEXT, AVALUE, INDICATOR, ITEM + + ASSOCIATIONS gives the user access to the association chain in +much the same way as FRAME gives access to the stack. ASSOCIATIONS +returns the first association triad (item, indicator, value) in the +chain, as a type ASOC, which looks, but doesn't behave like, a LIST. + An ASOC may be passed to ITEM, INDICATOR, or AVALUE to retrieve +the elements of a triad, or to NEXT to retrieve the next association +in the chain. + +Argument: + + Template: #DECL ("VALUE" ) + +Returns -- The first association in the association chain, FALSE if none exist. + +Example: +Only possible example. + +AT: Get a locative to a position in a Structure + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: IN, SETLOC + + Returns a locative to a position in a Structure (a VECTOR, LIST, +UVECTOR, STRING, etc.). + Takes a structure, and an optional FIX (default 1), like NTH or +REST, returning the locative. + +Argument: + + Template: #DECL ("VALUE" LOCATIVE STRUCTURED "OPTIONAL" FIX) + +Argument 1 -- A Structured object. +(Optional) +Argument 2 -- A FIX, default 1, the position in the structure. +Returns -- A Locative to the position in the structure. + +Example: + > +Get locative + +Change structure + .FOO + (1 2 5) +Changed + +ATAN: Arc-tangent of a tangent + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: SIN, COS + + Returns, in Radians, the angle whose tangent is the argument. +Note that all useful trig. functions may be derived using ATAN, COS, +and SIN. + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- The tangent of some angle. +Returns -- The angle whose tangent is argument 1. + +Example: >> +Will equal .FOO + +ATOM: Create an ATOM not on any OBLIST + +Object-type: SUBR + +Category: DATA-HANDLING, IDENTIFIER + + ATOM creates the ATOM with PNAME its argument (a STRING). The +resulting ATOM is not on any OBLIST, and thus has trailer !-#FALSE(). + +Argument: + + Template: #DECL ("VALUE" ATOM STRING) + +Argument 1 -- The string which is the pname of the atom. +Returns -- The newly created ATOM. +Example: +FOO!-#FALSE() -- New ATOM not on any oblist. + +AVALUE: Return the value part of an Association triad + +Object-type: SUBR + +Category: ASSOCIATION + +Reference: ASSOCIATIONS, NEXT, ITEM, INDICATOR, + GETPROP, GET + + Given an ASOC, as returned by ASSOCIATIONS or NEXT, returns the +value part of the ASOC triad. + This is equivalent to but uses the ASOC +instead of the item and indicator. + +Argument: + + Template: #DECL ("VALUE" ANY ASOC) + +Argument 1 -- An ASOC whose value field to get. +Returns -- The value field of the ASOC. + +Example: + > + BLECH + + BLECH +If this association is the most recent one made, the last two are equivalent. + +BACK: Replace items RESTed off of a structure + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: REST + + BACK replaces some items removed from a non-list stucture by +RESTing, that is, it moves the pointer to the structure back up the +structure. + It takes two arguments, the structure, and a fix which specifies +how many elements to return, and defaults to 1. An ERROR is generated +if there are not that many elements RESTed off the structure. + +Argument: + + Template: #DECL ("VALUE" + > "OPTIONAL" + FIX) + +Argument 1 -- The structure to return elements to. +(Optional) +Argument 2 -- Number of elements to return, default is 1. +Returns -- The structure with the elements returned. + +Example: > + [D E] + + [C D E] +.X, of course, is not changed by the BACK. + +BIND: Execute sequential expressions without providing default activation + +Object-type: FSUBR + +Category: PROGRAM-CONTROL + +Reference: PROG, RETURN, AGAIN + + This FSUBR is identical to PROG (q.v.), except that it +does not bind LPROG\ !-INTERRUPTS, and therefore RETURNs and AGAINs will +not default to it. This could prove useful to MACRO writers. + +Argument: + + Template: #DECL ("VALUE" ANY "ARGS" ) + +Optional argument 1 -- An ATOM, to bind the activation of the BIND to. +Argument 2 -- A parameter LIST. +Optional argument 3 -- The DECL of the BIND. +Remainder of arguments -- At least one object, to be sequentially evaled. +Returns -- The last thing evaled in the BIND, or the argument to a + RETURN within the BIND. + +Example: )) + )>> +This will FOO only if the file FOO BAR exists. + +BITS: Create a byte pointer. + +Object-type: SUBR + +Category: BIT-TWIDDLING + +Reference: GETBITS, PUTBITS + + BITS creates a byte pointer to a word. It takes two arguments, +the second optional. The first is the width of the byte in bits, the +second the right edge of the byte (counting from the least significant +bit of the word), which defaults to 0, meaning the rightmost bit. + A BITS is used with GETBITS and PUTBITS to get and put bytes from +objects of primtype WORD. + +Argument: + + Template: #DECL ("VALUE" BITS FIX "OPTIONAL" FIX) + +Argument 1 -- A FIX specifying the size of the byte pointed at. +(Optional) +Argument 2 -- A FIX specifying the right edge of the byte, default 0. +Returns -- A BITS, which may be used with GETBITS and PUTBITS to work + with bytes of actual machine words. + +Example: +Points to a full PDP-10 word + +Points to third Ascii character position in word + +BLOAT-STAT: Get internal storage statistics + +Object-type: SUBR + +Category: UTILITY + +Reference: BLOAT + + BLOAT-STAT fills its argument uvector with information about +the state of storage. The first 8 elements tell the number of GCs +attributable to various causes; the other 19 tell the sizes of various +areas of storage. For details see the manual, SYS.11.01. + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" ) + +(Optional) +Argument 1 -- a uvector of length 27 at least +Returns -- arg1 or a gratis uvector of storage statistics + +Example: +If no arg, a uvector is provided gratis. + +BLOAT: Temporarily grow the garbage collected space. + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: GC + + BLOAT provides a mechanism for temporary growth of the MUDDLE +garbage collected space as well as various stacks and special data +structures. + BLOAT takes from 0 to 15 arguments all of type FIX. The args are +described below in the Argument template field of this abstract. + Note that unless more than seven arguments are given, BLOAT will +not necessarily make any permanent change in the amount of space in +a MUDDLE -- the new space allocated may go away in the next following +GC if it is not filled. + BLOAT always returns the current number of free words. + +Argument: + + Template: #DECL ("VALUE" FIX "OPTIONAL" FIX FIX FIX FIX FIX FIX FIX FIX FIX + FIX FIX FIX FIX FIX FIX) + +(Optional) +Argument 1 -- Free space desired. +Argument 2 -- Main stack space desired. +Argument 3 -- Top level local slots desired. +Argument 4 -- Global value slots desired. +Argument 5 -- New type slots desired. +Argument 6 -- Non garbage collected words needed (STORAGE). +Argument 7 -- Auxiliary stack space desired (only useful for reading + large strings). +Argument 8 -- Minimum space to get in all future GCs. +Argument 9 -- top-level local slots to add on future expansions +Argument 10 -- global-value slots to add on future expansions +Argument 11 -- type slots to add on future expansions +Argument 12 -- words of STORAGE to add on future expansions +Argument 13 -- words reserved for pure storage, if possible +Argument 14 -- most desirable size for auxiliary stack +Argument 15 -- most desirable size for main (control) stack + +Example: +Get lots of free and stack space. + +BLOCK: Change the current OBLIST path. + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: ENDBLOCK + + BLOCK changes the current OBLIST path by pushing the binding +of the ATOM OBLIST, and rebinding it to the arg of BLOCK. + BLOCK takes as argument a LIST of OBLISTs, of which one is in +most cases the ROOT OBLIST. An application of ENDBLOCK will return +the path to its previous state. + +Argument: + + Template: #DECL ("VALUE" ]>> + ]>>) + +Argument 1 -- The new LIST of OBLISTs to become the new path. +Returns -- Its argument. + +Example: > 23> + )> + +This is approximately what happens when the function RPACKAGE is +invoked. It creates a new path containing the internal oblist of the +RPACKAGE plus the ROOT. + +BOUND?: Is an Atom locally bound ? + +Object-type: SUBR + +Category: PREDICATE, IDENTIFIER + +Reference: ASSIGNED? + + This routine is used to test if a particular Atom is locally +bound, or in other words if it either has a local value or else has a +local binding which has not yet been assigned, in a given environment, +default the current one. It does cause the activation of any read +monitors on that local binding. + It returns T if the ATOM is locally bound, #FALSE() otherwise. + +Argument: + + Template: #DECL ("VALUE" ATOM "OPTIONAL" + ) + +Argument 1 -- An ATOM which may or may not have a local binding. +(Optional) +Argument 2 -- the environment in which to perform the test +Returns -- T if the ATOM has a local binding, #FALSE() otherwise. + +Example: + +This will return the Atom T, since FOO does have a local binding. + + +This will return #FALSE (), since the Atom FOO has no local binding. + > + +However this will also return the Atom T, since FOO does have a local +binding. + +BREAK-SEQ: Stack an object for another PROCESS to EVAL when it is RESUMEd + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: RESUME + + Takes an object and a PROCESS, and stacks the object in the PROCESS +such that when RESUMEd, the PROCESS will EVAL it before doing what it +would normally do. It thus 'breaks' the evaluation sequence in the +other PROCESS. Objects are stacked in the new process, and thus the +last BREAK-SEQed will be the first EVALed. + +Argument: + + Template: #DECL ("VALUE" PROCESS ANY PROCESS) + +Argument 1 -- The object to be stacked. +Argument 2 -- The PROCESS to stack it in. +Returns -- The PROCESS in which the object was stacked. + +Example: > +Give the PROCESS that resumed me something to do. + +BUFOUT: Force out a channel's write buffer + +Object-type: SUBR + +Category: I/O + +Reference: OPEN, CLOSE, RESET + + BUFOUT forces the buffers of a print channel out. It is used +primarily as insurance against system crashes and other acts of God, +to assure that all of the data created by a process will be output. + It takes and returns a CHANNEL. + +Argument: + + Template: #DECL ("VALUE" CHANNEL "OPTIONAL" CHANNEL) + +(Optional arguments) +Argument 1 -- A print CHANNEL to force buffers from. +Returns -- The CHANNEL. + +Example: +Flush buffers from OUTCHAN. + +BYTE-SIZE: Return the size of bytes of a BYTES + +Object-type: SUBR + +Category: TYPE + +Reference: BYTES, IBYTES + + BYTE-SIZE returns the size of all the bytes of a BYTES. This +is the number of bits in all FIXes in the BYTES. + +Argument: + + Template: #DECL ("VALUE" FIX ) + +Argument 1 -- A BYTES +Returns -- A FIX, which is the size of bytes of the BYTES. + +Example: + 2 + +BYTES: Create a BYTES from FIXes + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: IBYTES + + BYTES creates a byte-string with explicit elements. These must be +PRIMTYPE WORDs. They will be ANDBed with the appropriate mask and +concatenated together to form a new BYTES. + +Argument: + + Template: #DECL ("VALUE" BYTES FIX "TUPLE" ]>) + +Argument 1 -- the number of bits in each byte +Tuple of arguments -- PRIMTYPE WORDs, the elements of the new BYTES +Returns -- Newly created BYTES + +Example: + #2 {0 1 2 3 0 1 2}] + +CHANLIST: Get list of all open channels. + +Object-type: SUBR + +Category: I/O, UTILITY + + Creates and returns a list of all OPEN channels in a MUDDLE. +The first and second elements of this list are usually the TTY input +and output channels of the MUDDLE. + +Argument: + + Template: #DECL ("VALUE" ) + +Returns -- A LIST of all the CHANNELs currently open in a MUDDLE. + +Example: +Only possible example + +CHANNEL: Create a CHANNEL. + +Object-type: SUBR + +Category: I/O + +Reference: OPEN + + This SUBR is similar to OPEN, except that it only goes as far as +creating the channel that OPEN would go on to OPEN. Its advantage +is that the CHANNEL returned can be RESET just as though it had once +been open. + It takes the identical arguments as OPEN but does not open the +CHANNEL. For greater detail, see the Abstract of OPEN. + +Argument: + + Template: #DECL ("VALUE" CHANNEL "OPTIONAL" STRING + "TUPLE" TUPLE) + +(Optional) +Argument 1 -- A STRING giving the direction and type of OPEN to not do. +Argument 2 -- STRINGs and/or FIXes giving the specification of the + file to not OPEN. +Returns -- An unOPENed CHANNEL. + +Example: +Return an unopened PRINT channel. + +CHTYPE: Change the type of a MUDDLE object. + +Object-type: SUBR + +Category: TYPE-MANIPULATION + + Changes the type of a MUDDLE object (or, more exactly, a given +type-value pair). The allowable changes are among types of the same +PRIMTYPE. For example, WORDs may be CHTYPEd to FIXes, but VECTORs may +not be CHTYPEd to LISTs. CHTYPE does not affect any other pointers to +the object that may exist. + Some objects which have the same primtype may not be CHTYPEd to +each other, for example, a VECTOR may not be CHTYPEd to a CHANNEL. +This is because some types (like CHANNEL) are controlled and may be +created only in special ways. + Takes as arguments the object to be CHTYPEd, and an ATOM giving +the name of the type to CHTYPE it to. + +Argument: + + Template: #DECL ("VALUE" ANY ANY ATOM) + +Argument 1 -- Any (or almost any) object. +Argument 2 -- An ATOM which is the name of a type. +Returns -- Argument 1 with its type changed to type argument 2. + +Example: + (+ 1 2) +Create a LIST + + <+ 1 2> +Returns a FORM + .X + (+ 1 2) +But the original is untouched + +CHUTYPE: Change the uniform type of a UVECTOR + +Object-type: SUBR + +Category: TYPE-MANIPULATION + +Reference: UTYPE? + + CHUTYPE changes the uniform type (UTYPE) of a UVECTOR. The +types to which the UTYPE may be changed are restricted in the same way +as the changes allowed by CHTYPE are restricted. Thus a UVECTOR of +UTYPE LIST cannot be changed to one of UTYPE VECTOR, but one of UTYPE +FORM may be changed to one of UTYPE LIST. A UTYPE of LOSE may be +CHUTYPEd to anything that a UVECTOR may legally contain. + +Argument: + + Template: #DECL ("VALUE" + ATOM) + +Argument 1 -- A UVECTOR whose UTYPE wants to be changed. +Argument 2 -- An ATOM whose name is the name of the type to change the + UTYPE of the UVECTOR to. +Returns -- The UVECTOR with a new UTYPE. + +Example: + + ![<> <> <> <> <>!] +New UTYPE. + .X + ![<> <> <> <> <>!] +Note all references to UVECTOR get new UTYPE. + +CLOSE: Close an I/O channel + +Object-type: SUBR + +Category: I/O + +Reference: OPEN, BUFOUT, RESET + + CLOSE takes as argument a CHANNEL, and causes it to be closed. +Its buffers are written out if it is a PRINT channel. The channel +may be reopened using RESET, for many types of devices. + The CHANNEL closed is returned. + +Argument: + + Template: #DECL ("VALUE" CHANNEL CHANNEL) + +Argument 1 -- A CHANNEL to close. +Returns -- The closed CHANNEL. + +Example: >> + +This pointless form will cause a CHANNEL to be opened (assuming the +file exists), closed, and then reopened. + +CLOSURE: Bind the free variables of a Function to current values + +Object-type: SUBR + +Category: TYPE-MANIPULATION + + The CLOSURE Subr creates an object of Type CLOSURE. A CLOSURE +can be applied like a FUNCTION, the only difference being that first +the Atoms given in the call to the CLOSURE subr are bound to the values +thay had when the CLOSURE was generated. Then the Function is applied +as normal in this new environment. + A CLOSURE is a poor man's FUNARG. + +Argument: + + Template: #DECL ("VALUE" CLOSURE FUNCTION "TUPLE" + ) + +Argument 1 -- A FUNCTION which will be the application part of the + CLOSURE. +Tuple of arguments -- ATOMs whose current values are to be stored as + the binding part of the CLOSURE. +Returns -- A CLOSURE. + +Example: >> + INC> + +This will create a Closure which can later be applied to an Atom. +When applied it will then increment the local value of that Atom. +The amount of the increment is determined by the current value of INC. +Note that any future changes to the value of INC will not affect +the amount of the increment peformed by the Closure. + +COND: CONDitional evaluation on the basis of a predicate + +Object-type: FSUBR + +Category: PREDICATE, PROGRAM-CONTROL + +Reference: AND, OR + + COND is an FSUBR used to control evaluation on the basis of a +number of predicates. It takes any non-zero number of arguments, each +of which is a list of a least one element. + For each list, starting with the first, the first element of the +list is evaluated, and if its result is non-false, the rest of the +elements of that list are evaluated and the last thing returned by +one of them is returned as the value of the COND (this will be the +predicate itself if it is the only object in the list. + If the predicate returns a FALSE, then COND moves on to the next +list, or, if there are no more lists, the last FALSE returned is the +value of the COND. + +Argument: + + Template: #DECL ("VALUE" ANY "ARGS" ) + +Tuple of arguments -- At least one list, of which the first element + is the 'IF', and the rest the 'THEN'. +Returns -- The result of the last EVAL under its control. + +Example: > + + )> + +A common use of COND is to fend off the possibility of lossage by +setting up a screen of conditions. Note that if the file is not +opened, the reason will be returned (the last FALSE). + +CONS: Add an item to the front of a LIST + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LIST + + CONS adds an item to the front of a list, without copying it. +It is equivalent to making a list of the new item and the old list +segment evaled: + + (.FOO !.THE-LIST) +are the same. In fact, the segment evaluation method is preferred, as +it is compilable into a PUSHJ. + +Argument: + + Template: #DECL ("VALUE" LIST ANY LIST) + +Argument 1 -- An object. +Argument 2 -- A LIST to which the object should be prefixed. +Return -- A new list which points into the old one -- the old one is + NOT recopied. + +Example: +note that this is equivalent to (1 !'(2 3 4)) + +COS: Cosine of an angle + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: SIN, ATAN + + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- the angle in radians. +Returns -- A FLOAT, the Cosine. + +Example: <+ <* > + <* >> + 1.0 +One of the common trig. identities. + +CRLF: Print a carriage-return and line-feed + +Object-type: SUBR + +Category: I/O + +Reference: TERPRI + + +Argument: + + Template: #DECL ("VALUE" 'T "OPTIONAL" CHANNEL) + +(Optional) +Argument 1 -- the channel, default .OUTCHAN +Returns -- T + +Example: + T +Output carriage-return and line-feed. + +DECL-CHECK: Change or examine the state of DECL checking + +Object-type: SUBR + +Category: TYPE, UTILITY + + Changes the state of MUDDLE's DECL checking. Initially turned +on, it may be disabled by , or enabled by +. When enabled, each attempt to set an ATOM is checked +against any available DECL of that ATOM. An ERROR is generated if the +DECL does not match the value to which the ATOM will be set. + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" ) + +(Optional) +Argument 1 -- Any MUDDLE object. Non-false to enable DECL checking, + False to disable it. +Returns -- The old state. + +Example: +Enables DECL checking. + +DECL?: Check an object against a DECL Pattern + +Object-type: SUBR + +Category: DATA-HANDLING, PREDICATE + + DECL? is a predicate that tells whether or not an object +satisfies a type/structure declaration. + +Argument: + + Template: #DECL ("VALUE" + ANY >) + +Argument 1 -- an object to be checked +Argument 2 -- a QUOTEd Pattern to check it against +Returns -- T or a FALSE + +Example: > + T +note QUOTE on Pattern + +DEFINE: Define a FUNCTION + +Object-type: FSUBR + +Category: DATA-HANDLING + +Reference: FUNCTION, DEFMAC + + DEFINE sets the global value of an atom to the function it +creates from the rest of the arguments. It also checks to see if the +atom was already 'defined', if so and if the atom REDEFINE is non +false, it complains. Otherwise this fsubr operates like FUNCTION plus +SETG. + +Argument: + + Template: #DECL ("VALUE" ATOM ATOM "ARGS" LIST) + +Argument 1 -- The atom whose GVAL to make the function. +List of arguments -- If the first element of the list is an atom the + activation is bound to it, the rest is the arg list, DECL, and + body of the function. +Returns -- Argument 1. + +Example: 1) + (T + <* .N + >>)>> +Then returns 24 + +DEFMAC: Define an EVAL Macro + +Object-type: FSUBR + +Category: IDENTIFIER + +Reference: DEFINE, EXPAND + + DEFMAC is syntactically exactly the same as DEFINE. However, +instead of creating a FUNCTION, DEFMAC creates a MACRO. A MACRO is +of primtype LIST, and in fact has a FUNCTION (or other applicable type) +as its single element. + MACROs are applied in a funny way, however. It is EVALed +twice. The first EVAL causes the macro's element to be applied to the +macro's arguments. Whatever it returns (usually another form) is also +evaled, and the result of the second evaluation is the result of +applying the macro. + To avoid complications, the first eval (to create the object to +be evaled in the second...) is done at top-level. The result of this +policy is that two syntactically identical invocations of a macro +should always return the same thing to be evaled in the second EVAL. + EXPAND (qv) is used to perform the first EVAL without the second. + +Argument: + + Template: #DECL ("VALUE" ATOM ATOM "ARGS" LIST) + +Argument 1 -- The atom whose GVAL is to be the MACRO. +Argument 2 -- The parameter list. +Tuple of arguments -- The body of the macro. +Returns -- Argument 1. + +Example: + .N>>> + + 1 + + 2 + > + > +The standard INC hack, in EVAL-macro form. + +DEMSIG: Signal a system Daemon + +Object-type: SUBR + +Category: SYSTEM + + DEMSIG signals to a system Daemon that it should run. It takes +a STRING, which is the name of the Daemon in the system's tables, and +causes a signal to it to be sent. + Returns T if the Daemon exists, FALSE otherwise. + +Argument: + + Template: #DECL ("VALUE" STRING) + +Argument 1 -- A STRING giving the name of a Daemon. +Returns -- T if exists, FALSE otherwise. + +Example: +Signal the communication Daemon. + +DISABLE: Disable an interrupt + +Object-type: SUBR + +Category: INTERRUPT + +Reference: ENABLE + + DISABLE causes the interrupt associated with the IHEADER which +is its argument to be disabled. Disabled interrupts are ignored as +opposed to queued. + +Argument: + + Template: #DECL ("VALUE" IHEADER IHEADER) + +Argument 1 -- The IHEADER whose interrupt is to be disabled. +Returns -- Argument 1. + +Example: > +Disable the ^G and ^S interrupts. + +DISMISS: Dismiss an interrupt + +Object-type: SUBR + +Category: INTERRUPT + +Reference: INT-LEVEL, HANDLER + + DISMISS allows an interrupt handler to dismiss an interrupt +returning a value, to an arbitrary activation, at an arbitrary int- +level. Only the value is required. If the activation is not given +the return is to the place interrupted from. If the int-level is not +given, the int-level is restored to what it was prior to the invocation +of the HANDLER. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" ACTIVATION FIX) + +Argument 1 -- The value. +(Optional) +Argument 2 -- The activation to return the value from. Default, the + place from which the HANDLER was invoked. +Argument 3 -- The interrupt level to set on return. Default the one + prior to invocation of the HANDLER. +Returns -- The first argument. + +Example: + +A construct like this could be used to signal to a higher level that +somewhere in the code below it, a fatal error occured. + +DISPLAY: Display a PICTURE on a Display Channel [OBSOLETE] + + ******* This SUBR is obsolete as of MUD55 ******* + +Object-type: SUBR + +Category: GRAPHICS + +Reference: ERASE, OPEN, + MUDDLE GRAPHICS USER'S MANUAL, SYS.11.04, Bruce Daniels, Ed Black + + DISPLAY takes two arguments, a CHANNEL opened in DISPLAY mode, +and a PICTURE. The picture is displayed on the device associated with +the display channel. If no second argument is given, the display on +that device will be refreshed. This is useful if the device is a +display console such as an IMLAC or ARDS. + +Argument: + + Template: #DECL ("VALUE" CHANNEL CHANNEL "OPTIONAL" PICTURE) + +Argument 1 -- A CHANNEL open in display mode. +(Optional) +Argument 2 -- A PICTURE to display on the CHANNEL. If not given, the + display is refreshed only. +Returns -- The CHANNEL. + +Example: > + +Where PIC is a Picture created previously in some manner. + +ECHOPAIR: Pair up console channels for echoing + +Object-type: SUBR + +Category: I/O + + ECHOPAIR makes its two argument channels 'know about each other' +so that rubout, ^@, ^D, and ^L will work between them. + +Argument: + + Template: #DECL ("VALUE" CHANNEL CHANNEL CHANNEL) + +Argument 1 -- console-input channel +Argument 2 -- console-output channel +Returns -- arg1 + +Example: +what LISTEN does + +EMPTY?: Does a structure have zero elements ? + +Object-type: SUBR + +Category: PREDICATE, DATA-HANDLING + +Reference: MONAD? + + This routine tests if a given structured object has a length of +zero. Note that EMPTY? works correctly for circular Lists, which have +no well-defined length. + +Argument: + + Template: #DECL ("VALUE" STRUCTURED) + +Argument 1 -- Any structured object. +Returns -- T if the structured object has no elements, #FALSE () if it + has any elements at all. + +Example: +This will return #FALSE (). + +However, this will return T. + +ENABLE: Enable an interrupt + +Object-type: SUBR + +Category: INTERRUPT + +Reference: DISABLE + + ENABLE causes the interrupt associated with the IHEADER which is +its argument to be enabled. This causes the interrupt HANDLERS +associated with the IHEADER to be run when the interrupt occurs. + ENABLEing an already enabled interrupt does nothing. + +Argument: + + Template: #DECL ("VALUE" IHEADER IHEADER) + +Argument 1 -- An IHEADER whose interrupt is to be enabled. +Returns -- Argument 1. + +Example: > +Enable a clock interrupt. + +ENDBLOCK: Undoes the effect of BLOCK, returning a previous OBLIST path + +Object-type: SUBR + +Category: IDENTIFIER, ENVIRONMENT + +Reference: BLOCK + + ENDBLOCK pops a value of the ATOM OBLIST, returning the OBLIST +path to a previous state. It therefore undoes the effect of a BLOCK. + If no BLOCK has been done, produces an ERROR. + It returns the new OBLIST path. + +Argument: + + Template: #DECL ("VALUE" + ]>>) + +Returns -- The previous OBLIST path, now restored. + +Example: +Only possible example. + +ENTRY-LOC: Return the offset of an RSUBR-ENTRY + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: RSUBR-ENTRY, RSUBR + + This routine will return the offset of an RSUBR-ENTRY into an +RSUBR. This will be the same offset that was supplied to create the +RSUBR-ENTRY. + +Argument: + + Template: #DECL ("VALUE" FIX RSUBR-ENTRY) + +Argument 1 -- An RSUBR-ENTRY whose offset is to be returned. +Returns -- A FIX, the offset of the RSUBR-ENTRY in its RSUBR. + +Example: > + 347 +This will return the offset given to RSUBR-ENTRY, which is the 347. + +EQVB: Bitwise logical EQV of its arguments + +Object-type: SUBR + +Category: LOGICAL, BIT-TWIDDLING + +Reference: ANDB, ORB, XORB + + EQVB takes any number of arguments of Primtype WORD, and returns +a WORD that is their bitwise logical EQV, that is, the bits they have +in common. + +Argument: + + Template: #DECL ("VALUE" WORD ]>) + +Tuple of arguments -- Primtype WORDs to be EQVed together. +Returns -- A WORD. + +Example: + #WORD *000000000000* +No bits in common. + +ERASE: Erase a picture from a Display Channel [OBSOLETE] + + ******* This SUBR is obsolete as of MUD55 ******* + +Object-type: SUBR + +Category: GRAPHICS + +Reference: DISPLAY, OPEN, + MUDDLE GRAPHICS USER'S MANUAL, SYS.11.04, Bruce Daniels, Ed Black + + ERASE takes two arguments, the second optional. The first is a +CHANNEL open in Display mode. The second is a picture. ERASE causes +the picture to be removed from the display on that CHANNEL. If the +second argument is not given, all the pictures on that CHANNEL will be +removed, leaving an empty display. + +Argument: + + Template: #DECL ("VALUE" CHANNEL CHANNEL "OPTIONAL" PICTURE) + +Argument 1 -- A CHANNEL open in display mode. +(Optional) +Argument 2 -- A PICTURE to erase from the CHANNEL. If not given, all + of the pictures on the CHANNEL are ERASEd. +Returns -- The CHANNEL. + +Example: > + + + +Display PIC and then remove it. (Where PIC is a Picture created +previously in some manner). + +ERRET: Return a value as the value of a FRAME + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: RETRY, RETURN + + ERRET is used to return values from FRAMEs. It takes two +optional arguments, a value to return, and a FRAME. If defaulted, +the FRAME is the frame of the last invocation of ERROR or LISTEN, and +if both are defaulted, it means to return to TOPLEVEL and reenter the +LISTEN loop there. + ERRET is used most often to recover from errors, by returning +a reasonable argument from the frame that called ERROR. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ANY FRAME) + +(Optional) +Argument 1 -- The value to return from the FRAME given in arg2. +Argument 2 -- The FRAME from which to return the value given. +Returns -- Argument 1. + +Example: + +Single most common use of ERRET -- continue from REDEFINE ERROR, +return something innocuous as value of funny atom, and so on. + +ERROR: Announce an ERROR + +Object-type: SUBR + +Category: ERROR + +Reference: ERRET + + ERROR is used to announce an ERROR in a program. It takes any +number of arguments, which will be printed as ERROR recurses to a +higher level LISTEN loop. + The usual format is to give an ATOM which is the reason for the +ERROR, the routine in which it occurred, and any other information of +interest last. + +Argument: + + Template: #DECL ("VALUE" ANY "TUPLE" TUPLE) + +Tuple of arguments -- ANY number of arguments of any type. +Returns -- Whatever the user ERRETs from it. + +Example: +Most common ERROR call format is this. + +ERRORS: Returns the ERRORS OBLIST + +Object-type: SUBR + +Category: ERROR + +Reference: ERROR, ROOT + + ERRORS returns the ERRORS OBLIST. This is the OBLIST on which +live the ATOMs whose PNAMEs are the MUDDLE ERROR messages. + +Argument: + + Template: #DECL ("VALUE" OBLIST) + +Returns -- The ERRORS OBLIST. + +Example: +Only possible example. + +EVAL: Evaluate an expression in a given envirnoment + +Object-type: SUBR + +Category: PROGRAM-CONTROL + + EVAL is a program control subr. The first arg to EVAL is the MUDDLE +expression to be evaluated. The second, optional, arg is the execution +environment in which the evaluation is to take place. If the second +arg is not supplied the current environment of the current process will +be used. + Every Type in MUDDLE has a defined, or default, rule for evaluation +of MUDDLE objects of that Type. See EVALTYPE on how to change these +rules. + The initial EVAL rules for MUDDLE Types are: + +FORM-- + EVAL of empty FORM is #FALSE () + If <1 <-Form-> > is an ATOM, + then, APPLY either GVAL of Atom or VALUE of the Atom to the + appropriately EVALed or unEVALed args. + else, APPLY the EVAL of <1 <-Form-> > to the appropriately EVALed + or unEVALed args. + Note that the subsequent EVAL of an arg which is of Type SEGMENT + is treated specially. + +LIST or VECTOR or UVECTOR-- + make a new structured object of the same Type whose elements + are the EVALuated elements of the given object. + Note that the EVAL of an element of the structure + which is of Type SEGMENT is also treated specially. + +ALL other types-- + Evaluate to themselves. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" + ) + +Argument 1 -- ANY object to be EVALed. +(Optional) +Argument 2 -- An ACTIVATION, FRAME, ENVIRONMENT, or PROCESS in which + to perform the evaluation. +Returns -- The result of the EVAL, as described above. + +Example: > > + + This will increment the local value of the Atom X in the process +which last resumed the current process. + Note that the value of X in the current process, if any, will not +be affected. + +EVALTYPE: Change or examine the way a TYPE is EVALed + +Object-type: SUBR + +Category: TYPE-MANIPULATION, PROGRAM-CONTROL + +Reference: EVAL, APPLYTYPE + + Changes the way a specific type is EVALed, by either mapping +it into another type, or giving an explicit method via an APPLICABLE. + If a type is given, the type being changed will be EVALed in the +same manner as that type. + If an APPLICABLE is given, it should take one argument, +which will be the object being EVALed. Whatever the APPLICABLE returns +will be the result of the EVALuation. If ,EVAL is given, the type +will hereafter receive no special treatment in evaluation. + If no second arg is given, EVALTYPE returns the last second arg +that was given for this type, or #FALSE () if the type is receiving no +special treatment in evaluation. + +Argument: + + Template: #DECL ("VALUE" ATOM "OPTIONAL" + ) + +Argument 1 -- The type whose EVALTYPE to change or examine. +(Optional) +Argument 2 -- A TYPE (which means 'Eval like this type'), or an + APPLICABLE (meaning 'use this when you EVAL this type'). +Returns -- The TYPE which was changed or, if no arg 2, the special + treatment it is receiving if any. + +Example: + + + + +This will set up MUDDLE to look like LISP to the casual user: + (+ 1 2) + 3 + (SET 'A 5) + 5 + A + 5 +LISP in MUDDLE? + +EVENT: Set up an IHEADER for an event + +Object-type: SUBR + +Category: INTERRUPT + +Reference: DISABLE, ENABLE + + EVENT sets up an IHEADER for either an external or internal +interrupt. No handlers are attached to the IHEADER set up by EVENT. + The first argument to EVENT identifies the interrupt. It may be +a string or an atom on the INTERRUPTS OBLIST. In either case if the +name is associated with a physical interrupt, the real interrupt is +set up. The first argument may also be a previously OFFd IHEADER. + The second argument is the priority of this interrupt and it must +be a positive fixed point number. The priority basically specifies +how important this interrupt is relative to other interrupts. + If the first argument to EVENT is either CHAR!-INTERRUPTS, +READ!-INTERRUPTS or WRITE!-INTERRUPTS or the strings with those names, +a third argument is required. For CHAR this must be a TTY input +channel and for the others it must be the locative getting the READ or +WRITE monitor. + +Argument: + + Template: #DECL ("VALUE" IHEADER FIX + "OPTIONAL" ) + +Argument 1 -- The name of the interrupt. +Argument 2 -- A priority. +(Optional) +Argument 3 -- A CHANNEL, for character interrupts, or LOCATIVE, for monitors +Returns -- An IHEADER. + +Example: > +Setup a SYSDOWN interrupt. + +EXP: Exponents of 'e' + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: LOG + + EXP is the opposite of LOG, taking e to a power. It takes a FIX +or FLOAT as argument, and returns e to that power, converted to a FLOAT +whether the argument was fix or float. + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- A FIX or FLOAT to take e to the power of. +Returns -- (e ** ) + +Example: > + 2.0 +Note conversion to floating point number. + +EXPAND: Expand a MACRO + +Object-type: SUBR + +Category: ENVIRONMENT, UTILITY + +Reference: DEFMAC + +EXPAND evaluates its argument in a top-level environment, that is, as +if no LVALs existed. It is designed to perform the first evaluation +in a MACRO application, but it can be useful in other cases. + +Argument: + + Template: #DECL ("VALUE" ANY ANY) + +Argument 1 -- an object to evaluate +Returns -- the top-level value of the object or 'body' of the MACRO + +Example: + .N>>> + INC + > + > +Note that > would EVAL this last form too. + +FILE-EXISTS?: Check for existence of a file + +Object-type: SUBR + +Category: I/O + +Reference: OPEN + + FILE-EXISTS? takes arguments like the second and higher arguments +to OPEN (q.v.). It returns T if the file thus specified exists, otherwise +a FALSE of two elements: the error message and error code returned by the +operating system. + +Argument: + + Template: #DECL ("VALUE" "TUPLE" ) + +Argument 1-4 -- file names +Returns -- T if file exists, a FALSE otherwise + +Example: +Will return T if FOO is a real directory. + +FILE-LENGTH: Get length of input file + +Object-type: SUBR + +Category: I/O + +Reference: FILECOPY + + FILE-LENGTH tells the length (in characters or binary words, +depending on the channel's mode) of the disk file open for input on its +argument channel. + +Argument: + + Template: #DECL ("VALUE" FIX CHANNEL) + +Argument 1 -- input disk channel +Returns -- length of disk file + +Example: > +Next input will detect end of file. + +FILECOPY: Copy entire file from one channel to another + +Object-type: SUBR + +Category: I/O + +Reference: FILE-LENGTH + + FILECOPY copies characters from an input channel (arg1) to an +output channel (arg2) until the end of file, thus closing the input +channel. A FILE-LENGTH on arg1 must win, ruling out certain devices. + +Argument: + + Template: #DECL ("VALUE" FIX "OPTIONAL" CHANNEL CHANNEL) + +(Optional) +Argument 1 -- source (input) channel, default .INCHAN +Argument 2 -- destination (output) channel, default .OUTCHAN +Returns -- number of characters copied + +Example: > +like Monit's WHO + +FIX: Convert a FLOAT to a FIX + +Object-type: SUBR + +Category: TYPE-MANIPULATION, ARITHMETIC + +Reference: FLOAT + + FIX takes a FLOAT and converts it to a FIX, truncating the +fractional part. + +Argument: + + Template: #DECL ("VALUE" FIX ) + +Argument 1 -- A FLOAT to convert +Returns -- A FIX corresponding to the FLOAT. + +Example: + 69 +Note the truncating. + +FLATSIZE: Return the size of an object within a maximum + +Object-type: SUBR + +Category: DATA-HANDLING, I/O + +Reference: PRINT + + FLATSIZE returns the number of characters needed to PRINT an +item, if it is less than the bound (thus winning on self-referencing things). +If it is greater than the upper bound, returns #FALSE (). + +Argument: + + Template: #DECL ("VALUE" ANY FIX "OPTIONAL" FIX) + +Argument 1 -- The object to 'PRINT'. +Argument 2 -- The upper bound on size of the object. +(Optional) +Argument 3 -- radix for FIX conversion +Returns -- The size, if less than the bound, or #FALSE () if not. + +Example: +Will be a fix result + +Will be a FALSE + +FLOAD: READ and EVAL every object in a file + +Object-type: SUBR + +Category: I/O + +Reference: READ, EVAL, LOAD, UNWIND, OPEN + + FLOAD opens a file, READs and EVALs every object in it, and +closes it again. If the opening fails, an ERROR occurs, giving the +reason for failure. A (list of) oblist(s) may also be given for +looking up atoms. Control characters in the file have no special +meaning. An UNWIND is set up to close the channel on any ERRET. + +Argument: + + Template: #DECL ("VALUE" '"DONE" "TUPLE" TUPLE) + +(Optional) +Tuple of arguments -- string(s) as for OPEN and/or oblist as for READ +Returns -- "DONE" + +Example: +part of initialization for TS file + +FLOAT: Convert a FIX to a FLOAT + +Object-type: SUBR + +Category: TYPE-MANIPULATION, ARITHMETIC + +Reference: FIX + + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- A FIX to convert to a FLOAT. +Returns -- The new FLOAT. + +Example: + 69.0 +CHTYPE would lose, of course. + +FORM: Create a FORM with explicit arguments + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: IFORM + + FORM creates a FORM of explicit arguments. This is the way to +make a form with the elements evaluated. + +Argument: + + Template: #DECL ("VALUE" FORM "TUPLE" ) + +Tuple of arguments -- Any objects, the elements of the FORM. +Returns -- The FORM created. + +Example: >>> +this returns the form > when called with FOO as arg + +FRAME: Walk the chain of stack frames + +Object-type: SUBR + +Category: ENVIRONMENT, UTILITY + +Reference: FUNCT, ARGS + + FRAME returns the 'previous' stack-frame on the stack. This +means that given a FRAME, it returns the FRAME that generated it. If +no FRAME is given, it returns the topmost FRAME on the stack. +Given an ACTIVATION or ENVIRONMENT, it returns the appropriate FRAME. + When the stack 'runs out', i.e., the end is reached, it returns +#FRAME TOPLEVEL. + In conjunction with ARGS and FUNCT, makes a powerful debugging +aid. + FRAME, ARGS, and FUNCT may also get access to the stack frames +of other processes, by giving the process as an argument. If this +feature is used, returns the topmost FRAME of that process. + +Argument: + + Template: #DECL ("VALUE" FRAME + "OPTIONAL" ) + +(Optional) +Argument 1 -- Either nothing, meaning return topmost FRAME of this + PROCESS, or a FRAME, meaning return next FRAME of this PROCESS, + or an environment, meaning return topmost FRAME of this + environment. +Returns -- As described above, a FRAME, or #FRAME TOPLEVEL when the + end of the stack is reached. + +Example: )) + ) + (N 1)) + TOPLEVEL> + )> + + > + > + > + > + >>> +A primitive version of the FRAMES function installed in MUDDLE. + +FREE-RUN: Returns a PROCESS to free running state + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: 1STEP + + Puts a PROCESS back into a free running state after it has been +in one-step mode. Takes a PROCESS as argument. + +Argument: + + Template: #DECL ("VALUE" PROCESS) + +Argument 1 -- A PROCESS to return to normal running mode. +Returns -- The PROCESS, or FALSE if PROCESS not in one-step mode. + +Example: +Now will run free when RESUMEd. + +FREE: Free non-garbage collected STORAGE [OBSOLETE] + + ******* This SUBR is obsolete as of MUD55 ******* + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: STORE + + FREE de-allocates non-garbage collected storage (mostly used for +E&S display). Once it has been free'd it will be used by STORE again. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- A storage: the space to be released. +Returns -- The same storage -- better not hold on to it. + +Example: > +Free up newly created STORAGE. + +FREEZE: Copy an object into non-moving storage + +Object-type: SUBR + +Category: DATA-HANDLING, UTILITY + + FREEZE copies its argument into non-moving (garbage-collected) +space. It CHTYPEs the copy to its PRIMTYPE; a TUPLE is changed to a +VECTOR. FREEZEing is mostly valuable applied to the CODE of an RSUBR. + +Argument: + + Template: #DECL ("VALUE" + + + + >) + +Argument 1 -- a vector, tuple, uvector, or string to freeze +Returns -- a frozen copy of arg1 + +Example: > +to debug an RSUBR + +FUNCT: Return the function that generated a FRAME + +Object-type: SUBR + +Category: ENVIRONMENT, UTILITY + +Reference: FRAME, ARGS + + FUNCT returns the ATOM which is the name of the applicable object +which caused a given FRAME to be created. Takes a FRAME or other +environment as an argument. If given a non-FRAME, it returns the +topmost function name of that environment. + Most commonly used as part of a more sophisticated program, such +as FRAMES or FR&. + +Argument: + + Template: #DECL ("VALUE" ATOM + ) + +Argument 1 -- an environment +Returns -- The ATOM which is the name of the object which caused the + FRAME to be created. + +Example: > + LISTEN +If done at top level. + +FUNCTION: Create a FUNCTION + +Object-type: FSUBR + +Category: DATA-HANDLING + +Reference: DEFINE + + FUNCTION creates a function. In cases where the function is to +be made the GVAL of an ATOM, it is preferable to use DEFINE. + A FUNCTION consists of an optional ACTIVATION name (an ATOM), +a Parameter LIST, an optional DECL, and a body consisting of at least +one object. + +Argument: + + Template: #DECL ("VALUE" FUNCTION "ARGS" LIST) + +List of arguments -- if the first element of the list is an atom the + activation is bound to it, the rest is the arg list, DECL, and + body of the function. +Returns -- A FUNCTION. + +Example: > +equivalent to #FUNCTION ((N) <+ 1 .N>) + +G=?: Is first argument greater than or equal to the second ? + +Object-type: SUBR + +Category: PREDICATE, ARITHMETIC + +Reference: L?, G? + + This routine tests if the first argument is numerically greater +than or equal to the second argument, returning T if it is, #FALSE() +otherwise. + +Argument: + + Template: #DECL ("VALUE" + ) + +Argument 1 -- A FIX or FLOAT. +Argument 2 -- A FIX or FLOAT. +Returns -- T if arg1 >= arg2, #FALSE() if not. + +Example: + + +These will return T. + + +These will return #FALSE (). + +G?: Is first argument greater than the second ? + +Object-type: SUBR + +Category: PREDICATE, ARITHMETIC + +Reference: L?, G=? + + This routine tests if the first argument is numerically greater +than the second argument, returning T if it is, #FALSE() otherwise. + +Argument: + + Template: #DECL ("VALUE" + ) + +Argument 1 -- A FIX or FLOAT. +Argument 2 -- A FIX or FLOAT. +Returns -- T if arg1 > arg2, #FALSE() if not. + +Example: + +These will return T. + + + +These will return #FALSE (). + +GASSIGNED?: Is an Atom globally assigned ? + +Object-type: SUBR + +Category: PREDICATE, IDENTIFIER + +Reference: ASSIGNED?, BOUND? + + This routine is used to test if a particular Atom is globally +assigned, or in other words, if it has a global value. It does cause +the activation of any read monitors on that global value. + It returns T if the ATOM has a GLOBAL value, #FALSE() otherwise. + +Argument: + + Template: #DECL ("VALUE" ATOM) + +Argument 1 -- An ATOM which may have a global value. +Returns -- T if the ATOM has a global value, #FALSE() otherwise. + +Example: + +This will simply return the Atom T, since FOO does have a global +value. + + +This will simply return #FALSE (), since the Atom FOO has no global +value. + +GBOUND?: Does an atom have a global-value slot? + +Object-type: SUBR + +Category: IDENTIFIER, PREDICATE + +Reference: SETG, MANIFEST, GDECL, GLOC + + GBOUND? tells whether or not an atom has a slot in the 'global +vector', that is, whether it has ever been SETGed, MANIFEST, GDECLed, +or GLOCed successfully. + +Argument: + + Template: #DECL ("VALUE" ATOM) + +Argument 1 -- the atom to test +Returns -- whether or not the atom is globally bound + +Example: + T +obviously + +GC-DUMP: Dump an object so it can be reproduced exactly + +Object-type: SUBR + +Category: I/O + +Reference: GC-READ + + GC-DUMP dumps an object via a channel so that GC-READ (q.v.) +can reproduce it exactly, including sharing. Any non-stack, non-pure +object can be dumped, except primtypes process, locd, and asoc. +If a false is given instead of a channel, GC-DUMP returns what it +would have output on the channel, as a uvector. This uvector can be +stored as desired, but it must not be changed in any way to be +GC-READable. + +Argument: + + Template: #DECL ("VALUE" >> + ANY ) + +Argument 1 -- the object to be dumped +Argument 2 -- "PRINTB/O" channel or false +Returns -- arg1 if arg2 is channel, else output data + +Example: > + <>> +can dump circular objects + +GC-MON: Toggle state of GC monitor + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: GC + + GC-MON is used to turn on and off the typing of GIN and GOUT +and other info upon entering and leaving the garbage collector. + If the argument is FALSE no typing will occur, otherwise typing +will occur. The initial state of the GC-monitor is to not type. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ANY) + +(Optional) +Argument 1 -- If non-FALSE, turn on GC-monitor, else turn it off. +Returns -- The previous or current state of the monitor. + +Example: +Turn on GC-monitoring + +GC-READ: Input an object that was previously GC-DUMPed + +Object-type: SUBR + +Category: I/O + +Reference: GC-DUMP + + GC-READ returns one object from a given channel, open to a file +produced by GC-DUMP (q.v.). + +Argument: + + Template: #DECL ("VALUE" ANY CHANNEL "OPTIONAL" ANY) + +Argument 1 -- a "READB" channel to read from +(Optional) +Argument 2 -- object to eval and return at eof +Returns -- an object from the file, or arg2 + +Example: )) + >>>>> +get all GC-DUMPed objects from a file + +GC: Cause a Garbage Collection to occur + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: GC-MON, BLOAT + + GC always causes a garbage collection and returns the amount +of storage reclaimed. Its first optional argument specifies the +minimum amount of free space tolerable in future gc's. Its second +argument tells whether this gc should be exhaustive. Its third argument +changes the parameter telling how many mark-sweep gcs to do between +"real" ones; this is initially 0, meaning never mark-sweep. + +Argument: + + Template: #DECL ("VALUE" FIX "OPTIONAL" FIX FIX) + +(Optional) +Argument 1 -- FIX specifying amount of free space to get. +Argument 2 -- whether gc should be exhaustive +Argument 3 -- how many mark-sweep GCs to do between "real" ones. +Returns -- A FIX giving the amount free space reclaimed. + +Example: > +GC and change a GC parameter + +GDECL: Make a declaration for a global value + +Object-type: FSUBR + +Category: DATA-HANDLING + +Reference: GET-DECL, PUT-DECL, MANIFEST + + GDECL is used to make a DECL for a global value or values, in +much the same way as the #DECL () construct is used for local values. +It takes the standard DECL syntax argument (ie, CHTYPEing REST of the +GDECL form to DECL would make it look like a local DECL). + ATOMs that have been GDECLed will give ERRORs on an attempt to +SETG them to something that conflicts with their DECL, unless, of +course, DECL-checking is disabled. + +Argument: + + Template: #DECL ("VALUE" ANY + "ARGS" + ]>) + +List of arguments -- Pairs consisting of a LIST of ATOMs and a + DECL body. +Returns -- T + +Example: > +Just like local DECLs. + +GET-DECL: Get the DECL of an ATOM + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: PUT-DECL + + GET-DECL returns the current DECL of an ATOM's GVAL or LVAL. +It takes a single argument, a locative to the value. It returns +either the DECL, the ATOM MANIFEST (if the ATOM is manifest), or +FALSE, if the ATOM has no DECL. + The use of locatives allows the same SUBR to work for both local +and global values. + + If given an OFFSET, returns the DECL part of the OFFSET. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- A locative to the global or local value slot of an + ATOM, or an OFFSET. +Returns -- The DECL of that value, or MANIFEST, or FALSE. + +Example: + + + > + LIST + + >> + + +See also PUT-DECL, for changing declarations. + +GET: Get an element of a structure or the value of an association + +Object-type: SUBR + +Category: DATA-HANDLING, ASSOCIATION + +Reference: PUT, GETPROP + + GET returns a given property associated with an item, or if +second arg is a fix and the object is structured, returns that element +of the structured object. + Thus, GET is like GETPROP if the first argument is not a structure, +and like NTH if it is. + If GET is being used like GETPROP, an optional third argument is +allowed, which is what to return if there is no association between +the given item and indicator. + +Argument: + + Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY) + +Argument 1 -- The object with the association or structure. +Argument 2 -- The indicator under which the association is stored or + the FIX offset within a structure. +(Optional) +Argument 3 -- The default to be evaled and returned if no assoc, else + FALSE is the result. +Returns -- The element of the structure, value of the association, or + the optional third argument if given, or FALSE. + +Example: + + + (.A + + + )> +Notice the difference between the PROP and non-prop subrs + +GETBITS: Get part of a word + +Object-type: SUBR + +Category: BIT-TWIDDLING + +Reference: BITS, PUTBITS + + GETBITS takes a PRIMTYPE WORD (or a STORAGE, for which its +address is used) and a BITS, and returns a word generated by picking +up the bits described by the BITS. For example, a BITS of +describes the rightmost 7 bits of a word. Therefore, a GETBITS using +it will return the rightmost 7 bits. + It is functionally equivalent to the PDP-10 Load Byte (LDB) +instruction. + +Argument: + + Template: #DECL ("VALUE" WORD > BITS) + +Argument 1 -- An object of type WORD. +Argument 2 -- A BITS, as returned by BITS. +Returns -- A WORD containing the bits described by Argument 2. + +Example: > + #WORD *000000000007* +Non-WORDs need not be CHTYPEd. + +GETL: Get a locative to a structure or the value of an association + +Object-type: SUBR + +Category: DATA-HANDLING, ASSOCIATION + +Reference: PUT, GETPROP, GETPL + + GETL returns a locative to a given association, or if second arg +is a fix and the object is structured, returns a locative to that +element of the structured object. + Thus, GETL is like GETPL if the first argument is not a structure, +and like AT if it is. + If GETL is being used like GETPL, an optional third argument is +allowed, which is what to return if there is no association between +the given item and indicator. + +Argument: + + Template: #DECL ("VALUE" ANY ANY + "OPTIONAL" ANY) + +Argument 1 -- The item part of the association or a structure. +Argument 2 -- The indicator under which the association is stored or + the FIX offset within a structure. +(Optional) +Argument 3 -- The default to be evaled and returned if no assoc, else + FALSE is the result. +Returns -- A locative to the association or element of a structure, or + if acting like GETPL and there is no association, eval of the + optional third argument if given, or FALSE. + +Example: + + + (.A + + + )> +Notice the difference between the PROP and non-prop subrs + +GETPL: Get an a locative to the value of an association + +Object-type: SUBR + +Category: ASSOCIATION + +Reference: PUT, GETPROP, GETL + + GETPL returns a locative to the value part of an association +with given item (arg1) and indicator (arg2). It also takes a third +argument (optional) which will be evaled if the association does not +exist (default is FALSE). + Note that GETL is identical to GETPL if its first argument is not +structured and its second is not a FIX. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" ANY) + +Argument 1 -- The object with the association. +Argument 2 -- The indicator under which the association is stored. +(Optional) +Argument 3 -- The default to be evaled and returned if no assoc, else + FALSE is the result. +Returns -- A locative (type LOCAS) to the association if it exists, or + eval of the optional third argument if given, or FALSE. + +Example: + + + (.A + + + )> +Notice the difference between the PROP and non-prop subrs + +GETPROP: Get the value of an association + +Object-type: SUBR + +Category: DATA-HANDLING, ASSOCIATION + +Reference: PUT, PUTPROP, GETPL, GETL + + GETPROP returns a given property associated with an item. It +takes two required arguments, the item and the indicator, and a third +argument which is optional, and which will be evaled and returned if +the item-indicator pair has no association on it (default a FALSE). + GETPROP is thus one end of a triad of SUBRs, GETPROP, GET and NTH, +which together make up a full association/subelement mechanism. This +is paralleled by PUT and PUTPROP, and GETPL, GETL and AT. + +Argument: + + Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY) + +Argument 1 -- The item part of an item-indicator pair. +Argument 2 -- The indicator under which the association is stored. +(Optional) +Argument 3 -- The default to be evaled and returned if no assoc, else + FALSE is the result. +Returns -- The element of the structure, value of the association, or + the optional third argument if given, or FALSE. + +Example: + + + (.A + + + )> +Notice the difference between the PROP and non-prop subrs + +GLOC: Get a locative to the GVAL of an ATOM + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LLOC + + Returns a locative, type LOCD, to the GVAL of the ATOM passed +as its argument. If the ATOM has no GVAL slot, ERROR, unless second +arg is given and true. + +Argument: + + Template: #DECL ("VALUE" LOCD ATOM "OPTIONAL" ) + +Argument 1 -- An ATOM with a GVAL. +(Optional) +Argument 2 -- whether not to give a no-slot error or not +Returns -- A locative (LOCD) to the GVAL of the ATOM. + +Example: > +Guard against ATOMs with no GVALs. + +GO: Go elsewhere in a PROG/REPEAT + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: TAG, PROG, REPEAT + + GO transfers control to a given top-level object within a PROG +or REPEAT. The place to go is specified by an atom label or a tag. +GO is very seldom tasteful: use nested REPEAT or MAPF/R instead. + +Argument: + + Template: #DECL ("VALUE" ANY ) + +Argument 1 -- where to go to +Returns -- RESUME arg, if tag lay in another process + +Example: + AWAY + + <&> + + &..> +exactly what GO should do + +GROW: Enlarge a VECTOR or UVECTOR + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: GC + + GROW extends the bounds of a vector or uvector. Be aware that +growing causes a garbage collection and is therefore an expensive +operation. That is the reason it is only done in increments of 32 or +64. + +Argument: + + Template: #DECL ("VALUE" > + > FIX FIX) + +Argument 1 -- The object to grow. +Argument 2 -- Number to be added to the end rounded up to a multiple + of 32 for VECTORs, 64 for UVECTORs. +Argument 3 -- Number to be added to beginning rounded up to a multiple + of 32 for VECTORs, 64 for UVECTORs. +Returns -- The newly enlarged VECTOR or UVECTOR. + +Example: +will grow by 32 on each end. + +GUNASSIGN: Removes the Global value of an ATOM + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: GVAL, GASSIGNED? + + GUNASSIGN removes the global value of an ATOM. After an ATOM +has been GUNASSIGNED, GVAL of it will cause and error, and GASSIGNED? +of it will return FALSE. + +Argument: + + Template: #DECL ("VALUE" ATOM ATOM) + +Argument 1 -- The ATOM to flush the GVAL of. +Returns -- The ATOM you just GUNASSIGNed. + +Example: + GUNASSIGN +Something you only do once. + +GVAL: Return the Global value of an ATOM + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: GASSIGNED?, GUNASSIGN + + Returns the Global value of an ATOM, if any. If the ATOM has +no Global value, ERROR. + The expressions , and > are identical. + +Argument: + + Template: #DECL ("VALUE" ANY ATOM) + +Argument 1 -- An ATOM. +Returns -- Its GVAL, if it has one. + +Example: <==? ,FOO .FOO> + +GVAL and LVAL are independent, but watch out using both -- the last +referenced is kept in the ATOM's value slot, so switching back and +forth can be expensive! + +HANDLER: Attach an interrupt handler to an IHEADER + +Object-type: SUBR + +Category: INTERRUPT + +Reference: EVENT, ENABLE, DISABLE + + HANDLER attaches an interrupt handler to an IHEADER. It may +build and attach a new handler or reattach a previously OFFed handler. + The first argument is always the IHEADER. The second argument +is either the previously OFFd handler or an applicable object. +The last argument is optional and may be a +process in which the handler is to run. If no process is supplied, +the interrupt will run in whatever process is currently running. +Note: new handlers are always added to the beginning of the list of +handlers. + +Argument: + + Template: #DECL ("VALUE" HANDLER IHEADER + "OPTIONAL" PROCESS) + +Argument 1 -- An IHEADER, such as is returned by EVENT. +Argument 2 -- An APPLICABLE object to handle the interrupt, or a + previously OFFed HANDLER. +(Optional) +Argument 3 -- A PROCESS in which to run the interrupt. +Returns -- A HANDLER, which has been added to the beginning of the + list of HANDLERs for that interrupt. + +Example: > + ,QUITTER> +Setup a character interrupt with one handler. + +HANG: Hang interruptably forever + +Object-type: SUBR + +Category: ENVIRONMENT, INTERRUPT + +Reference: SLEEP + + HANG causes the MUDDLE to hang interruptably forever. It is +useful if there is an activation available to return to beyond the +HANG. Alternatively, it takes an optional argument which is EVALed +each time an interrupt DISMISSes back to the HANG. If the argument +EVALs to non-FALSE, the HANG terminates, returning the result of the +EVAL. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ANY) + +(Optional) +Argument 1 -- Something to EVAL each time the HANG is dismissed to. +Returns -- The result of EVALing the argument, or if it is not given, + never returns (May be non-locally returned beyond, of course). + +Example: +Hang until someone (at interrupt level) sets FOO to a non-FALSE. + +IBYTES: Generate a BYTES by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: BYTES + + IBYTES returns a byte-string of given byte-size and length whose +elements are generated by repeated evaluation of the third argument. +Note that the third argument must return a FIX each time it is EVALed. + +Argument: + + Template: #DECL ("VALUE" BYTES FIX FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, size of bytes +Argument 2 -- FIX, number of elements. +(Optional) +Argument 3 -- ANY, expression which when evaled, gives each element, + default is zeros. +Returns -- Newly baked BYTES. + +Example: >) ()>> + #3 {0 1 2 3 4 5 6 7 0} + +IFORM: Generate a FORM by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: FORM + + IFORM returns a form of given length whose elements are generated +by repeated evaluation of the second argument. + +Argument: + + Template: #DECL ("VALUE" FORM FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements to generate. +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element + default is #LOSE *0*'s. +Returns -- The newly hatched FORM. + +Example: >> + .ROOTL>>>> + +Makes a FORM by picking the first elements of 5 randomly selected +buckets in the ROOT OBLIST. + +ILIST: Generate a LIST by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LIST + + ILIST returns a list of given length whose elements are generated +by repeated evaluation of the second argument. + +Argument: + + Template: #DECL ("VALUE" LIST FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element + default is #LOSE *0*'s +Returns -- The newly created LIST. + +Example: +Create a LIST containing five 0s. + +IMAGE: Output a naked character + +Object-type: SUBR + +Category: I/O + +Reference: PRINC + + IMAGE outputs precisely the character whose ASCII value is +given as an arg. It does not add up-arrow, line-feed, etc. + +Argument: + + Template: #DECL ("VALUE" FIX FIX "OPTIONAL" CHANNEL) + +Argument 1 -- ASCII code for character to send naked +(Optional) +Argument 2 -- the channel to send it on, default .OUTCHAN +Returns -- arg1 + +Example: + 1 + + 2 +draws an I-beam on an Imlac + +IN: Get the object a locative points to + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: AT, LLOC, GLOC, LEGAL? + + Returns the object a locative points to. The only way you can +get an error using IN is to pass it a locative to an LVAL that has +become unbound. Using LEGAL? will save you much grief. + +Argument: + + Template: #DECL ("VALUE" ANY LOCATIVE) + +Argument 1 -- A locative. +Returns -- The object the locative points to. + +Example: + > + 69 +Like LVAL except independent of rebindings of FOO. + +INDEX: Return the index part of an OFFSET + +Object-type: SUBR + +Category: STRUCTURES + +Reference: OFFSET, NTH, GET-DECL, PUT-DECL + + Given an OFFSET, returns the index part. + +Argument: + + Template: #DECL ("VALUE" FIX OFFSET) + +Argument 1 -- An OFFSET +Returns -- The index field of the OFFSET. + +Example: >> + %> + + 1 +Use GET-DECL to get the DECL part of the OFFSET. + +INDICATOR: Return the indicator part of an Association triad + +Object-type: SUBR + +Category: ASSOCIATION + +Reference: ASSOCIATIONS, NEXT, ITEM, AVALUE, + GETPROP, GET + + Given an ASOC, as returned by ASSOCIATIONS or NEXT, returns the +indicator part of the ASOC triad. + See also ITEM and AVALUE, which return the Item and Value parts +of the triad. + +Argument: + + Template: #DECL ("VALUE" ANY ASOC) + +Argument 1 -- An ASOC whose indicator field to get. +Returns -- The indicator field of the ASOC. + +Example: + > + FOO + > + BAR + > + BLECH +ASSOCIATIONS gets newest ASOC. + +INSERT: Create an ATOM and put it on an OBLIST + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: ATOM, LOOKUP + + INSERT takes as argument a STRING, which will be the PNAME of +a new ATOM on the OBLIST given as the second argument. The ATOM is +returned. + In the special case where the ATOM is not already on an OBLIST, +INSERT will also take an ATOM as argument. In conjunction with REMOVE +this feature may be used to move an ATOM from one OBLIST to another. + Note that if the ATOM with the PNAME given already exists on that +OBLIST, ERROR. See the example for the standard foolproof way to +INSERT. + +Argument: + + Template: #DECL ("VALUE" ATOM OBLIST) + +Argument 1 -- A STRING, which is the PNAME of a new ATOM to be + created, or an ATOM on no OBLIST. +Argument 2 -- An OBLIST into which to insert the new ATOM. +Returns -- The newly minted ATOM. + +Example: > +This will fail, as the ATOM is already there. + > >> +Guaranteed to win. + +INT-LEVEL: Read and set the current interrupt level + +Object-type: SUBR + +Category: INTERRUPT + + INT-LEVEL is used to read and set the current interrupt level. +If it is called with no arguments, it simply returns the current level +otherwise it causes its fixed point argument to be the current +interrupt level and returns the previous one. + Note that 0 is the 'normal' int-level, and during handling of an +interrupt, the int-level is set to the priority assigned to the int- +errupt that is being handled. + +Argument: + + Template: #DECL ("VALUE" FIX "OPTIONAL" FIX) + +(Optional) +Argument 1 -- A FIX, which will be the new interrupt level. If not + given, simply returns the current level. +Returns -- A FIX, the interrupt level at the time of the call (ie: + if changed, the old one). + +Example: > +Cause all interrupts to be deferred. + +INTERRUPT: Generate an artificial interrupt + +Object-type: SUBR + +Category: INTERRUPT + + INTERRUPT causes a software interrupt to happen. If the +interrupt has an IHEADER associated with it, either run the handlers +or queue them depending on the INT-LEVEL. If the IHEADER exists +return T, otherwise return #FALSE (). The first argument to INTERRUPT +is either an IHEADER, atom or string specifying the interrupt to do. + The rest of the arguments are applied to the functions associated +with the various handlers. + INTERRUPT is used either to cause a 'software' interrupt (one +identified by a name not normally in the INTERRUPTS OBLIST) or to test +a 'real' interrupt handler. + +Argument: + + Template: #DECL ("VALUE" "TUPLE" + ) + +Argument 1 -- An identifier of the interrupt to be generated, either + a STRING, ATOM, or IHEADER. +Tuple of arguments -- The appropriate arguments for the handler for + this interrupt. +Returns -- T if an IHEADER exists for this interrupt, FALSE otherwise. + +Example: +Causes a FOO interrupt if an IHEADER exists. + +INTERRUPTS: Return the INTERRUPTS OBLIST + +Object-type: SUBR + +Category: INTERRUPT + + INTERRUPTS returns the INTERRUPTS oblist. This oblist contains +atoms that are dangerous to play with. These include atoms associated +with interrupts and the special atoms LPROG , LERR and LMAP . + +Argument: + + Template: #DECL ("VALUE" OBLIST) + +Example: +Only possible invocation. + +IPC-HANDLER: Default IPC message handler + +Object-type: SUBR + +Category: INTERNAL, INTERRUPT, SYSTEM + +Reference: IPC-ON, IPC-OFF, SEND, SEND-WAIT + + IPC-HANDLER is the default IPC message handler. It prints out +the message, who it is from, the type if non-zero, and who it is to, +if not uname, jname. If the type is 1, and the message is a STRING, +it is parsed and evaluated as well as being printed out. See the +FUNCTION INQUIRE for an application of this feature. + IPC conditions are signalled with arguments as specified in the +'Template' field below. + +Argument: + + Template: #DECL ("VALUE" ANY FIX STRING STRING + "OPTIONAL" STRING STRING) + +(Arguments to any IPC condition handler) +Argument 1 -- The message received. This may be a STRING, a UVECTOR, + of UTYPE primtype FIX, or a STORAGE. +Argument 2 -- The type of the message, a FIX. The interpretation of + this is entirely up to the handler. +Arguments 3 & 4 -- STRINGs specifying whom the message is from. +(Optional) +Arguments 5 & 6 -- STRINGs specifying whom the message is to, if other + than UNAME-JNAME. +Returns -- T + +Example: + +Just prints this out. Actually you would never see or invoke this +form, since only happens at interrupt level. + +IPC-OFF: Stop listening for IPC messages + +Object-type: SUBR + +Category: SYSTEM + +Reference: IPC-ON, IPC-HANDLER, SEND, SEND-WAIT + + IPC-OFF causes the MUDDLE to stop listening for messages on the +IPC. The opposite is IPC-ON, which causes the MUDDLE to listen. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Returns -- T + +Example: +In virgin MUDDLE, disable default IPC handler, IPC-HANDLER. + +IPC-ON: Listen for IPC messages sent to a given pair + +Object-type: SUBR + +Category: SYSTEM + +Reference: IPC-OFF, SEND, SEND-WAIT, IPC-HANDLER + + IPC-ON takes two STRINGs as arguments, and listens for IPC +messages addressed to that pair. If they are received, an IPC +condition is signalled. There is a default handler for this condition +called IPC-HANDLER. See its abstract for more details. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" STRING STRING) + +(Optional) +Arguments 1 & 2 -- A pair of names to listen on, default UNAME JNAME + of the MUDDLE. +Returns -- ANY + +Example: +Usually jobs listen on their uname-jname to avoid confusion. + +ISTORAGE: Generate a STORAGE by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: STORE + + ISTORAGE Return a non-g.c. storage area of given length with +elements generated by repeated evaluation of the second argument. + Storage is normally used for the E&S, since it does not move +during garbage collection. + Note that the repeatedly EVALed argument must return something +suitable to be in a STORAGE (ie, no STRINGs) and also the results must +be of uniform type. + +Argument: + + Template: #DECL ("VALUE" STORAGE FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements. +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element + default is #LOSE *0*'s. +Returns -- Newly minted STORAGE. + +Example: > +Create a STORAGE with random contents. + +ISTRING: Generate a STRING by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: STRING + + ISTRING returns a string of given length whose elements are +generated by repeated evaluation of the second argument. Note that +the second argument must return a CHARACTER each time it is EVALed. + +Argument: + + Template: #DECL ("VALUE" STRING FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements. +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element, + default is ^@'s. +Returns -- Newly baked STRING. + +Example: 128> CHARACTER>> +Note the CHTYPEing to type CHARACTER. + +ITEM: Return the item part of an Association triad + +Object-type: SUBR + +Category: ASSOCIATION + +Reference: ASSOCIATIONS, NEXT, AVALUE, INDICATOR, + GETPROP, GET + + Given an ASOC, as returned by ASSOCIATIONS or NEXT, returns the +item part of the ASOC triad. See also INDICATOR and AVALUE, which get +the Indicator and Value parts of the triad. + +Argument: + + Template: #DECL ("VALUE" ANY ASOC) + +Argument 1 -- An ASOC whose item field to get. +Returns -- The item field of the ASOC. + +Example: + > + FOO + > + BAR + > + BLECH +ASSOCIATONS gets newest ASOC. + +ITUPLE: Generate a TUPLE by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: TUPLE + + ITUPLE returns a TUPLE (vector on the stack) of given length whose +elements are generated by repeated evaluation of the second argument. +ITUPLE is exactly like IVECTOR, except for the restriction that it may +only be applied at top-level inside the parameter list of a FUNCTION, +in AUX or OPTIONAL atom-value pairs, or at top level inside the atom- +value pairs of PROGs or REPEATs. + Note also that ITUPLE does not compile very well. + +Argument: + + Template: #DECL ("VALUE" TUPLE FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements. +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element + default is #LOSE *0*'s +Returns -- Newly stacked TUPLE. + +Example: )) + + (!.A)> +This is a valid usage of ITUPLE. + + >)) + .X> + +This is not a valid usage of ITUPLE, since the application is not at +top level of the atom-value pair. + +IUVECTOR: Generate a UVECTOR by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: UVECTOR + + IUVECTOR returns a uniform vector of given length whose elements +are generated by repeated evaluation of the second argument. + Note that the second argument must return objects all the same +type and appropriate to be part of a UVECTOR (ie: no STRINGs). + +Argument: + + Template: #DECL ("VALUE" UVECTOR FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements. +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element + (must all be of same type) default is #LOSE *0*'s. +Returns -- Newly created UVECTOR. + +Example: >>> +Powers of 2. + +IVECTOR: Generate a VECTOR by repeated Evaluation + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: VECTOR + + IVECTOR returns a vector of given length whose elements are +generated by repeated evaluation of the second argument. + +Argument: + + Template: #DECL ("VALUE" VECTOR FIX "OPTIONAL" ANY) + +Argument 1 -- FIX, number of elements. +(Optional) +Argument 2 -- ANY, expression which when evaled, gives each element + default is #LOSE *0*'s. +Returns -- Newly created VECTOR. + +Example: + ["ha" "ha" "ha" "ha" "ha"] +Comedic vector. + +JNAME: Return the Job name of the MUDDLE + +Object-type: SUBR + +Category: SYSTEM + +Reference: UNAME + + Returns the JNAME, or Job-name of the MUDDLE. This is a STRING +giving the JNAME, which is the second name of the job in which the +MUDDLE is running. The UNAME (qv) is the first. + +Argument: + + Template: #DECL ("VALUE" STRING) + +Returns -- A STRING which is the JNAME of the job. + +Example: +Only possible example. + +L=?: Is first argument less than or equal to the second ? + +Object-type: SUBR + +Category: PREDICATE, ARITHMETIC + +Reference: ==?, L?, G?, G=? + + This routine tests if the first argument is numerically less +than or equal to the second argument, returning T if it is, #FALSE() +otherwise. + +Argument: + + Template: #DECL ("VALUE" + ) + +Argument 1 -- A FIX or FLOAT. +Argument 2 -- A FIX or FLOAT. +Returns -- If arg1 <= arg2, T, else #FALSE(). + +Example: + + +These will return T. + + + +These will return #FALSE (). + +L?: Is first argument less than the second? + +Object-type: SUBR + +Category: PREDICATE, ARITHMETIC + +Reference: G?, ==?, L=? + + This routine tests if the first argument is numerically less +than the second argument. + +Argument: + + Template: #DECL ("VALUE" + ) + +Argument 1 -- A FIX or FLOAT. +Argument 2 -- A FIX or FLOAT. +Returns -- T if arg1 < arg2, #FALSE() otherwise. + +Example: + + +These will return T. + + +These will return #FALSE (). + +LEGAL?: Is the argument (TUPLE, FRAME, etc.) legal ? + +Object-type: SUBR + +Category: PREDICATE + + This routine is used to verify the legality of MUDDLE objects. +Although it works for all MUDDLE Types, it is only really useful for +the Types: TUPLE, FRAME, ACTIVATION, ENVIRONMENT, TAG, and LOCD. + For these Types it will return the Atom T if the portion of the +stack in which the given item is found is still active. Otherwise, it +will return #FALSE (). + For any other Type it simply returns the atom T. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Argument 1 -- Any object, but most interestingly, TUPLE, FRAME, TAG + ACTIVATION, ENVIRONMENT and LOCD, which are only legal if the + part of the stack they are 'in' is still active. +Returns -- T if the object is legal (for other than the types listed + above this is always the result), #FALSE() otherwise. + +Example: > +This will be False, since the activation is not legal outside the PROG. + > +However, this will be True, since the activation is legal inside the +PROG. + +LENGTH: Number of elements in a structure + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LENGTH? + + LENGTH returns the number of elements in a structure. + Be careful, LENGTH of a circular list never returns. For such +cases consider LENGTH?, which allows you to specify a maximum length +to check. + +Argument: + + Template: #DECL ("VALUE" FIX STRUCTURED) + +Argument 1 -- Any structured object. +Returns -- FIX, giving number of elements. + +Example: > + 5 +Winnage. + .X>> +Never returns, X is circular now. + +LENGTH?: Is a structure less than or equal to a given length? + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LENGTH + + LENGTH? has a very misleading name. It takes a structured +object and a FIX, and if the length of the s.o. is less than or equal +to the FIX, it returns the length. Otherwise it returns FALSE. + It is very common to see people attempt to program with this +SUBR as though it were equivalent to either <==? fix> +or alternatively fix>. Neither of these are what +it does. It is actually closer to fix>. + LENGTH? derives its specialness from the fact that it works +incrementally on LISTs, counting elements until the end is reached or +the count runs out. Thus, LENGTH? will not die horribly on circular +LISTs, which LENGTH will. + +Argument: + + Template: #DECL ("VALUE" STRUCTURED FIX) + +Argument 1 -- A Structured Object. +Argument 2 -- A FIX. +Returns -- length of s.o. if less than or equal to FIX, and + FALSE otherwise. + +Example: 2> + .FOO>> +Returns circular list. + +Will never return. + + #FALSE () +Will work. + +LINK: Give an object a synonym + +Object-type: SUBR + +Category: I/O, IDENTIFIER + + LINK gives a MUDDLE expression a synonym. It causes an object +that looks vaguely like an ATOM to be placed in an OBLIST. This type, +LINK, has the property that when it is read, its value is immediately +substituted for what was read. This is particularly useful in inter- +active work with MUDDLE, to avoid having to type long and dull streams +of characters. See 'Example' for the canonication application. + +Argument: + + Template: #DECL ("VALUE" ANY ANY STRING "OPTIONAL" OBLIST) + +Argument 1 -- The expression which is the value of the LINK, and which + is substituted whenever the LINK is read. +Argument 2 -- A STRING giving the 'PNAME' of the LINK (remember, they + are somewhat like ATOMs). +(Optional) +Argument 3 -- An OBLIST for the LINK to live on, default <1 .OBLIST>. +Returns -- Argument 1. + +Example: ""> +Links the ATOM of PNAME ^E to . + +LIST: Create a LIST + +Object-type: SUBR + +Category: DATA-HANDLING + + LIST creates a list having explicit elements. Note that this is +a SUBR, so the elements will be evaluated. + +Argument: + + Template: #DECL ("VALUE" LIST "TUPLE" ) + +Tuple of arguments -- ANY, the elements + +Example: > +equivalent to (1 2 3 4 5) + <==? .X > + #FALSE () + <==? .X (!.X)> + T + +Slight difference does exist between explicit application of LIST and +using parens. + +LISTEN: Go to a subsidiary READ-EVAL-PRINT loop + +Object-type: SUBR + +Category: I/O, PROGRAM-CONTROL + +Reference: READ, EVAL, PRINT, TTYECHO, ECHOPAIR + +LISTEN is seldom called from a program (rather ERROR is), but it +(1) ensures that .INCHAN, .OUTCHAN, and .OBLIST are reasonable +(2) does and +(3) PRINTs its arguments on .OUTCHAN +(4) PRINTs LISTENING-AT-LEVEL l PROCESS p INT-LEVEL i [as appropriate] +(5) Either does > or drops into a READ-EVAL-PRINT + loop. + +Argument: + + Template: #DECL ("VALUE" ANY "TUPLE" TUPLE) + +Tuple of arguments -- objects to print before listening +Returns -- the argument to ERRET that makes the LISTEN return + +Example: +not an overly stupid example + +LLOC: Get a Locative to the LVAL of an ATOM + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: GLOC + + LLOC of an ATOM returns a locative (type LOCD) to the LVAL of +the ATOM in the current environment, or, optionally, if a second arg +is given, the LVAL in that environment. The locative +returned is independent of future rebindings of the ATOM. IN will +always return the same value as long as that binding still exists. +Once it ceases to exist, IN of that locative is no longer LEGAL?. + +Argument: + + Template: #DECL ("VALUE" LOCD ATOM "OPTIONAL" + ) + +Argument 1 -- An ATOM +(Optional) +Argument 2 -- An Environment. If not given, the current one. +Returns -- A locative (type LOCD) to the binding specified. + +Example: )) + >>> +Will always print 3. + +LOAD: READ and EVAL every object from a channel + +Object-type: SUBR + +Category: I/O + +Reference: FLOAD, READ, EVAL + + LOAD READs and EVALs every object in the file pointed to by +its channel argument, and closes the channel. Control characters in +the file have no special meaning. An oblist can be given for looking +up atoms. + +Argument: + + Template: #DECL ("VALUE" '"DONE" CHANNEL "OPTIONAL" + ]>>) + +Argument 1 -- the channel to load from +(Optional) +Argument 2 -- (list of) oblist(s) for looking up atoms +Returns -- "DONE" + +Example: > +make yourself root-bound + +LOCATIVE?: Is an object a locative? + +Object-type: SUBR + +Category: TYPE, PREDICATE + +Reference: TYPE, STRUCTURED?, APPLICABLE? + + LOCATIVE? returns T if its argument is a locative, and FALSE if +it is not. Since most of the locative related SUBRs (such as IN) take +any sort of locative, and since there are several different types of +locatives, it is a useful SUBR. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Argument 1 -- Any MUDDLE object. +Returns -- T argument 1 is a locative, or FALSE if it is not. + +Example: > + T + > + T + > + T +All are locatives. + +LOG: Logarithms to the base 'e' + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: EXP + + LOG takes a FIX or FLOAT and returns the Logarithm to the base +e of that FIX or FLOAT, as a FLOAT. EXP is the opposite of LOG. + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- A FIX or FLOAT to take the LOG of. +Returns -- The log base e of argument 1. + +Example: > + 2.0 +Note conversion to floating point number. + +LOGOUT: Log out a top-level MUDDLE + +Object-type: SUBR + +Category: SYSTEM + +Reference: VALRET, QUIT + + This subr causes the MUDDLE it is in to attempt to log out. +This will only work if the MUDDLE is top-level. Otherwise it will +return FALSE. + +Argument: + + Template: #DECL ("VALUE" FALSE) + +Returns -- A FALSE, if it returns. + +Example: +Never returns if it wins. + +LOOKUP: Look up an ATOM in an OBLIST + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: ATOM, INSERT, OBLIST? + + LOOKUP takes the PNAME of an ATOM and an OBLIST as arguments, +and looks to see if an ATOM with that PNAME exists on the OBLIST +given. If one does, it is returned. If not, FALSE. + LOOKUP is often used in conjunction with INSERT. + +Argument: + + Template: #DECL ("VALUE" STRING OBLIST) + +Argument 1 -- A STRING which represents the PNAME of an ATOM. +Argument 2 -- An OBLIST to look up the PNAME in. +Returns -- The ATOM found or FALSE if there wasn't one. + +Example: + > + +Recommended way of safely inserting ATOMs. Guaranteed to return the +ATOM of pname "FOO". + +LPARSE: PARSE several objects into a LIST. + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: PARSE + + PARSE takes from 0 to 5 arguments. If parse is given no arguments, +it returns the first item parsed from the local value of the string +PARSE-STRING, and additionally, sets PARSE-STRING to the string having +those characters which were parsed rested off. If parse is given a +string to parse, the atom, PARSE-STRING, is rebound to the string within +that call. If the parse table argument is given to PARSE, the value of +PARSE-TABLE is rebound to it within that call to PARSE. Finally, PARSE +takes a look ahead character, which is treated as if it were logically +concatenated to the front of the string being parsed. The full callling +sequence of PARSE is: + + + + LPARSE is called exactly the same way as PARSE is called. +It tries to parse the whole string, returning a list of the items +parsed. The same action is taken with respect to optional +arguments and rebindings as is taken by PARSE. All arguments are +optional. The full calling sequence of LPARSE is: + + + + +Argument: + + Template: #DECL ("VALUE" LIST "OPTIONAL" STRING + FIX ]>> + VECTOR CHARACTER) + +(Optional arguments) +Argument 1 -- A STRING to be PARSEd. +Argument 2 -- FIX radix for number conversion. +Argument 3 -- An OBLIST or LIST of OBLISTs. +Argument 4 -- A Parse-table (VECTOR). +Argument 5 -- A CHARACTER for lookahead. +Returns -- A LIST of objects. + +Example: + (() 1 A) +Will return a list of three elements. + +LSH: Logical shift + +Object-type: SUBR + +Category: BIT-TWIDDLING, LOGICAL + +Reference: ROT + + LSH takes an object of Primtype WORD and a FIX, and it returns a +WORD containing the bits in the first argument, shifted left (positive +argument) or right (negative argument) the number of bits specified by +the second argument (mod 256). Zero bits are brought in at the end +being vacated; bits shifted out at the other end are lost. + +Argument: + + Template: #DECL ("VALUE" WORD + FIX) + +Arg 1 -- a Primtype WORD containing the bits to shift +Arg 2 -- a FIX specifying the amount to shift +Returns -- A WORD containing the shifted bits. + +Example: + #WORD *000000001000* + + #WORD *000000000000* +Primarily useful for getting fingers directly in the bits. + +LVAL: Get the local value of an atom + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: ASSIGNED?, LLOC + + LVAL gets the local value of its atom argument, relative to its +environment argument. With only one arg, it can be written .<-atom-> . + +Argument: + + Template: #DECL ("VALUE" ANY ATOM "OPTIONAL" + ) + +Argument 1 -- the atom whose local value is desired +(Optional) +Argument 2 -- the environment in which to find a value +Returns -- the value + +Example: .INCHAN +default input channel + +MAIN: Returns the main MUDDLE process + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: ME + + MAIN returns the initial MUDDLE PROCESS. This is always +PROCESS 1, and cannot be terminated. + +Argument: + + Template: #DECL ("VALUE" PROCESS) + +Returns -- The initial, PROCESS 1, PROCESS of the MUDDLE. + +Example: <==?
> +Is the PROCESS I am in the main process? + +MANIFEST: Declare the global value of an ATOM to be a constant + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: MANIFEST?, GDECL + + MANIFEST declares that the current global value of an ATOM is +a constant. Any attempt to SETG it will generate an error, assuming +that DECL-checking is on. + MANIFEST is useful to the compiler because if an ATOM is a +constant its value may be placed directly into the RSUBR, and thus +references to it will be considerably faster. Note that manifesting +a FIX will make applications of it (NTH's, that is) open-compile. + It is not usually a good idea to MANIFEST a GVAL that is large +and complex and used by several FUNCTIONs -- each FUNCTION will get +a copy of it in the result RSUBR. + +Argument: + + Template: #DECL ("VALUE" 'T "TUPLE" ) + +Tuple of arguments -- ATOMs whose GVALs are constants. +Returns -- T. + +Example: + + +Most common use of MANIFEST. + +MANIFEST?: Has an ATOM been MANIFESTed? + +Object-type: SUBR + +Category: DATA-HANDLING, PREDICATE + +Reference: MANIFEST, UNMANIFEST + + MANIFEST? returns T if its argument (an ATOM) has been MANIFESTed, +and #FALSE () otherwise. + +Argument: + + Template: #DECL ("VALUE" ATOM) + +Argument 1 -- An ATOM. +Returns -- T if it is MANIFEST, FALSE if it is not. + +Example: + + + T + + + #FALSE () +Make it a constant, then make it not a constant. + +MAPF: Map routine onto elements of structured objects. + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: MAPR, MAPRET, MAPSTOP, MAPLEAVE + + This is used to map, or apply, a routine to succesive elements +of one or more structured objects. This routine is the second argument +to MAPF and it must take n args, where n is the number of structured +args supplied to the MAPF. In addition another routine can be supplied +to be applied to the results of all of the previous applications. +Usually this routine will take an arbitrary number of arguments. This +secondary routine is given as the first argument to MAPF. However, if +#FALSE () is supplied as the first argument, this indicates that no +such additional application is desired. + Finally the desired structured arguments for mapping are supplied +after the first two arguments. + The primary routine is repeatedly applied to a bunch of the +successive elements from all the structured objects supplied. The +bunch consists of exactly one element from each of the structured +objects. + The repeated application continues until one of the structured +objects runs out of elements for the application, OR until the MAPF is +stopped within the application by use of the SUBRs MAPSTOP or MAPLEAVE. + Note that at least one such structured object must be supplied. + The value returned by the MAPF is the result returned by the +application of the additional routine, if any. + If the additional routine is not supplied (the first arg is +#FALSE ()), the value returned is the result of the last application +of the primary routine to the last bunch of elements. + +Argument: + + Template: #DECL ("VALUE" ANY APPLICABLE + "TUPLE" ) + +Argument 1 -- An applicable object to be used after the mapping phase + is finished, or a FALSE, to simply finish. +Argument 2 -- An applicable object to apply to the elements of the + structured objects. +Tuple of arguments -- At least one structured object, whose elements + will be passed in order as arguments to the second argument of + MAPF. +Returns -- Either the result of APPLYing the first argument to the + stacked results of the repeated application of the second + argument, or the last thing returned by applying the second + argument, or #FALSE () if all of the structured objects were + empty. + +Example: +This will perform the element-wise sum of two lists + +MAPLEAVE: Leave from the current MAPF/MAPR with a given value. + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: MAPF, MAPR, MAPRET, MAPSTOP + + Leaves from the current MAPF/MAPR without doing the normal +application of a routine to the stacked args. If the optional argument +to MAPLEAVE is supplied, it will be the result of the MAPF/MAPR. + If no such argument is supplied the Atom T will be used instead. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ANY) + +(Optional) +Argument 1 -- The result of the MAPF/R. If not given, T will be used. +Returns -- Nothing. Terminates a MAPF/R. + +Example: + )>> + .STRUC> +This example will find and return the first non-zero element of STRUC + +MAPR: Map routine onto RESTs of structured objects. + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: MAPF, MAPRET, MAPSTOP, MAPLEAVE + + This is used to map, or apply, a routine to succesive RESTs of +one or more structured objects. + Works just like MAPF, see its description, except that instead +of applying the second arg to the elements of the structured objects, +MAPR applys the second arg to the successive RESTs of the structured +objects. This makes it possible to change the arguments that will be +passed to future applications of the second argument before they are +reached. + +Argument: + + Template: #DECL ("VALUE" ANY APPLICABLE + "TUPLE" ) + +Argument 1 -- FALSE or an applicable object to apply to the results + of the repeated applications of the second argument. +Argument 2 -- An applicable object to apply repeatedly to the RESTs of + the remaining arguments. +Tuple of arguments -- At least one structured object to supply RESTs + for the second argument. +Returns -- The result of applying argument 1 to the results of the + repeated applications of argument 2, or the result of the last + such application if argument 1 is FALSE, or #FALSE () if all the + structures were empty and no applications were performed. + +Example: + 2>>> + .STRUC> +This will change the structure STRUC to contain double its values. + +MAPRET: Return an arbitrary number of objects to a MAPF/MAPR. + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: MAPF, MAPR, MAPSTOP, MAPLEAVE + + This routine is used to return an arbitrary number of elements +to the current MAPF/R. An invocation of MAPRET ends the current +application of the second argument of MAPF/R. The arguments to MAPRET +are added to the objects being collected to be passed as arguments to +the application of the first argument to MAPF/R. + MAPRET makes it possible to return no arguments or several argu- +ments from one of these intermediate applications. + +Argument: + + Template: #DECL ("VALUE" ANY "TUPLE" ) + +Tuple of arguments -- Any number of objects to be added to the group + of potential arguments to the ending application of a MAPF/R. +Returns -- Nothing, really, as the application is ended by MAPRET. + +Example: +This is used when one desires to return nothing. + +MAPSTOP: Stop looping of the current MAPF/MAPR and do the application. + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: MAPF, MAPR, MAPRET, MAPLEAVE + + First this Subr acts like MAPRET and causes an arbitrary number +of MUDDLE objects to be stacked for the current MAPF/MAPR. Then it +stops the normal looping operation of this MAPF/MAPR and causes the +normal application of the previously saved applicative object to the +current group of stacked objects. + The result of this application is then returned as the result +of the MAPF/MAPR. + +Argument: + + Template: #DECL ("VALUE" ANY "TUPLE" ) + +Tuple of arguments -- Any number of arguments to add to the stacked + objects that the final application will apply to. +Returns -- Nothing, terminates MAPF/R looping. + +Example: > 0> + )> + .X> + .STRUC>> + +This example produces a list out of the first ten elements of STRUC. +If there are fewer than ten elements in STRUC, then all are used. + +MAX: Maximum of a set of numbers + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: MIN + + MAX (Maximum) takes any number of FIXes or FLOATs, and returns +the greatest as its result. If any of the arguments are FLOATs, the +result will be FLOAT. If no argument is given, MAX returns the least +floating-point number. If one argument is given, MAX returns that +argument. + +Argument: + + Template: #DECL ("VALUE" + "TUPLE" ]>) + +(Optional) +Tuple of arguments -- FIXes and FLOATs +Returns -- FIX or FLOAT, floating is contagious. + +Example: + 2.0 +Floating is contagious. + +ME: Returns the process id of the the current process + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: MAIN, RESUMER + + ME is similar to MAIN, except that it returns the PROCESS ID of +the process it is evaled in, rather than the initial process. + +Argument: + + Template: #DECL ("VALUE" PROCESS) + +Returns -- The PROCESS Id of the PROCESS it is EVALed in. + +Example: <==?
> +Am I the main process? + +MEMBER: Is there a similar object in a structure? + +Object-type: SUBR + +Category: PREDICATE + +Reference: MEMQ, =? + + MEMBER is used to find a structural copy of an object in a +structure. It takes as arguments and object and a structure. Each +element of the structure is examined in turn, using =?, and if one of +them is =? to the object, the structure is returned, RESTed down to a +point where its first element is the copy. + If no element is structurally identical to the first argument, +#FALSE() is returned. + +Argument: + + Template: #DECL ("VALUE" ANY STRUCTURED) + +Argument 1 -- Any MUDDLE object. +Argument 2 -- A STRUCTURED object. +Returns -- Either the structure RESTed down to the copy, or FALSE if + there is no copy. + +Example: + [69 81] +MEMQ would do the same for this example. + +But not for this example. Different strings are =? not ==?. + +MEMQ: Is there an identical object in a structure? + +Object-type: SUBR + +Category: PREDICATE + +Reference: MEMBER, ==? + + MEMQ is used to find a copy of an object in a structure. It +takes as arguments and object and a structure. Each element of the +structure is examined in turn, using ==?, and if one of them is ==? +to the object, the structure is returned, RESTed down to a point +where its first element is the copy. + If no element is identical to the first argument, #FALSE() is +returned. + +Argument: + + Template: #DECL ("VALUE" ANY STRUCTURED) + +Argument 1 -- Any MUDDLE object. +Argument 2 -- A STRUCTURED object. +Returns -- Either the structure RESTed down to the copy, or FALSE if + there is no copy. + +Example: + [69 81] +The copy is now the first element. + +MIN: Minumum of a set of numbers + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: MAX + + MIN (Minimum) takes any number of FIXes or FLOATs, and returns +the least as the result. If no argument is given, MIN returns the +greatest floating-point number; if one argument is given, MIN returns +that argument. + If any of the arguments is a FLOAT, the result will be a FLOAT, +no matter what type it was originally. + +Argument: + + Template: #DECL ("VALUE" + "TUPLE" ]>) + +(Optional) +Tuple of arguments -- FIXes and FLOATs +Returns -- FIX or FLOAT, depending on whether any args were FLOAT. + +Example: + 1.0 +Takes any number of args + +MOBLIST: Create an OBLIST + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: BLOCK + + MOBLIST creates an oblist--repository for atoms. It is not put +anywhere automatically. If the user wants it in his oblist path, that +must be done explicitly, as in the example. + Note that it is the location of the ATOM passed as argument to +MOBLIST that determines where the new OBLIST will exist. + An association is automatically created for the oblist under the +atom and the indicator OBLIST. Note that this association is checked +by MOBLIST, and a new OBLIST will not be created if one already exists +with the name given. + +Argument: + + Template: #DECL ("VALUE" OBLIST ATOM "OPTIONAL" FIX) + +Argument 1 -- ATOM, name of OBLIST. +(Optional) +Argument 2 -- FIX, number of hashing buckets, default 13 +Returns -- New OBLIST, or old one if one already exists with that name. + +Example: !.OBLIST))) + AN-ATOM!-MY-OBLIST + > +The oblist is placed in the path by the setting of the atom OBLIST + +MOD: Take a number modulus another number + +Object-type: SUBR + +Category: ARITHMETIC + + MOD (Modulus) takes two FIXes and returns the remainder when the +first is divided by the second. This is the standard arithmetic Mod +operation. + +Argument: + + Template: #DECL ("VALUE" FIX FIX FIX) + +Argument 1 -- A FIX. +Argument 2 -- A FIX. +Returns -- FIX, remainder of argument 1 divided by argument 2. + +Example: 30> +How to get a random number between 0 and 30. + +MONAD?: Will NTH and REST fail on this object? + +Object-type: SUBR + +Category: PREDICATE + +Reference: STRUCTURED?, EMPTY? + + MONAD? returns T if and only if NTH and REST will fail on the +object passed as its argument. Obviously this is true of any non- +structured object, but additionally, MONAD? returns T if its argument +is an empty structured object. + MONAD? is thus similar to ORing > and +. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Argument 1 -- Any MUDDLE object. +Returns -- T if NTH and REST will not work on the object, FALSE if + they will work. + +Example: > + > + +Result is the same for these two forms. + +N==?: Test for physical non-identity of two objects. + +Object-type: SUBR + +Category: PREDICATE + +Reference: =?, ==? + + N==? is the logical complement of ==?. For every case in which +==? would return T, N==? returns #FALSE() and vice versa. + ==? tests two objects for physical identity. For ==? to return +T (true), the two objects must have the same identical type-value pair. +For example, two STRINGs typed in from the console will not be ==?, but +two ATOMS, FIXes, or nil LISTs will be. + If the two objects are not the same, ==? returns FALSE. + +Argument: + + Template: #DECL ("VALUE" ANY ANY) + +Argument 1 -- Any object. +Argument 2 -- Another object. +Returns -- T if the two objects are different objects, FALSE otherwise. + +Example: + T +These two STRINGs look identical, but are not. + +N=?: Test for structural non-identity of two objects. + +Object-type: SUBR + +Category: PREDICATE + +Reference: =?, N==? + + N=? is the logical complement of =?. For every case in which +N==? returns T, =? would have returned FALSE, and vice versa. + =? is a less stringent, but more expensive, test for identity +than ==?. It also takes two objects as arguments, but tests only for +structural identity of the objects, rather than physical identity. If +two objects print the same, they will be =? to each other, except for +numeric fuzz. For example, two STRINGs typed in from the console will +be =? to each other, but not ==?. Any objects that are ==? will also +be =?, and if ==? applies, it should be used. =? is much more +expensive than ==?, in general, as it must test an entire structure +piece by piece. + =? returns T if the objects are structurally identical, and FALSE if +they are not. + +Argument: + + Template: #DECL ("VALUE" ANY ANY) + +Argument 1 -- Any object. +Argument 2 -- Any other object. +Returns -- T if the arguments are not structurally equal, FALSE if they + are. + +Example: > > + #FALSE () +If the test were =?, the result would be T. + +NETACC: Network Listening socket accept + +Object-type: SUBR + +Category: NETWORK + +Reference: OPEN, NETSTATE, NETS + + NETACC takes a network listening socket and accepts a connection. +It will return FALSE if the connection is in the wrong state. + +Argument: + + Template: #DECL ("VALUE" CHANNEL) + +Argument 1 -- A Network channel (a listening socket). +Returns -- The channel, or FALSE if it is in the wrong state. + +Example: > +Accept the listening socket. + +NETS: Force out the Network buffers of a Network channel + +Object-type: SUBR + +Category: NETWORK + +Reference: OPEN, NETSTATE, NETACC + + NETS forces any system buffered network output to be sent. The ITS +system normally does this every 1/2 second anyway. Note that this is +similar to the function of BUFOUT for normal channels but more thorough. + +Argument: + + Template: #DECL ("VALUE" CHANNEL CHANNEL) + +Argument 1 -- A Network channel. +Returns -- The Network channel, with buffers output. + +Example: +What else? + +NETSTATE: Return the state of an ARPA-net connection + +Object-type: SUBR + +Category: NETWORK + +Reference: OPEN, NETACC, NETS + + NETSTATE returns a UVECTOR of three elements. The first is the +state of the connection, the second is a code specifying why a connection +was closed, and the last is the number of bits available for input. + The meaning of the state and close codes is specified in the +documentation of the ITS NCP (Network Control Program). + +Argument: + + Template: #DECL ("VALUE" CHANNEL) + +Argument 1 -- A MUDDLE channel open to the NETWORK. +Returns -- A UVECTOR containing 3 FIXes, a connection state, a close + code, and the number of bits available on the connection for + input. + +Example: > +Give state of a network channel open for listening. + +NEWTYPE: Create a new MUDDLE type + +Object-type: SUBR + +Category: TYPE-DEFINITION + +Reference: ALLTYPES + + NEWTYPE creates and specifies a new MUDDLE type. It takes the +name of the new type (an ATOM), the primtype of the new type (also an +ATOM), and optionally, the DECL of the new type. + A new type will print as: + + # + +For example, a would make FOOs that print as: + + #FOO () + +The new type is added to the type vector (as returned by ALLTYPES), +and becomes legal to DECL, etc. Note that a newtype is not given the +EVALTYPE, APPLYTYPE and so on of its primtype! If you wish it to have +these you must explicitly give them to it. For example, the type FOO +above, when EVALed, will not generate a new FOO with the elements +EVALed. To cause this to happen you must say . + The third (optional) argument allows you to more strongly specify +the makeup of the new type. It is a DECL-body, and it will be assoc- +itated with the type-name under the indicator DECL. Each type an +object is CHTYPEd to the newtype it will be checked against the DECL, +and ERROR will occur if they don't match. + NEWTYPE returns the ATOM given as the name of the new type. + +Argument: + + Template: #DECL ("VALUE" ATOM ATOM ATOM + "OPTIONAL" >) + +Argument 1 -- The ATOM name of the new type. +Argument 2 -- The ATOM name of the primtype of the new type. +(Optional) +Argument 3 -- The DECL of the new type. +Returns -- The name of the new type (arg 1). + +Example: [ + "Simple newtype" + BAR [REST FIX FLOAT]>> + "More strongly specified, even recursive."] + +NEXT: Access the next Association in the Association chain. + +Object-type: SUBR + +Category: ASSOCIATION + +Reference: ASSOCIATIONS, AVALUE, INDICATOR, ITEM + + NEXT returns the next Association in the association chain, given +an ASOC. It is used to access associations further down the chain +than the first, which must be gotten with ASSOCIATIONS. Applying NEXT +to the last association in the chain will return FALSE. + ASSOCIATIONS gives the user access to the association chain in +much the same way as FRAME gives access to the stack. ASSOCIATIONS +returns the first association triad (item, indicator, value) in the +chain, as a type ASOC, which looks, but doesn't behave like, a LIST. + An ASOC may be passed to ITEM, INDICATOR, or AVALUE to retrieve +the elements of a triad, or to NEXT to retrieve the next association +in the chain. + +Argument: + + Template: #DECL ("VALUE" ASOC) + +Argument 1 -- An ASOC, as returned by NEXT or ASSOCIATIONS. +Returns -- The next association in the association chain, or FALSE if + NEXT was passed the last association. + +Example: > +Get second association in chain. + +NEXTCHR: Return the next input character from an I/O channel + +Object-type: SUBR + +Category: I/O + +Reference: READCHR + + NEXTCHR returns the character which READCHR will return the +next time it is called. Successive calls, with no intervening input +operations, all return the same thing. + +Argument: + + Template: #DECL ("VALUE" "OPTIONAL" CHANNEL + ANY) + +(Optional) +Argument 1 -- the channel +Argument 2 -- object to eval and return at end of file +Returns -- the next character (-1 if empty STY device) + +Example: + !\ +what you get if called by itself + +NOT: Change the truth value of an object to its complement + +Object-type: SUBR + +Category: LOGICAL, CONDITIONAL + +Reference: AND, OR, COND + + NOT complements the truth value of its argument. If its +argument was a FALSE, NOT returns T, if its argument was non-FALSE, +NOT returns a FALSE. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Argument 1 -- ANY object. +Returns -- The logical complement of the truth value of the object. + +Example: > + #FALSE () +Note the loss of detail in complementing the complement. + +NTH: Get the Nth element of a structure + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: APPLY + + NTH returns the n'th element of a stucture. It takes the +structure and the number of the element to return, where 1 is the +first element, and so on. + If the structure does not have an Nth element, an ERROR occurs. +LENGTH can be used to help find out if a structure has an Nth element. + Note that NTH is cheap on VECTORs, UVECTORs and such, and +expensive on LISTs. + An application of a FIX, or something that EVALs to a FIX, to +a structure is equivalent to an application of NTH, assuming that the +order of evaluation is not important: + + + and <1 .X> +are equivalent, but + + >> + and <> .X> + +are not equivalent, the order of evaluation makes a difference. + +Argument: + + Template: #DECL ("VALUE" ANY STRUCTURED "OPTIONAL" FIX) + +Argument 1 -- A Structured object. +(Optional) +Argument 2 -- A FIX, the element number to return, default 1. +Returns -- The contents of the Arg-2th element of the structure. + +Example: <2 (4 5 6)> + + +The first is equivalent to the second as long +as order of evaluation makes no difference. + +OBLIST?: Return the OBLIST that contains a given ATOM + +Object-type: SUBR + +Category: IDENTIFIER, CONDITIONAL + +Reference: INSERT, ATOM, REMOVE + + OBLIST? returns the OBLIST that contains a given ATOM, or FALSE +if the ATOM is not on an OBLIST (hence the ?). It is usually used for +the first purpose (to find out what OBLIST an ATOM is on). + +Argument: + + Template: #DECL ("VALUE" ATOM) + +Argument 1 -- An ATOM. +Returns -- Either the OBLIST that ATOM is on, or FALSE if it is not on + any OBLIST. + +Example: +...SOME OBLIST.... + > + #FALSE () + +If you type in the ATOM as part of the form, it will naturally be on +an OBLIST. + +OFF: Turn off an interrupt IHEADER or HANDLER + +Object-type: SUBR + +Category: INTERRUPT + + OFF permits the user to remove an IHEADER or HANDLER. OFFing the +IHEADER causes MUDDLE to completely ignore the interrupt and OFFing a +HANDLER causes the function associated with that particular HANDLER +not to be run. + OFF may also be used with strings or atoms to identify IHEADERs +as in EVENT. As usual "CHAR" requires the channel as an additional +argument, and "READ" and "WRITE" require the locative as an +additional argument. + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" + ) + +Argument 1 -- An IHEADER, HANDLER, STRING or ATOM identifying exactly + what interrupt or interrupt handler to remove. +(Optional) +Argument 2 -- If the CHAR interrupt is the one being OFFed, the + channel is also needed with which the interrupt was paired. + If the READ or WRITE interrupt is the one being OFFed, the + locative is also needed with which the interrupt was paired. +Returns -- The OFFed IHEADER or HANDLER, if successful, or FALSE if + there was nothing to remove. + +Example: +Turns off the CLOCK interrupt. + +OFFSET: Create an OFFSET + +Object-type: SUBR + +Category: STRUCTURES + +Reference: NTH, INDEX, GET-DECL, PUT-DECL + + An OFFSET is a "frozen" NTH. Given a fix and a DECL, it creates +an APPLICABLE object which may be applied to structures to get the fixth +element or to a structure and an object to change the fixth element to +be the object. + +Argument: + + Template: #DECL ("VALUE" OFFSET FIX ) + +Argument 1 -- The element of the structure the offset refers to. +Argument 2 -- A DECL which describes the structure (the entire structure, + not the element) the offset is an offset into. +Returns -- The OFFSET. + +Example: >> + %> + + +ON: Create and turn on an interrupt handler + +Object-type: SUBR + +Category: INTERRUPT + +Reference: OFF, EVENT, HANDLER + + ON is equivalent to a call to EVENT followed by a call to HANDLER. +It causes an interrupt handler to be created and added to the list of +handlers for a given interrupt. + + + +is equivalent to + + ,FOO ,P> + + In the case of "CHAR" or "READ"/"WRITE", the channel or +locative is the last argument. In this case the process argument may +be zero and is equivalent to no process being given. + +Argument: + + Template: #DECL ("VALUE" HANDLER APPLICABLE FIX "OPTIONAL" + ) + +Argument 1 -- The name of the interrupt. Note that if it is not one + of the existing interrupts in the INTERRUPTS OBLIST, no ERROR, + the interrupt is assumed to be a software one! +Argument 2 -- An APPLICABLE, to be called with the appropriate number + of arguments when the interrupt occurs. +Argument 3 -- The priority of the interrupt. +(Optional) +Argument 4 -- the PROCESS in which to run the interrupt, 0 means the + running one. +Argument 5 -- If a "CHAR" interrupt, the CHANNEL. + If a "READ" or "WRITE" interrupt, the LOCATIVE. +Returns -- The HANDLER for the interrupt. + +Example: > 1> + +OPEN-NR: Create and open an I/O channel without changing file's reference date + +Object-type: SUBR + +Category: I/O + +Reference: OPEN + + OPEN-NR is the same as OPEN (q.v.), except that the date of last +reference of the opened file is not changed. + +Argument: + + Template: #DECL ("VALUE" > + "OPTIONAL" STRING "TUPLE" TUPLE) + +(Optional) +Argument 1 -- mode +Tuple of arguments -- 'file specification' +Returns -- channel or false giving reason for failure & filename + +Example: +so it will be reaped sooner + +OPEN: Create and open an I/O channel + +Object-type: SUBR + +Category: I/O + +Reference: CHANNEL, RESET + + OPEN creates a channel for subsequent input or output. +All arguments are optional. The first arg is the mode for the channel, +a string from the list ("READ" "PRINT" "READB" "PRINTB" "PRINTO" +"DISPLAY"), default "READ". The other arguments specify the file +or other 'external storage medium' involved. These can be: + . a string giving the complete file name + . several strings giving name1, name2, device, and directory + . the string "INT:" and a function, a source or sink for characters + . two fixes, the string "NET", and two more fixes +Omitted parts of the file specification follow these defaults: + , if any, else "INPUT" + , if any, else ">" + , if any, else "DSK" + , if any, else the 'working directory' +For more details, see the manual, SYS.11.01. + +Argument: + + Template: #DECL ("VALUE" > + "OPTIONAL" STRING "TUPLE" TUPLE) + +(Optional) +Argument 1 -- mode +Tuple of arguments -- 'file' specification +Returns -- a channel or a false giving the reason for failure & filename + +Example: +Make a channel for line-printer output. + +OR: Logical OR of its arguments. + +Object-type: FSUBR + +Category: PREDICATE, PROGRAM-CONTROL + +Reference: COND, AND, OR? + + OR is an FSUBR that evaluates its arguments, one by one, until +either one of them returns a non-FALSE or it runs out of arguments. + The fact that it is an FSUBR means that it can be used as a +miniature COND. A construct of the form will +allow 'thing' to be executed only if 'preconditions' is false. In +combination with AND, fairly powerful constructs can be generated. + OR takes any number of arguments, returning either the result of +its last evaluation (#FALSE () if no arguments were given) or the +non-FALSE that caused it to complete. + +Argument: + + Template: #DECL ("VALUE" "ARGS" LIST) + +List of arguments -- ANY evalable objects. +Returns -- Terminating non-FALSE or FALSE if all elements were FALSE. + +Example: > >> + +This construct only attempts to insert FOO in the ROOT if it is not +already there, avoiding the possibility of an ERROR. + +OR?: Logical OR of its arguments, evaluated at call time + +Object-type: SUBR + +Category: PREDICATE, PROGRAM-CONTROL + +Reference: AND?, OR, MAPF, MAPR + + OR is a SUBR that looks at its arguments, one by one, until +either one of them is a non-FALSE or it runs out of arguments. + The fact that it is a SUBR means that it can be used as a +first argument to MAPF or MAPR. + OR takes any number of arguments, returning either +its last argument (#FALSE () if no arguments were given) or the +non-FALSE that caused it to complete. + +Argument: + + Template: #DECL ("VALUE" "TUPLE" TUPLE) + +Tuple of arguments -- ANY objects. +Returns -- Terminating non-FALSE or FALSE if all elements were FALSE. + +Example: > .VECTOR> +Is any element of VECTOR positive? + +ORB: Bitwise logical OR + +Object-type: SUBR + +Category: ARITHMETIC, BIT-TWIDDLING + +Reference: EQVB, XORB, ANDB + + ORB takes any number of objects of Primtype WORD, and returns +a WORD containing the bitwise logical OR of the arguments. + +Argument: + + Template: #DECL ("VALUE" WORD + "TUPLE" ]>) + +Tuple of arguments -- Objects of primtype WORD to be ORed together. +Returns -- A WORD containing the bitwise OR of the arguments. + +Example: + #WORD *000000042261* +Primarily useful for getting fingers directly in the bits. + +OVERFLOW: Enable or disable overflow error + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: +, -, *, / + +OVERFLOW disables or enables -- if its argument is a FALSE or not, +respectively -- overflow and underflow errors caused by arithmetic +SUBRs. Initially these errors are enabled. + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" ) + +(Optional) +Argument 1 -- whether or not to enable over/underflow errors +Returns -- the previous state, initially true, or current state if no arg + +Example: +the initial state + +PARSE: Parse a string into a MUDDLE object + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: UNPARSE, LPARSE + + Parse a string into a MUDDLE object, just like reading from a +string instead of a channel. + PARSE takes from 0 to 5 arguments. If parse is given no arguments, +it returns the first item parsed from the local value of the string +PARSE-STRING, and additionally, sets PARSE-STRING to the string having +those characters which were parsed rested off. If parse is given a +string to parse, the atom, PARSE-STRING, is rebound to the string within +that call. If the parse table argument is given to PARSE, the value of +PARSE-TABLE is rebound to it within that call to PARSE. Finally, PARSE +takes a look ahead character, which is treated as if it were logically +concatenated to the front of the string being parsed. The full calling +sequence of PARSE is: + + + + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" STRING + FIX ]>> + VECTOR CHARACTER) + +(Optional) +Argument 1 -- STRING to parse, if not given, LVAL of PARSE-STRING. +Argument 2 -- FIX, radix for number conversion. +Argument 3 -- An OBLIST or LIST of OBLISTs. +Argument 4 -- A parse-table. +Argument 5 -- A prefix character. +Returns -- A MUDDLE object. + +Example: "> +Returns the FORM <+ 1 2>. + +PCODE: Create pointer to pure RSUBR code + +Object-type: SUBR + +Category: UTILITY + + PCODE returns a pure code vector for an RSUBR, given a name +in the internal table of pure RSUBRs and the offset in the block of +code where the RSUBR entry point is. It is most often seen when +a pure code vector is output, as %. + +Argument: + + Template: #DECL ("VALUE" PCODE STRING FIX) + +Argument 1 -- name in pure-RSUBR table +Argument 2 -- offset in the code +Returns -- a pure code vector + +Example: +Calls like this fill FBIN files. + +PNAME: Create a distinct STRING which is the name of an ATOM + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: ATOM, INSERT, SPNAME + + PNAME takes as argument an ATOM, and returns the STRING which +is the PNAME (printing name) of that ATOM. This name does not include +any oblist trailers or the backslashes that are sometimes printed out +for the convenience of the reader. Several other SUBRs, notably +INSERT, LOOKUP, and ATOM, use the pname of atoms as arguments. + PRINC of the PNAME of an ATOM is one guaranteed way of printing +an ATOM-name without trailers, backslashes, or quotes. + +Argument: + + Template: #DECL ("VALUE" STRING ATOM) + +Argument 1 -- An ATOM. +Returns -- A STRING which contains the atom's pname. + +Example: + +Just three spaces, no backslashes, no trailers. + +PRIMTYPE-C: Get a primtype code for an object + +Object-type: SUBR + +Category: TYPE-DEFINITION + +Reference: PRIMTYPE TYPE-C + + PRIMTYPE-C returns the 'storage type code' for an object. +This gives no more info than PRIMTYPE (q.v.), except for TEMPLATEs: +each TYPE of TEMPLATE has a different PRIMTYPE-C. + +Argument: + + Template: #DECL ("VALUE" PRIMTYPE-C ATOM) + +Argument 1 -- the type to get a code for +Returns -- a 'storage type code' + +Example: > +returns a 'storage type code' for my template + +PRIMTYPE: Return the primitive type of an object + +Object-type: SUBR + +Category: TYPE + +Reference: UTYPE, TYPE, TYPEPRIM + + PRIMTYPE is applied to any MUDDLE object to return an ATOM which +is the name of the PRIMITIVE type of that object. TYPE, which is +similar, returns the type of the object given. TYPEPRIM returns the +primitive type given the name of the type. + +Argument: + + Template: #DECL ("VALUE" ATOM ANY) + +Argument 1 -- Any MUDDLE object. +Returns -- ATOM, the name of the primitive type of the argument. + +Example: + FIX + + WORD + +PRIMTYPE will obviously return the same result for a larger class of +objects than will TYPE. + +PRIN1: Print an object on an I/O channel + +Object-type: SUBR + +Category: I/O + +Reference: PRINT + +PRIN1 is exactly like PRINT (q.v.) except that it omits the new-line +before and the space afterward. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" CHANNEL) + +Argument 1 -- the object +(Optional) +Argument 2 -- the output channel, default .OUTCHAN +Returns -- the object + +Example: +boring example, sorry + +PRINC: Print an object on an I/O channel without indicators + +Object-type: SUBR + +Category: I/O + +Reference: PRIN1, PRINT + +PRINC is exactly like PRIN1 (q.v.) except that it omits "s around +strings, !\s before characters, and \s and trailers for atoms. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" CHANNEL) + +Argument 1 -- the object +(Optional) +Argument 2 -- the output channel, default .OUTCHAN +Returns -- the object + +Example: + + > +Amaze your friends! + +PRINT: Print an object on an I/O channel on a new line + +Object-type: SUBR + +Category: I/O + +PRINT outputs the character representation (unparsing) of its first +argument, preceded by carriage-return/line-feed and succeeded by a space. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" CHANNEL) + +Argument 1 -- the object +(Optional) +Argument 2 -- the output channel, default .OUTCHAN +Returns -- the object + +Example: +not a very wonderful example + +PRINTB: Write binary words on an I/O channel + +Object-type: SUBR + +Category: I/O + +PRINTB writes the entire contents of its first argument into a given +channel, as 36-bit binary words. + +Argument: + + Template: #DECL ("VALUE" + < [REST ]> CHANNEL) + +Argument 1 -- the buffer whose contents to write +Argument 2 -- the output channel, open in PRINTB or PRINTO mode +Returns -- arg1 + +Example: +Can't use a console channel. + +PRINTSTRING: Write contents of string on an I/O channel + +Object-type: SUBR + +Category: I/O + +PRINTSTRING writes the entire contents or initial characters of a +string on a given channel. The output appears identical to that +produced by PRINC. + +Argument: + + Template: #DECL ("VALUE" FIX STRING "OPTIONAL" CHANNEL FIX) + +Argument 1 -- the string to write out +(Optional) +Argument 2 -- the output channel, default .OUTCHAN +Argument 3 -- number of characters to output, default all +Returns -- number of characters output + +Example: > +Suck out the echoed characters on your pseudo-console. + +PRINTTYPE: Change or examine the way a TYPE is PRINTed + +Object-type: SUBR + +Category: TYPE-MANIPULATION, PROGRAM-CONTROL, I/O + +Reference: PRINT + + Changes the way a specific type is PRINTed, by either mapping +it into another type, or giving an explicit method via an APPLICABLE. + If a type is given, the type being changed will be PRINTed in the +same manner as that type. Note that in this case the two types must +be of the same PRIMTYPE or else ERROR. + If an APPLICABLE is given, it should take one argument, which +will be the object being PRINTed. If ,PRINT is given, the type will +receive no special treatment in printing. + If no second argument is given, PRINTTYPE returns the last arg +given it for that TYPE, or else #FALSE () if the type is receiving no +special treatment in printing. + +Argument: + + Template: #DECL ("VALUE" ATOM "OPTIONAL" + ) + +Argument 1 -- The type whose PRINTTYPE to change or examine. +(Optional) +Argument 2 -- A TYPE (which means 'Print like this type'), or an + APPLICABLE (meaning 'use this when you PRINT this type'). +Returns -- The TYPE which was changed or, if no arg 2, the way the + TYPE is being printed. + +Example: +Combine with example for EVALTYPE and make MUDDLE look like LISP. + >> +Confuse your friends. + +PROCESS: Create a new PROCESS + +Object-type: SUBR + +Category: TYPE-MANIPULATION, PROCESS-CONTROL + +Reference: RESUME, STATE + + PROCESS creates a new PROCESS with a given start up function. +This must be an APPLICABLE of one argument, which must be evaled. +If the starter of a PROCESS ever returns a value, that PROCESS is DEAD. + Note that creating a PROCESS will often cause a GC. + +Argument: + + Template: #DECL ("VALUE" PROCESS APPLICABLE) + +Argument 1 -- An APPLICABLE which takes a single evaluated argument. +Returns -- A new PROCESS. + +Example: + > +Creates a process which is a read-eval-print loop like
. + + RUNABLE +Means P has never run. + +Starts it. + +To treat a process like a simple function: + >> +Starts it, returns the result of applying arg1 (T) to the function, +and then dies. + +PROG: Execute sequential expressions + +Object-type: FSUBR + +Category: PROGRAM-CONTROL + +Reference: REPEAT + + This FSUBR is used to bind variables and sequentially execute +MUDDLE expressions and perform appropriate GOs, RETURNs, and AGAINs. + If the first argument to PROG is an atom, it is bound to the +Activation of the PROG. + Otherwise the next object must be the argument list of the PROG. +It contains either Atoms or Lists of an Atom and a MUDDLE expression. +Each single Atom in the argument list is Bound but not Assigned. Each +'listified' Atom is Bound and Assigned to the evaluation of the MUDDLE +expression which appears with it. + If the next argument to the PROG is of type DECL, it is used as +the declaration for the variables of the PROG. + The remaining arguments, at least one must exist, constitute the +body of the PROG. They are executed in sequence with the value of the +last being the value for the entire PROG, unless a RETURN from the +activation of the PROG (explicit or with only one argument) is done. + +Argument: + + Template: #DECL ("VALUE" ANY "ARGS" ) + +Optional argument 1 -- An ATOM, to bind the activation of the PROG to. +Argument 2 -- A parameter LIST. +Optional argument 3 -- The DECL of the PROG. +Remainder of arguments -- At least one object, to be sequentially evaled. +Returns -- The last thing evaled in the PROG, or the argument to a + RETURN within the PROG. + +Example: )) + + )>> +This will FOO only if the file FOO BAR exists. + +PURIFY: Purify objects everywhere + +Object-type: SUBR + +Category: UTILITY + +Reference: SUBSTITUTE, FSAVE, RESTORE + + PURIFY causes a mini-GC, like SUBSTITUTE, resulting in its args +becoming pure and sharable, and ignored by the garbage collector. +No arg can live on the stack or be of primtype process, locd, or +asoc. Sharing between jobs/forks actually occurs after FSAVE/RESTORE. + +Argument: + + Template: #DECL ("VALUE" ANY "TUPLE" TUPLE) + +Tuple of Arguments -- the objects to be purified, not RSUBRs +Returns -- its last arg, now pure + +Example: +OK if no RSUBRs in the group + +PUT-DECL: Give a value a DECL or change the existing one + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: GET-DECL + + PUT-DECL gives a DECL to a global or local value, or changes +the existing DECL. It takes a locative to the value and a DECL, which +cannot be FALSE or MANIFEST. It modifies the DECL of the value to +be that second argument. + Note that the new DECL must correspond with the type of the +value, if is T. For example, if the value is a FIX, you +cannot change the DECL to be VECTOR, without first changing the value. + + PUT-DECL may also be used to make a new OFFSET from an old one, given +a new DECL part for the OFFSET. + +Argument: + + Template: #DECL ("VALUE" LOCD >) + +Argument 1 -- A locative to a value of an ATOM, or an OFFSET. +Argument 2 -- A new DECL for that value, or a new OFFSET. +Returns -- Argument 1. + +Example: + 1 + > + T + > + + FIX> +returns locative here + VECTOR> +here ERROR, type mismatch, as GVAL of FOO is FIX. + + >> '> + %> +Note that this is a new OFFSET: + .X + %> + + +PUT: Change an element of a structure or make an association + +Object-type: SUBR + +Category: DATA-HANDLING, ASSOCIATION + +Reference: PUTPROP, GET + + PUT associates a property with an item or (as with GET) if arg 1 +is structured and arg 2 is fix, insert the third arg as the fix'th +element. + PUT is thus exactly like PUTPROP if the first argument is not +structured or the second not FIX. If used as PUTPROP, and no third +argument is given, removes any association between ARG 1 and ARG 2. + Returns the first argument. + +Argument: + + Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY) + +Argument 1 -- ANY, the object with the association, or the structure + whose Nth element to replace. +Argument 2 -- ANY, the indicator under which the association is + stored, if fix and first arg a structure, clobber the fix'th + element with the value instead. +(Optional) +Argument 3 -- ANY, the value to be associated, if none, the previous + association is removed. +Returns -- The result is the first argument. + +Example: +Like PUTPROP. + +If .FOO is structured, clobber its first element. + +PUTBITS: Change part of a WORD + +Object-type: SUBR + +Category: BIT-TWIDDLING + +Reference: BITS, GETBITS + + PUTBITS changes part of a PRIMTYPE WORD, as described by a BITS +and a PRIMTYPE WORD. It takes the rightmost bits of the third +argument, which defaults to 0, and clobbers the bit positions +indicated by the BITS in the first argument. + It is functionally equivalent to the PDP-10 Deposit Byte (DPB) +instruction. + +Argument: + + Template: #DECL ("VALUE" BITS + "OPTIONAL" ) + +Argument 1 -- A PRIMTYPE WORD, the destination of the bits. +Argument 2 -- A BITS, describes how many bits to move and where in the + output word to put them. +(Optional) +Argument 3 -- A PRIMTYPE WORD, the source of the bits to move, default 0. +Returns -- The new version of argument 1. Arg 1 itself is not changed. + +Example: > + -505 +Args need not be of type WORD. + +PUTPROP: Change or create an association + +Object-type: SUBR + +Category: DATA-HANDLING, ASSOCIATION + +Reference: PUT, GET + + PUTPROP associates a property with an item under a given +indicator. If no property (or value) is given, any association of the +item and indicator is removed. Note that if PUT's first argument is +not structured and its second argument is not FIX, it is identical to +PUTPROP. + Returns the first argument. + +Argument: + + Template: #DECL ("VALUE" ANY ANY ANY "OPTIONAL" ANY) + +Argument 1 -- ANY, the object with the association +Argument 2 -- ANY, the indicator under which the association is to be + stored. +(Optional) +Argument 3 -- ANY, the value to be associated, if none, the previous + association is removed. +Returns -- The result is the first argument. + +Example: +Makes association. + +If .FOO is structured, clobber its first element, else make association. + +PUTREST: Make REST of a LIST a given LIST + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LIST + + PUTREST replaces the rest of a list making arg2 be REST of arg1. +Notice that this does not copy the lists, so it can be used to produce +circular lists. + +Argument: + + Template: #DECL ("VALUE" + ) + +Argument 1 -- A LIST, rest of which will be replaced by Argument 2. +Argument 2 -- A LIST, which will become the new REST of Argument 1. +Returns -- The new LIST. + +Example: 2> (4 5 6)> + (3 4 5 6) +.X will now be (1 2 3 4 5 6). + .CIRCULAR> +Create a circular LIST of one element. + +QUIT: Kill a MUDDLE + +Object-type: SUBR + +Category: SYSTEM + +Reference: LOGOUT, VALRET + + Causes a MUDDLE to VALRET the string ':KILL' to its +superior. This will cause the superior to kill the MUDDLE job. + +Argument: + + Template: #DECL () + +Never returns. + +Example: +Only possible example. + +QUITTER: Default character interrupt SUBR + +Object-type: SUBR + +Category: INTERRUPT + +Reference: ON, OFF + + QUITTER is not normally called by user programs. It is the +default character interrupt SUBR that handles ^S and ^G + +Argument: + + Template: #DECL ("VALUE" ANY CHARACTER CHANNEL) + +Argument 1 -- The CHARACTER typed. +Argument 2 -- The CHANNEL which produced the interrupt. +Returns -- The CHARACTER typed. + +Example: For the best example, type ^G and then to a MUDDLE. + +QUOTE: Return its first argument unEVALed. + +Object-type: FSUBR + +Category: UTILITY + +Reference: EVAL + +The QUOTE Fsubr takes unEVALuated arguments and returns the first. +It is the way to circumvent the normal EVALuation mechanism. +Note that 'object is an abbreviation for . + +Argument: + + Template: #DECL ("VALUE" ANY "ARGS" LIST) + +Arguments -- ANY objects; the first will be returned untouched by QUOTE. +Returns -- Its first argument, untouched by interpreted hands. + +Example: ` + [CHRIS + BRUCE + NEAL + DAVE + HOWARD] + +This will cause the Vector to be returned unEVALuated and therefore + without the overhead of copying. + '( + + ) +This will return a list of Forms. + +RANDOM: Generate a random FIX + +Object-type: SUBR + +Category: ARITHMETIC + + RANDOM generates a random FIX. If the seeds of the MUDDLE +random number generator are not touched, repeated invocations of +RANDOM will return the exact same sequence of numbers. This is for +convenience in debugging. 'Debugged' code should pass the first and +second optional arguments to RANDOM, which change the two seeds it +uses to generate its numbers. Popular choices of new seeds are the +numbers returned by TIME and the contents of various UVECTOR buffers. + +Argument: + + Template: #DECL ("VALUE" FIX "OPTIONAL" FIX FIX) + +(Optional) +Arguments 1 and 2 -- New seed settings for the random number generator. +Returns -- A random FIX. + +Example: 30> +How to generate a random number between 0 and N. + +READ: Read one object from an I/O channel + +Object-type: SUBR + +Category: I/O + +READ returns the entire object whose character representation is next +in the input stream. If there is a comment on the object, it is PUT +on the channel used with indicator COMMENT. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" CHANNEL ANY + ]>> + VECTOR) + +(Optional) +Argument 1 -- input channel, default .INCHAN +Argument 2 -- object to eval and return at end of file, default + +Argument 3 -- oblist or list therof for looking up atoms, default .OBLIST +Argument 4 -- READ-TABLE giving special characters, default .READ-TABLE +Returns -- the object read + +Example: > +Calls like this make you CALICO-incompatible. + +READB: Read binary words from an I/O channel + +Object-type: SUBR + +Category: I/O + + READB fills a buffer with 36-bit binary words and returns the +number of words read. If the end of file is reached, this number will +be less than the size of the buffer. If another READB is attempted, +the end-of-file arg will be evaled and returned. + +Argument: + + Template: #DECL ("VALUE" FIX + < [REST ]> CHANNEL + "OPTIONAL" ANY) + +Argument 1 -- buffer to fill +Argument 2 -- "READB" channel +(Optional) +Argument 3 -- object to eval and return at end of file +Returns -- number of binary words read + +Example: + > +Get your file directory in binary form. + +READCHR: Read one character from an I/O channel + +Object-type: SUBR + +Category: I/O + +Reference: TYI + + READCHR returns the next character in the input stream from a +given channel. Successive calls return successive characters. If the +channel is open to a console, receipt of a character is held off until +an ESC is typed. If it is open to a pseudo-console in "READ" mode +and no input is available, READCHR returns -1. + +Argument: + + Template: #DECL ("VALUE" "OPTIONAL" CHANNEL + ANY) + +(Optional) +Argument 1 -- the channel to read from +Argument 2 -- object to eval and return at end of file +Returns -- the character read (-1 if empty STY device) + +Example: + !\ +If called alone, you get the ESC. + +READSTRING: Read into a string from an I/O channel + +Object-type: SUBR + +Category: I/O + +Reference: READB + +READSTRING is the string analog to READB (q.v.). It fills a string +buffer with characters from a channel, returning the number of characters +input. One argument tells when to stop reading: after a certain number +of characters or upon reading one of a set of characters. + +Argument: + + Template: #DECL ("VALUE" FIX STRING "OPTIONAL" CHANNEL + ANY) + +Argument 1 -- buffer to read into +(Optional) +Argument 2 -- channel to read from, default .INCHAN +Argument 3 -- number of chars to read or char to stop reading on +Argument 4 -- object to eval and return at end of file +Returns -- number of characters read + +Example: + 1 +You get the ESC if called alone. + +REALTIMER: Set interval between Real-time interrupts + +Object-type: SUBR + +Category: INTERRUPT + +Reference: RUNTIMER + + REALTIMER sets the interval (in seconds) between REALT (real- +time) interrupts. The MUDDLE will be interrupted each time this many +seconds elapse. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- Interval between Real-time interrupts (in seconds). +Returns -- Argument 1. + +Example: > +Interrupt every ten minutes. + +REMOVE: Remove an ATOM from its OBLIST + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: INSERT, LOOKUP + + REMOVE is the opposite of INSERT. It takes a single argument, an +ATOM, and removes that ATOM from its OBLIST. It can also take two +arguments, a STRING and an OBLIST, and removes the ATOM of that PNAME +from that OBLIST. The ATOM, which now is on no OBLIST, and therefore +has a trailer of !-#FALSE(), is returned. If the ATOM was originally +on no OBLIST, or if the STRING names no ATOM on the OBLIST, REMOVE +returns #FALSE (). + +Argument: + + Template: #DECL ("VALUE" "OPTIONAL" + OBLIST) + +Argument 1 -- The ATOM to flush from its OBLIST, or a STRING. +(Optional) +Argument 2 -- If arg 1 was a STRING, this is the OBLIST to mung. +Returns -- The now homeless ATOM. + +Example: > +You can move ATOMs from one OBLIST to another with REMOVE and INSERT. + +RENAME: Rename or delete a disk file + +Object-type: SUBR + +Category: I/O + + RENAME is for renaming and deleting files. It takes three +kinds of arguments: + (a) two file names (one or more strings) separated by the atom TO, + (b) one file name, or + (c) a channel (output mode) and a file name. +Omitted file-name parts use the OPEN defaults. The action is, respectively, + (a) rename the file named first to the second name, + (b) delete the file, or + (c) rename the file while open for writing. + +Argument: + + Template: #DECL ("VALUE" > + "TUPLE" >) + +Tuple of arguments -- rename or delete action (see description) +Returns -- whether it succeeded + +Example: + T +Rename FOO 3 to BAR >. + + T +Delete that file. + +REP: Enter a READ-EVAL-PRINT loop + +Object-type: SUBR + +Category: SYSTEM + +Reference: LISTEN, ERRET, RETRY + +REP causes an endless READ-EVAL-PRINT loop, which is left only by a +non-local return. It is the last thing that LISTEN does, unless there +is a substitute . + +Argument: + + Template: #DECL ("VALUE" ANY) + +Returns -- argument to ERRET + +Example: +no arguments + +REPEAT: Execute repeatedly sequential expressions. + +Object-type: FSUBR + +Category: PROGRAM-CONTROL + +Reference: PROG, RETURN, GO, AGAIN + + This FSUBR is used to bind varialbes and repeatedly and +sequentially execute MUDDLE expressions and perform appropriate GOs, +RETURNs, and AGAINs. + If the first argument to REPEAT is an atom, it is bound to the +Activation of the REPEAT. + Otherwise the next object must be the argument list of the REPEAT. +It contains either Atoms or Lists of an Atom and a MUDDLE expression. +Each single Atom in the argument list is Bound but not Assigned. Each +'listified' Atom is Bound and Assigned to the evaluation of the MUDDLE +expression which appears with it. + If the next argument to the REPEAT is of type DECL, it is used as +the declaration for the variables of the REPEAT. + The remaining arguments, at least one must exist, constitutes the +body of the REPEAT. They are executed in sequence. When the last has +been evaluated, evaluation begins again with the first expression in +the body. Unless a RETURN or non-local AGAIN or GO is executed at +some time by the body of the REPEAT, the REPEAT will never return. + +Argument: + + Template: #DECL ("VALUE" ANY "ARGS" ) + +Optional argument 1 -- ATOM to which to bind the activation of the + REPEAT. +Argument 2 -- Parameter list of the REPEAT. +Optional argument 3 -- DECL of the REPEAT. +Tuple of arguments -- At least one evalable object. +Returns -- the argument to a RETURN from the REPEAT's activation. + +Example: !.C)>> 69>) + (ELSE )>> +This will create a LIST of random numbers until RANDOM returns 69. + +RESET: Reopen a channel at its beginning + +Object-type: SUBR + +Category: I/O + +Reference: ACCESS, OPEN + + RESETting a channel means: +for input, empty all buffers and ACCESS the file (if any) to 0; +for output, return to beginning of file, destroying all output if not +"PRINTO". If the channel is closed, it is first opened. RESET on +either console channel causes the interpreter to update device specs. + +Argument: + + Template: #DECL ("VALUE" > CHANNEL) + +Argument 1 -- the channel to reset +Returns -- arg1 or a false if reopen failed + +Example: +after detaching and moving to a different console + +REST: Remove elements from the front of a structure + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: BACK, TOP + + REST removes the first N elements from a structure, that is, +moves N places down the structure. N defaults to 1 if not given. + For some structures, the effect of REST may be undone with BACK. + Note that the result of REST is always CHTYPEd to its PRIMTYPE, +thus FORMs become LISTs when RESTed, and so on. + +Argument: + + Template: #DECL ("VALUE" STRUCTURED STRUCTURED "OPTIONAL" FIX) + +Argument 1 -- A Structured object. +(Optional) +Argument 2 -- FIX, default 1. +Returns -- The result is the structured object, CHTYPEd to its + primtype. + +Example: > + [4] + > + [3 4] + > + [2 3 4] + > + [1 2 3 4] + > + [2 3 4] + > +YZ + +The relationships between REST, BACK, and TOP are illustrated. +Note that only REST can work on lists + +RESTORE: Restore a previously SAVEd core image + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: SAVE, FSAVE + + RESTORE replaces the entire current MUDDLE environment with one +from a file generated by SAVE. It is much faster than FLOAD for very +large programs. RESTORE does not return; the SAVE that originally +created the file returns again with the string "RESTORED" as its +value. + All arguments are optional with a default file name of + + DSK:<-user's sname>-;MUDDLE SAVE + + Note that RESTORE attempts to restore the state of all channels. + If the SNAME of the MUDDLE doing the SAVE was "", the current +SNAME will not be changed by the RESTORE. This feature is useful +if a SAVE file is to be used by more than one person. + +Argument: + + Template: #DECL ("VALUE" STRING "OPTIONAL" STRING STRING STRING + STRING) + +(Optional) +Arguments -- Up to four STRINGs specifying the file name to RESTORE. +Returns -- The STRING "RESTORED". + +Example: +Restore the compiler. + +RESUME: Resume running a PROCESS + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: RESUMER, PROCESS + + RESUME starts a PROCESS running. It takes something to return +as the 'value' of the current PROCESS, and the PROCESS to resume. If +not given, the PROCESS to RESUME is defaulted to be the last PROCESS to +RESUME the PROCESS doing the RESUME, if there was one. + If the process that is doing the RESUME is ever itself RESUMEd, +the first argument to that RESUME will be returned as its value. In +fact, a PROCESS may be treated in the simpler cases as a routine called +by invoking RESUME, which returns the result as RESUME's value. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" PROCESS) + +Argument 1 -- Something to be returned to the resumed process. +(Optional) +Argument 2 -- The PROCESS to resume, default if there is one. +Returns -- Whatever is passed to RESUME later in another PROCESS to + RESUME this one. + +Example: >)> +Resumer our RESUMER, if we have one. + +RESUMER: Return the last PROCESS to RESUME a PROCESS + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: RESUME + + RESUMER takes an optional process, and returns the last +PROCESS to RESUME it. If not given, the PROCESS is . If no +process has ever RESUMEd the process given, returns FALSE. + +Argument: + + Template: #DECL ("VALUE" "OPTIONAL" PROCESS) + +(Optional) +Argument 1 -- A PROCESS, default . +Returns -- A PROCESS, which last RESUMEd Arg 1, or FALSE if none ever + did. + +Example: )) + RESUMABLE>> + )>> +RESUME RESUMER if o.k. to do so. + +RETRY: Retry a previous Subroutine call from the error level + +Object-type: SUBR + +Category: ERROR, PROGRAM-CONTROL + +Reference: FRAME + +RETRY pops the stack down to a given frame and then causes the +Subroutine call that generated that frame to be done again. It is +mostly useful for restarting some program after fixing the cause of an +error. + +Argument: + + Template: #DECL ("OPTIONAL" FRAME) + +(Optional) +Argument 1 -- the frame to be redone, default the last call to ERROR/LISTEN +Returns -- really nothing + +Example: > +Often you want to restart from just before the error. + +RETURN: Return something from an activation + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: ERRET, GO, RETRY + + RETURN takes a value and an ACTIVATION and returns the value +from the ACTIVATION. The ACTIVATION is optional, and defaults to the +most nearly surrounding ACTIVATION, usually that of the current PROG +or REPEAT. The value is also optional, default T. + The result of RETURN is that the ACTIVATION terminates and the +value is returned as its 'result'. + ACTIVATIONs may be implicit, as in they often are in PROGs and +REPEATs, or explicit as in the optional first argument for PROG, +REPEAT, FUNCTION, and second argument for DEFINE. In these cases the +LVAL of the ATOM given is the ACTIVATION of that PROG, REPEAT, etc. +See the Abstracts of these FSUBRs and the Abstract of AGAIN for more +details. + One final note. An ACTIVATION may be CHTYPEd to a FRAME and used +by ERRET, RETRY and so on. + The ACTIVATION argument to RETURN may literally be any legal +activation in the MUDDLE, even one from another PROCESS. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ANY ACTIVATION) + +(Optional) +Argument 1 -- the value to return from the activation, default T. +Argument 2 -- the ACTIVATION to return the value from, default the + most closely surrounding ACTIVATION, as of the current PROG + or REPEAT that is running. +Returns -- Argument 1 (from the ACTIVATION). + +Example: ) + (ELSE >)> + >> +Simple use of RETURN in a REPEAT. + +RGLOC: Get a locative to the GVAL of an ATOM for pure-program use + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: LLOC, GLOC + + Returns a locative, type LOCR, to the GVAL of the ATOM passed +as its argument. If the ATOM has no GVAL slot, ERROR, unless second +arg is given and true. Pure RSUBRs must use this instead of GLOC. + +Argument: + + Template: #DECL ("VALUE" LOCR ATOM "OPTIONAL" ) + +Argument 1 -- An ATOM with a GVAL. +(Optional) +Argument 2 -- whether not to give a no-slot error or not +Returns -- A locative (LOCR) to the GVAL of the ATOM. + +Example: > +Guard against ATOMs with no GVALs. + +ROOT: Return the ROOT oblist + +Object-type: SUBR + +Category: IDENTIFIER + + ROOT returns the ROOT OBLIST. This OBLIST is almost always +in the path. + +Argument: + + Template: #DECL ("VALUE" OBLIST) + +Returns -- The ROOT OBLIST. + +Example: +Only one there is. + +ROT: Logical rotate + +Object-type: SUBR + +Category: BIT-TWIDDLING, LOGICAL + +Reference: LSH + + ROT takes an object of Primtype WORD and a FIX, and it returns a +WORD containing the bits in the first argument, rotated the number of +bits specified by the second argument (mod 256). A positive second +argument specifies rotation to the left, a negative FIX specifies +rotating to the right. Rotation is a cyclic logical shift where bits +shifted out at one end are put back in at the other. + +Argument: + + Template: #DECL ("VALUE" WORD + FIX) + +Arg 1 -- a Primtype WORD containing the bits to rotate +Arg 2 -- a FIX specifying the amount to rotate +Returns -- A WORD containing the rotated bits. + +Example: + #WORD *000000001000* + + #WORD *100000000000* +Primarily useful for getting fingers directly in the bits. + +RSUBR-ENTRY: Create entry point to an RSUBR. + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: RSUBR, ENTRY-LOC + + This routine will create an alternate entry point to an RSUBR. +The ATOM supplied will be the name of this alternate entry point. The +DECL will be used for argument and result checking at the new entry. +The FIX is the offset into the actual code of the RSUBR of this entry. + +Argument: + + Template: #DECL ("VALUE" RSUBR-ENTRY + ATOM DECL> FIX) + +Argument 1 -- a vector containing the RSUBR (or its name) and the new + entry's name and DECL +Argument 2 -- a FIX, an offset in the RSUBR +Returns -- an RSUBR-ENTRY into the RSUBR + +Example: + +This will make a new entry point into the RSUBR FOO. This entry will +have the name FOO1 and have a DECL as given. The offset into the CODE +of FOO for this entry will be 245. + +RSUBR-LINK: Change state of automatic RSUBR linking feature + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: RSUBR + + RSUBR-LINK is used to enable and disable the automatic RSUBR +linking feature of MUDDLE. Normally, as they are called, RSUBRs link +up to each other. If RSUBRs are being debugged, this can be a problem +as several different versions may be loaded and reloaded. + Calling RSUBR-LINK with FALSE disables the feature, with non-FALSE +enables it. It is normally enabled. + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" ) + +(Optional) +Argument 1 -- FALSE disables automatic RSUBR linking, non-FALSE + enables it. +Returns -- The previous state, or the current state if no arg + +Example: > + +.....debugging..... + +Done debugging. + +RSUBR: Create an object of type RSUBR (Relocatable SUBR) + +Object-type: SUBR + +Category: DATA-HANDLING + + RSUBR is a routine that is rarely if ever used other than in the +MUDDLE Assembler. The user (almost) always sees the type RSUBR already +created. + RSUBR creates an object of RSUBR, which stands for Relocatable +SUBR. RSUBRs are created in one of several ways. They can be created +by hand-coding a routine and assembling it. They can be the result of +the assembly of a compiled FUNCTION. + Internally, an RSUBR consists of a code uvector, a name, a DECL, +and (optionally) references, which are all the objects the +RSUBR references outside of itself. + +Argument: + + Template: #DECL ("VALUE" RSUBR + ATOM DECL [REST ANY]>) + +Argument 1 -- A VECTOR containing the code (impure or pure), an ATOM (the + name of the RSUBR), a DECL, and references. +Returns -- The argument CHTYPEd to an RSUBR. + +Example: +Will create a useless RSUBR + +RUNINT: Apply interrupt handler (for internal use only) + +Object-type: SUBR + +Category: SYSTEM, INTERRUPT + +Reference: APPLY + +RUNINT is just like APPLY, except that it is called internally to +execute an interrupt handler. It may cause another PROCESS to run. + +Argument: + + Template: #DECL ("VALUE" ANY APPLICABLE "TUPLE" TUPLE) + +Argument 1 -- the handler to be applied +Tuple of arguments -- its args, supplied by interrupt system +Returns -- whatever handler returns + +Example: !.ARGS> +Of course only the interpreter does this. + +RUNTIMER: Set time of Run-time interrupt + +Object-type: SUBR + +Category: INTERRUPT + +Reference: REALTIMER + + RUNTIMER sets the amount of Run-time (in seconds) the MUDDLE +must have used for a RUNT (run-time) interrupt to occur. + +Argument: + + Template: #DECL ("VALUE" ) + +Argument 1 -- The amount of run-time (fix or float) the MUDDLE must + have used for a RUNT (run-time) interrupt to occur. +Returns -- Argument 1. + +Example: > +Cause interrupt after one hour time (seconds) used. + +SAVE: Saves the core image of a MUDDLE in a continuable state. + +Object-type: SUBR + +Category: I/O + +Reference: FSAVE, RESTORE + + SAVE saves the impure part of a MUDDLE's core image in a file on +the disk. This file can later be RESTOREd (q.v.) and whatever was in +progress continued. + SAVE files are zero compressed, and normally a garbage collection +is performed before the SAVE is done to further reduce the rather +considerable size of the resulting file. + SAVE takes the name of the file to SAVE into as its argument, and +optionally, an argument which if given and FALSE, causes the garbage +collect to not occur. The default name of the SAVE file is DSK:MUDDLE +SAVE. + SAVE returns the string "SAVED". RESTORE, which 'returns again' +from the SAVE, returns the string "RESTORED", and thus the caller can +differentiate. + SAVE files are RESTOREable only into MUDDLEs with the same +version number as the MUDDLE that SAVEd them. To check if a SAVE file +is compatible with a MUDDLE, compare the version number with on +a channel open to the SAVE file. + +Argument: + + Template: #DECL ("VALUE" '"SAVED" "TUPLE" TUPLE) + +(Tuple of arguments) +First element(s) -- STRING(s) specifying the file to SAVE into. +Last element (optional) -- An object, which, if FALSE, inhibits pre-SAVE garbage + collect. +Returns -- the STRING "SAVED" + +Example: +Will save core image to DSK:;MUDDLE SAVE. + +SEND-WAIT: Send an IPC message and wait until someone takes it + +Object-type: SUBR + +Category: SYSTEM + +Reference: SEND, IPC-ON, IPC-OFF + + SEND-WAIT sends an IPC message to a specific destination from your +MUDDLE, using the ITS IPC (Inter-process communication) feature. SEND +takes 3, 4, or 6 arguments: Two string specifying whom to send the +message to, a message, and optionally a message type number, and a +pair of strings specifying whom the message is from. + Using SEND-WAIT, it is possible to hang until someone takes the +message. SEND returns T if someone takes the message, #FALSE() +otherwise. + When your process receives an IPC message, the condition "IPC" +is signalled. There is a default handler for this condition, called +IPC-HANDLER. See its abstract for more details. + +Argument: + + Template: #DECL ("VALUE" 'T STRING STRING + ]> STORAGE> + "OPTIONAL" FIX STRING STRING) + +Arguments 1 & 2 -- STRINGs specifying the destination of the message. + Any one who is listening on this pair will receive the message. + They correspond to an ITS UNAME, JNAME pair. +Argument 3 -- A message. This can be a STRING, a UVECTOR of UTYPE + Primtype WORD, or a STORAGE. +(Optional) +Argument 4 -- A message type. This is just an identifying type for + the recipient to look at if he is interested. +Arguments 5 & 6 -- Two STRINGs specifying whom the message is from. If + not given, they are from UNAME JNAME of the MUDDLE. +Returns -- T when the message is taken. Hangs until then. + +Example: +Will return T when CLR MUDDLE takes the IPC message. + +SEND: Send an IPC message + +Object-type: SUBR + +Category: SYSTEM + +Reference: SEND-WAIT, IPC-ON, IPC-OFF + + SEND sends an IPC message to a specific destination from your +MUDDLE, using the ITS IPC (Inter-process communication) feature. SEND +takes 3, 4, or 6 arguments: Two strings specifying whom to send the +message to, a message, and optionally a message type number, and a +pair of strings specifying whom the message is from. + SEND returns T if someone takes the message, #FALSE() otherwise. +Using SEND-WAIT, it is possible to hang until someone takes the message. + When your process receives an IPC message, the condition "IPC" +is signalled. There is a default handler for this condition, called +IPC-HANDLER. See its abstract for more details. + +Argument: + + Template: #DECL ("VALUE" STRING STRING + ]> STORAGE> + "OPTIONAL" FIX STRING STRING) + +Arguments 1 & 2 -- STRINGs specifying the destination of the message. + Any one who is listening on this pair will receive the message. + They correspond to an ITS UNAME, JNAME pair. +Argument 3 -- A message. This can be a STRING, a UVECTOR of UTYPE + Primtype WORD, or a STORAGE. +(Optional) +Argument 4 -- A message type. This is just an identifying type for + the recipient to look at if he is interested. +Arguments 5 & 6 -- Two STRINGs specifying whom the message is from. If + not given, they are from UNAME JNAME of the MUDDLE. +Returns -- T if the message is taken, else #FALSE (). + +Example: +Will return T only if CLR MUDDLE is listening for IPC messages. + +SET: Give an atom a local value + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: ASSIGNED?, LVAL + + SET gives an atom (arg1) a local value (arg2) in a given +environment (arg3, optional). + +Argument: + + Template: #DECL ("VALUE" ANY ATOM ANY + "OPTIONAL" ) + +Argument 1 -- the atom to set +Argument 2 -- the local value to give it +(Optional) +Argument 3 -- the environment for this to occur in +Returns -- arg2 + +Example: +allows redefinitions + +SETG: Assign a global value to an atom + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: GVAL, GASSIGNED?, DEFINE + + +Argument: + + Template: #DECL ("VALUE" ANY ATOM ANY) + +Argument 1 -- the atom +Argument 2 -- the global value to give it +Returns -- arg2 + +Example: +often the first step in redefining primitives + +SETLOC: Change the object a locative points to + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: IN, LEGAL? + + Change the object a locative points to. The advantage of SETLOC +is that it is independent of exactly what is pointed to by the locative +passed it. It works equally well for LVALs, GVALs, structures, and +so on. + Note that it is possible to lose if an LVAL to which an LLOC +points has become unbound. Use LEGAL? to check when in doubt. + +Argument: + + Template: #DECL ("VALUE" ANY LOCATIVE ANY) + +Argument 1 -- A locative. +Argument 2 -- Anything, to be the new contents of the thing the + locative points at. +Returns -- Argument 2. + +Example: + > + + 2 + + .FOO + (1 "BAR" 3) +Just like PUT, right? + +SIN: Sine of an angle + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: COS, ATAN + + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- the angle in radians. +Returns -- A FLOAT, the Sine. + +Example: <+ <* > + <* >> + 1.0 +One of the common trig. identities. + +SLEEP: Sleep interruptably for a given number of seconds + +Object-type: SUBR + +Category: ENVIRONMENT, INTERRUPT + +Reference: HANG + + SLEEP allows a process to sleep (using the system call) for +a given period of time. It is also possible to give an object to be +evaluated each time an interrupt occurs and is dismissed back into +the SLEEP. If the result of the evaluation is non-FALSE, the result +is returned as the value of the SLEEP. This enables a switch to be +set at interrupt level and looked at to terminate a SLEEP. + +Argument: + + Template: #DECL ("VALUE" ANY "OPTIONAL" ANY) + +Argument 1 -- the number of seconds to SLEEP. +(Optional) +Argument 2 -- Something to evaluate each time an interrupt dismisses + back into the SLEEP, and terminates the SLEEP if it returns + non-FALSE. +Returns -- The non-FALSE result of the second argument. + +Example: + +Sleep for a minute but stop early if an interrupt handler sets the +ATOM to a non-FALSE. + +SNAME: Read or change MUDDLE's SNAME + +Object-type: SUBR + +Category: SYSTEM + + Reads or changes MUDDLE's SNAME, which is the default name for +opening files. If no arguments are given, returns the current SNAME. +If a STRING is given, it is made the current SNAME and returned. + The ATOM SNM may also be set, locally or globally, to change +(temporarily or permanently) the default SNAME of the MUDDLE. + +Argument: + + Template: #DECL ("VALUE" STRING "OPTIONAL" STRING) + +(Optional) +Argument 1 -- A STRING to set the SNAME to. If none is given, just + read the current SNAME. +Returns -- The current SNAME. + +Example: +FOO + +FOO +Set and read SNAME. + +SORT: Sort VECTORs, UVECTORs, or TUPLEs + +Object-type: SUBR + +Category: DATA-HANDLING + + SORT is used to order VECTORs, UVECTORs, and TUPLEs. It is a +fairly complex SUBR, which however has good defaults and is fairly +easy to use with them. + It works most efficiently if the sort keys are of primtype WORD, +ATOM, or STRING. However, the keys may be of any type, and SORT will +still work. SORT acts on records which consist of one or more contig- +uous entries in the structure being sorted. One item in the record is +declared to be the sort key. Also, any number of additional structures +may be rearranged based on how the main structure is sorted. + + arg2 ?? + + s1 ; the structure to sort + + l1 ; length of sort records in s1, default 1 + + offset ; REST offset from start of record of + ; sort key. Optional, default 0. + + s2 l2 - sN lN> ; the VECTORs, UVECTORs, or TUPLEs to + ; rearrange, and record lengths in them + + If the function is FALSE, then the types of all the sort keys +must be the same, and they must be of primtype WORD, ATOM, or STRING. +In this case a Radix Exchange Sort is used (stolen from TECO). If +function is something applicable, a Shell Sort is used. + Note that if you give your own 'function' it is possible to make +a non-terminating sort. If the condition you create by your function +does not map into the normal one 'return FALSE if first not bigger than +second' then the SORT may not terminate. + See 'Example' section for several examples of the use of SORT. + +Argument: + + Template: #DECL ("VALUE" > + > + "OPTIONAL" FIX FIX "TUPLE" + > + FIX]>) + +Argument 1 -- The Sorting routine, or FALSE if the internal one is to + be used. Remember internal one only works if keys are WORD, + ATOM, STRING primtypes. +Argument 2 -- The PRIMTYPE VECTOR, UVECTOR, or TUPLE to sort. +(Optional) +Argument 3 -- FIX giving the record size in the + structure given for argument 2. Defaults to 1 if not + given. +Argument 4 -- The REST offset of the sort key in the records of the main + structure. Default is 0. +Tuple of arguments -- Alternating structures and respective record sizes. + These records are permuted the same way as the sorted ones in + the main structure. +Returns -- the sorted arg 1 + +Example: >> + .A> + +This is the simplest use of SORT. Note that only one argument is +really given, the FALSE simply defaulting the sorting method to the +internal one. + + [foo + 1 + bar + 2 + blech + -1 + crock + 69] + 2> + +This sorts the vector based on the atom names, considering records +to be two elements and defaulting the offset to 0. If the offset had +been 1 would sort based on the numbers. + <1 .Y>>> + [(101 "FOOBAR") (17 "MUMBLE") (86 "BLECH") (34 "GRITCH")] + 1 + 0 + [A + B + C + D + E + F + G + H + I + J + K + L] + 3> + +This sorts two structures based on the first element of the main +structure. Note that records in the second structure are 3 elements +long. + +SPECIAL-CHECK: Change or examine the state of interpreter SPECIAL checking + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: SPECIAL-MODE, DECL-CHECK + + SPECIAL-CHECK turns interpreter SPECIAL checking on or off, +returning the old state, or, if given no argument, returns the current +state. (T indicates special checking is on, #FALSE() off). + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" ) + +(Optional arguments) +Argument 1 -- A FALSE or T, indicating which state special checking is + to be put in. If not given, just return current state. +Returns -- The state of special-checking when SPECIAL-CHECK was called. + +Example: > +This sets the normal initial state -- no special checking. + +SPECIAL-MODE: Change or examine the default Special Mode + +Object-type: SUBR + +Category: ENVIRONMENT + +Reference: SPECIAL-CHECK + + SPECIAL-MODE is used to change or examine the default special +mode. It takes as argument the atoms SPECIAL or UNSPECIAL, and sets +the default mode accordingly, returning the old mode. If no argument +is given, it just returns the old mode. + +Argument: + + Template: #DECL ("VALUE" + "OPTIONAL" ) + +(Optional arguments) +Argument 1 -- SPECIAL or UNSPECIAL, the new mode. +Returns -- The mode at the time of the call. + +Example: +Set the initial state. + +SPNAME: Create a shared STRING which is the name of an ATOM + +Object-type: SUBR + +Category: IDENTIFIER + +Reference: ATOM, INSERT, PNAME + + SPNAME takes as argument an ATOM, and returns the STRING which +is the PNAME (printing name) of that ATOM. This name does not include +any oblist trailers or the backslashes that are sometimes printed out +for the convenience of the reader. Several other SUBRs, notably +INSERT, LOOKUP, and ATOM, use the pname of atoms as arguments. + PRINC of the PNAME of an ATOM is one guaranteed way of printing +an ATOM-name without trailers, backslashes, or quotes. + SPNAME is more efficient than PNAME (q.v.) if the string will not +be modified. Any attempt to PUT into the string will cause an error. + +Argument: + + Template: #DECL ("VALUE" STRING ATOM) + +Argument 1 -- An ATOM. +Returns -- A STRING which shares the atom's pname. + +Example: + +Just three spaces, no backslashes, no trailers. + +SQRT: Square root of a number + +Object-type: SUBR + +Category: ARITHMETIC + +Reference: LOG, EXP + + +Argument: + + Template: #DECL ("VALUE" FLOAT ) + +Argument 1 -- A FIX or FLOAT. +Returns -- FLOAT, the square root of argument 1. + +Example: + 2.0 +Floating is always done. + +SQUOTA: Get the address of an internal interpreter symbol (for internal use only) +"VALUE" + + +STACKFORM: Apply a function to generated arguments. [OBSOLETE] + + ******* This FSUBR is obsolete as of MUD54 ******* + +Object-type: FSUBR + +Category: DATA-HANDLING + + STACKFORM is obsolete and replaced by a MAPF of only two arguments. +It is documented for historical reasons only. The compiler transforms +applications of STACKFORM into appropriate MAPFs. + + The STACKFORM Fsubr was used to APPLY a function to a variable +number of generated arguments. This could also be done by constructing +the appropriate Form and EVALing it. STACKFORM is more efficient; it +builds the Form on the stack and therefore produces no garbage. This +is where STACKFORM obtains its name. + STACKFORM operates as follows: + (0) EVALuate the 1st arg, and save as the applicative object. + (1) EVALuate the 3rd arg, the boolean expression. + (2) If the 3rd arg EVALuated to an object not of Type FALSE + Then, EVALuate the 2nd arg, the argument expression + and save on the stack. GO TO (1) + Else APPLY the saved applicative object + to the stacked arguments and return the result. + +Argument: + + Template: #DECL ("VALUE" ANY "ARGS" ) + +Arguments -- see Description. +Returns -- see Description. + +Example: + >>> + +This reads characters from the current input channel until an alt-mode +is read. It then returns what was read as one String. + +STATE: Return the state of a PROCESS + +Object-type: SUBR + +Category: PROCESS-CONTROL + + STATE returns the state of a PROCESS, as an ATOM from the +following list: + +a) RUNNABLE -- PROCESS has never been run. +b) RUNNING -- running now (ie: applied STATE). +c) RESUMABLE -- has run and may run again. +d) DEAD -- has run and may not run again. + +Argument: + + Template: #DECL ("VALUE" ATOM PROCESS) + +Argument 1 -- A PROCESS whose state should be returned. +Returns -- The state of the PROCESS + +Example: > + RUNNING +This should always be the case. + +STORE: Create a non-garbage collected storage area [OBSOLETE] + + ******* This SUBR is obsolete as of MUD55 ******* + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: ISTORAGE, FREE + + STORE creates non-g.c. storage (for E&S etc.). It looks just like +a uvector, but does not move during garbage collection. It takes as +argument a UVECTOR whose contents will be copied into the STORAGE. + +Argument: + + Template: #DECL ("VALUE" STORAGE UVECTOR) + +Argument 1 -- UVECTOR, desired contents of the store. +Returns -- STORAGE, containing old contents of the UVECTOR. + +Example: > + (.A <1 .A> )> +Notice that once the space is free'd it should not be accessed + +STRCOMP: Compare two STRINGs + +Object-type: SUBR + +Category: PREDICATE, CHARACTER + +Reference: =? + + STRCOMP alphabetically compares two STRINGs or ATOMs. It +actually is not a predicate, since it can return one of three values: + 0 if the first string is =? to the second, + 1 if the first is greater (sorts alphabetically after the + second), + and -1 if the second is greater. + + If STRCOMP is given ATOMs, it of course uses their pnames to +compare them. + + Alphabetically means, in this case, according to the numeric +order of ASCII, which gives the standard alphabetizing rules. + +Argument: + + Template: #DECL ("VALUE" FIX ) + +Argument 1 -- STRING or ATOM +Argument 2 -- STRING or ATOM +Returns -- 0 if argument 1 is =? to argument 2. + 1 if argument 1 is greater than argument 2. + -1 if argument 1 is less than argument 2. + +Example: + 1 + 0> + T +Converts STRCOMP into a predicate suitable for SORT. + +STRING: Create a STRING from CHARACTERs and STRINGs + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: ISTRING + + STRING creates a string with explicit elements. These must be +other STRINGs or CHARACTERs. They will be concatenated together to +form a new STRING. + +Argument: + + Template: #DECL ("VALUE" STRING + "TUPLE" ]>) + +Tuple of arguments -- STRINGs or CHARACTERs, the elements of the new + STRING. +Returns -- Newly created STRING. + +Example: +This is a string + +STRUCTURED?: Is an object structured? + +Object-type: SUBR + +Category: TYPE, PREDICATE + +Reference: TYPE?, LOCATIVE?, APPLICABLE? + + STRUCTURED? tests if an object is one of the group of types +known as structured objects. It is similar to applying TYPE? to +the object and the list of structured objects, but relieves the user +from knowing the list, and thus will work for any new structured types +invented. + A structured object is defined as an object which potentially may +have NTH applied to it. + +Argument: + + Template: #DECL ("VALUE" ANY) + +Argument 1 -- Any MUDDLE object. +Returns -- T if argument 1 is structured, or FALSE if it is not. + +Example: > + T +Lots of types are structured. + +SUBSTITUTE: Substitute one type-value pair for another throughout MUDDLE + +Object-type: SUBR + +Category: DATA-HANDLING + +Reference: GC + + SUBSTITUTE causes one type-value pair to be substituted for +another throughout MUDDLE. It is not to be used unless you really +know what you are doing. In fact, one of the few legitimate uses for +it (other than just having fun by doing ) is to +substitute the 'right' atom for the 'wrong' one, where OBLISTs have +gotten in a bad state. + +Argument: + + Template: #DECL ("VALUE" ANY ANY ANY) + +Argument 1 -- Object to be substituted. +Argument 2 -- Object to be substituted for. +Returns -- Argument 2. + +Example: + +Only reasonable use so far found. ATOM impurification is done this +way, more or less. + +SUBSTRUC: Copy part of a structure into another + +Object-type: SUBR + +Category: DATA-HANDLING + + SUBSTRUC facilitates the construction of structures that are +composed of sub-parts of existing structures. It copies a set of +contiguous elements of one (non-TEMPLATE) structure into the first +elements of another, old or new, structure, all in one swell foop. + +Argument: + + Template: #DECL ("VALUE" + + + + + + > + "OPTIONAL" FIX FIX + ) + +Argument 1 -- object to copy out of +(Optional) +Argument 2 -- amount to REST arg1 (temporarily) before copying, default 0 +Argument 3 -- number of elements to copy, default all +Argument 4 -- object to copy into, TYPE must be (VECTOR + if arg1 is TUPLE), must not share with arg1 if LIST +Returns -- new object (doesn't share with arg1, VECTOR if arg1 is TUPLE) + or arg4 + +Example: + (1 2) +opposite of REST + > + "PART" +substring function + +SUICIDE: Kill the PROCESS you are in and resume another + +Object-type: SUBR + +Category: PROCESS-CONTROL + +Reference: PROCESS, RESUME, DEAD + + SUICIDE is exactly like RESUME, except that the PROCESS it is +EVALed in is made DEAD after it is left, and thus cannot be RESUMEd +any longer. + Note that
cannot be SUICIDEd. + +Argument: + + Template: #DECL ("VALUE" ANY ANY "OPTIONAL" PROCESS) + +Argument 1 -- The value of the process doing the SUICIDE. +(Optional) +Argument 2 -- A PROCESS to RESUME, default , if there is one. +Returns -- Nothing really, as the PROCESS SUICIDEd cannot be RESUMEd, + since it will be dead. + +Example: +Won't work if is
+ +TAG: Create a tag within an activation + +Object-type: SUBR + +Category: PROGRAM-CONTROL + +Reference: GO + + TAG creates a tag for a non-local GO. GO with a tag argument +allows returning to the middle of any PROG or REPEAT still active. + +Argument: + + Template: #DECL ("VALUE" TAG ATOM) + +Argument 1 -- a legal argument for local GOs +Returns -- a TAG for non-local GOs + +Example: + & + > + &> +See how easy it is to make confusing programs? + +TERPRI: Print a carriage-return and line-feed + +Object-type: SUBR + +Category: I/O + +Reference: CRLF + + +Argument: + + Template: #DECL ("VALUE" '#FALSE () "OPTIONAL" CHANNEL) + +(Optional) +Argument 1 -- the channel, default .OUTCHAN +Returns -- #FALSE () + +Example: + #FALSE () +Terminate printing on this line. + +TIME: Return the Run time of the MUDDLE + +Object-type: SUBR + +Category: UTILITY, SYSTEM + + TIME returns a FLOAT giving the run time of the MUDDLE in +seconds. + TIME takes any number of optional arguments, however, and is thus +often used to pass arguments for examination at a DDT break point. + +Argument: + + Template: #DECL ("VALUE" FLOAT "TUPLE" ) + +(Optional) +Tuple of arguments -- ANY objects. +Returns -- FLOAT, the run time of the MUDDLE in seconds. + +Example: