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: