--- /dev/null
+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.
+\f
+*: 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" <OR FIX FLOAT>
+ "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
+
+(Optional)
+Tuple of arguments -- FIXes and FLOATs
+Returns -- FIX or FLOAT, floating is contagious.
+
+Example: <* 1 2.0>
+ 2.0
+Floating is contagious.
+\f
++: 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" <OR FIX FLOAT>
+ "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
+
+(Optional)
+Tuple of arguments -- FIXes and FLOATs.
+Returns -- FIX or FLOAT, sum of arguments.
+
+Example: <+ !<SET FOO (1 2 3)!>>
+ 6
+Sum of elements of list.
+\f
+-: 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" <OR FIX FLOAT>
+ "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
+
+(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.
+\f
+/: 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" <OR FIX FLOAT>
+ "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
+
+(Optional)
+Tuple of arguments -- FIXes and FLOATs
+Returns -- FIX or FLOAT quotient.
+
+Example: </ 10 7 2.0>
+ 0.5
+First division gave 1, then .5 after second.
+\f
+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" <OR FALSE 'T> <OR FIX FLOAT>)
+
+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?
+\f
+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" <OR FALSE 'T> <OR FIX FLOAT>)
+
+Argument 1 -- FIX or FLOAT to test.
+Returns -- FALSE if not 1, T if 1.
+
+Example: <1? 1.0>
+ T
+Works for floats, too.
+\f
+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
+ <RESUME .FOO>
+ [EVLIN <+ 1 1>]
+ <RESUME .FOO>
+ [EVLOUT 2]
+Two successive steps of the process.
+\f
+==?: 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" <OR 'T FALSE> 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.
+\f
+=?: 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" <OR 'T FALSE> 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: <=? <SET V <VECTOR 1 2 3>> <EVAL .V>>
+ T
+If the test were ==?, the result would be FALSE.
+\f
+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" <OR FIX FLOAT> <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT to take the absolute value of.
+Returns -- A FIX or FLOAT guaranteed non-negative.
+
+Example: <ABS -69105>
+ 69105
+Simple SUBR, simple example.
+\f
+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: <ACCESS .IN 0>
+starts reading again from beginning of file
+\f
+ACTIVATE-CHARS: Set or inspect interrupt characters for console typing (TENEX only)
+"VALUE" STRING
+"OPTIONAL" STRING
+\f
+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: <PROG ((X <ILIST 20 '<MOD <RANDOM> 10>>))
+ <COND (<G=? <+ !.X> 100>
+ <SET X <REST .X>>
+ <AGAIN>)
+ (ELSE <PRINT <LENGTH .X>>)>>
+
+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.
+\f
+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" <VECTOR [REST ATOM]>)
+
+Returns -- The MUDDLE type VECTOR.
+
+Example: <ALLTYPES>
+Only possible example.
+\f
+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 <AND preconditions thing> 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" <OR FALSE ANY> "ARGS" LIST)
+
+List of unevaluated arguments -- ANY evalable objects.
+Returns -- Terminating FALSE or terminating non-FALSE.
+
+Example: <AND <ASSIGNED? X> .X>
+
+This construct attempts to take LVAL of X only if X is assigned, thus
+avoiding the possibility of an ERROR.
+\f
+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" <OR FALSE ANY> "TUPLE" TUPLE)
+
+Tuple of evaluated arguments -- ANY objects.
+Returns -- Terminating FALSE or terminating non-FALSE.
+
+Example: <MAPF ,AND? <FUNCTION (T) <G? .T 0>> .VECTOR>
+Are all elements of this vector positive?
+\f
+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 [REST <PRIMTYPE WORD>]>)
+
+Tuple of arguments -- Objects of primtype WORD to be ANDed together.
+Returns -- A WORD containing the bitwise AND of the arguments.
+
+Example: <ANDB 511 4226793183>
+ #WORD *000000000337*
+Primarily useful for getting fingers directly in the bits.
+\f
+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" <OR 'T FALSE> ANY)
+
+Argument 1 -- ANY object to be tested for applicability.
+Returns -- T if applicable, #FALSE() if not.
+
+Example: <APPLICABLE? 69>
+ T
+NTH makes this the case.
+\f
+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"
+ <TUPLE [REST ANY]>)
+
+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: <APPLY <GET <TYPE .ITEM> 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.
+\f
+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" <OR ATOM APPLICABLE FALSE> ATOM "OPTIONAL"
+ <OR ATOM APPLICABLE>)
+
+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: <APPLYTYPE
+ LIST
+ '<FUNCTION (X "TUPLE" Y)
+ <REPEAT ((X .X))
+ <COND
+ (<EMPTY? .Y> <RETURN .X>)
+ (<TYPE? <1 .Y> FIX>
+ <SET X
+ <NTH .X <1 .Y>>>)
+ (<ERROR>)>>>>
+Make application of a LIST be like NTH
+ <(1 2 3 (4 5 6)) 4 2>
+ 5
+\f
+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
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+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.
+ <ARGS <FRAME <FRAME>>>
+ [a 1]
+The arguments of the frame that caused the ERROR.
+\f
+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" <OR CHARACTER FIX> <OR CHARACTER FIX>)
+
+Argument 1 -- A CHARACTER or FIX to be transformed into the other.
+Returns -- The opposite type to its argument.
+
+Example: <ASCII 65>
+ <ASCII !\A>
+The first returns the character A,
+the second *101*.
+\f
+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" <OR 'T FALSE> ATOM "OPTIONAL"
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+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: <SET FOO "ANYTHING">
+ <ASSIGNED? FOO>
+This will return the Atom T, since FOO does have a local value.
+ <UNASSIGN FOO>
+ <ASSIGNED? FOO>
+This will return #FALSE (), since the Atom FOO has no local value.
+ <PROG (FOO) <ASSIGNED? FOO>>
+This will also return #FALSE (), since FOO still does not have a local value
+\f
+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" <OR ASOC FALSE>)
+
+Returns -- The first association in the association chain, FALSE if none exist.
+
+Example: <ASSOCIATIONS>
+Only possible example.
+\f
+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: <SET FOO (1 2 3)>
+ <SET Y <AT .FOO 3>>
+Get locative
+ <SETLOC .Y 5>
+Change structure
+ .FOO
+ (1 2 5)
+Changed
+\f
+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 <OR FIX FLOAT>)
+
+Argument 1 -- The tangent of some angle.
+Returns -- The angle whose tangent is argument 1.
+
+Example: <ATAN </ <SIN .FOO> <COS .FOO>>>
+Will equal .FOO
+\f
+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: <ATOM "FOO">
+FOO!-#FALSE() -- New ATOM not on any oblist.
+\f
+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 <GETPROP item indicator> 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: <PUTPROP FOO BAR BLECH>
+ <AVALUE <ASSOCIATIONS>>
+ BLECH
+ <GETPROP FOO BAR>
+ BLECH
+If this association is the most recent one made, the last two are equivalent.
+\f
+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" <OR VECTOR UVECTOR STRING TEMPLATE>
+ <PRIMTYPE <OR VECTOR UVECTOR STRING TEMPLATE>> "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: <SET X
+ <REST [A B C D E]
+ 3>>
+ [D E]
+ <BACK .X 1>
+ [C D E]
+.X, of course, is not changed by the BACK.
+\f
+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" <LIST ATOM LIST DECL ANY>)
+
+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: <BIND ((C <OPEN "READ" "FOO BAR">))
+ <COND (.C <FOO> <CLOSE .C>)>>
+This will FOO only if the file FOO BAR exists.
+\f
+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: <BITS 36>
+Points to a full PDP-10 word
+ <BITS 7 15>
+Points to third Ascii character position in word
+\f
+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" <UVECTOR [27 FIX]>
+ "OPTIONAL" <UVECTOR [27 ANY]>)
+
+(Optional)
+Argument 1 -- a uvector of length 27 at least
+Returns -- arg1 or a gratis uvector of storage statistics
+
+Example: <BLOAT-STAT>
+If no arg, a uvector is provided gratis.
+\f
+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: <BLOAT 10000 10000 100 100 100>
+Get lots of free and stack space.
+\f
+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" <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>
+ <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>)
+
+Argument 1 -- The new LIST of OBLISTs to become the new path.
+Returns -- Its argument.
+
+Example: <BLOCK (<MOBLIST <PARSE <STRING !\I .FOO>> 23>
+ <ROOT>)>
+
+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.
+\f
+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" <OR 'T FALSE> ATOM "OPTIONAL"
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+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: <SET FOO "ANYTHING">
+ <BOUND? FOO>
+This will return the Atom T, since FOO does have a local binding.
+ <UNASSIGN FOO>
+ <BOUND? FOO>
+This will return #FALSE (), since the Atom FOO has no local binding.
+ <PROG (FOO) <BOUND? FOO>>
+
+However this will also return the Atom T, since FOO does have a local
+binding.
+\f
+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: <BREAK-SEQ '<+ 1 1> <RESUMER>>
+Give the PROCESS that resumed me something to do.
+\f
+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: <BUFOUT .OUTCHAN>
+Flush buffers from OUTCHAN.
+\f
+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 <PRIMTYPE BYTES>)
+
+Argument 1 -- A BYTES
+Returns -- A FIX, which is the size of bytes of the BYTES.
+
+Example: <BYTE-SIZE #2 {}>
+ 2
+\f
+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" <TUPLE [REST <PRIMTYPE WORD>]>)
+
+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: <BYTES 2 0 1 2 3 4 5 6>
+ #2 {0 1 2 3 0 1 2}]
+\f
+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" <LIST [REST CHANNEL]>)
+
+Returns -- A LIST of all the CHANNELs currently open in a MUDDLE.
+
+Example: <CHANLIST>
+Only possible example
+\f
+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: <CHANNEL "PRINT" "FOO BAR">
+Return an unopened PRINT channel.
+\f
+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: <SET X (+ 1 2)>
+ (+ 1 2)
+Create a LIST
+ <CHTYPE .X FORM>
+ <+ 1 2>
+Returns a FORM
+ .X
+ (+ 1 2)
+But the original is untouched
+\f
+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" <PRIMTYPE UVECTOR>
+ <PRIMTYPE UVECTOR> 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: <SET X ![() () () () ()!]>
+ <CHUTYPE .X FORM>
+ ![<> <> <> <> <>!]
+New UTYPE.
+ .X
+ ![<> <> <> <> <>!]
+Note all references to UVECTOR get new UTYPE.
+\f
+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: <RESET <CLOSE <OPEN "READ" "DSK:FOO BAR">>>
+
+This pointless form will cause a CHANNEL to be opened (assuming the
+file exists), closed, and then reopened.
+\f
+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"
+ <TUPLE [REST ATOM]>)
+
+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: <CLOSURE <FUNCTION (X)
+ <SET .X <+ ..X .INC>>>
+ 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.
+\f
+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" <LIST LIST [REST LIST]>)
+
+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: <COND (<SET C <OPEN "READ" "FOO BAR">>
+ <LOAD .C>
+ <CLOSE .C>)>
+
+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).
+\f
+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:
+ <CONS .FOO .THE-LIST>
+ (.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: <CONS 1 (2 3 4)>
+note that this is equivalent to (1 !'(2 3 4))
+\f
+COS: Cosine of an angle
+
+Object-type: SUBR
+
+Category: ARITHMETIC
+
+Reference: SIN, ATAN
+
+
+Argument:
+
+ Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
+
+Argument 1 -- the angle in radians.
+Returns -- A FLOAT, the Cosine.
+
+Example: <+ <* <COS .X> <COS .X>>
+ <* <SIN .X> <SIN .X>>>
+ 1.0
+One of the common trig. identities.
+\f
+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: <CRLF>
+ T
+Output carriage-return and line-feed.
+\f
+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 <DECL-CHECK #FALSE()>, or enabled by
+<DECL-CHECK T>. 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" <OR FALSE ANY>
+ "OPTIONAL" <OR FALSE ANY>)
+
+(Optional)
+Argument 1 -- Any MUDDLE object. Non-false to enable DECL checking,
+ False to disable it.
+Returns -- The old state.
+
+Example: <DECL-CHECK T>
+Enables DECL checking.
+\f
+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" <OR 'T FALSE>
+ ANY <OR ATOM <FORM 'QUOTE FORM>>)
+
+Argument 1 -- an object to be checked
+Argument 2 -- a QUOTEd Pattern to check it against
+Returns -- T or a FALSE
+
+Example: <DECL? '[1 2 3] '<VECTOR [REST FIX]>>
+ T
+note QUOTE on Pattern
+\f
+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: <DEFINE FACTORIAL (N)
+ <COND
+ (<0? .N> 1)
+ (T
+ <* .N
+ <FACTORIAL <- .N 1>>>)>>
+Then <FACTORIAL 4> returns 24
+\f
+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: <DEFMAC INC (ATM "OPTIONAL" (N 1))
+ <FORM SET
+ .ATM
+ <FORM +
+ <FORM LVAL .ATM>
+ .N>>>
+ <SET X 1>
+ 1
+ <INC X>
+ 2
+ <EXPAND '<INC X>>
+ <SET X <+ .X 1>>
+The standard INC hack, in EVAL-macro form.
+\f
+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" <OR 'T FALSE> STRING)
+
+Argument 1 -- A STRING giving the name of a Daemon.
+Returns -- T if exists, FALSE otherwise.
+
+Example: <DEMSIG "COMDMN">
+Signal the communication Daemon.
+\f
+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 <GET .INCHAN INTERRUPT>>
+Disable the ^G and ^S interrupts.
+\f
+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: <DISMISS #FALSE ("FATAL ERROR DEEP IN GUTS")
+ .TOP-LEVEL-ACTIVATION>
+
+A construct like this could be used to signal to a higher level that
+somewhere in the code below it, a fatal error occured.
+\f
+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: <SET D <OPEN "DISPLAY" "E&S:">>
+ <DISPLAY .D .PIC>
+Where PIC is a Picture created previously in some manner.
+\f
+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: <ECHOPAIR .INCHAN .OUTCHAN>
+what LISTEN does
+\f
+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" <OR 'T FALSE> STRUCTURED)
+
+Argument 1 -- Any structured object.
+Returns -- T if the structured object has no elements, #FALSE () if it
+ has any elements at all.
+
+Example: <EMPTY? "---args---">
+This will return #FALSE ().
+ <EMPTY? ()>
+However, this will return T.
+\f
+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 <GET CLOCK!-INTERRUPTS INTERRUPT>>
+Enable a clock interrupt.
+\f
+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"
+ <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>)
+
+Returns -- The previous OBLIST path, now restored.
+
+Example: <ENDBLOCK>
+Only possible example.
+\f
+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: <ENTRY-LOC <RSUBR-ENTRY [,FOO FOO1] 347>>
+ 347
+This will return the offset given to RSUBR-ENTRY, which is the 347.
+\f
+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 [REST <PRIMTYPE WORD>]>)
+
+Tuple of arguments -- Primtype WORDs to be EQVed together.
+Returns -- A WORD.
+
+Example: <EQVB -22906492246 22906492245>
+ #WORD *000000000000*
+No bits in common.
+\f
+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: <SET D <OPEN "DISPLAY" "E&S:">>
+ <DISPLAY .D .PIC>
+ <ERASE .D .PIC>
+
+Display PIC and then remove it. (Where PIC is a Picture created
+previously in some manner).
+\f
+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: <ERRET T>
+
+Single most common use of ERRET -- continue from REDEFINE ERROR,
+return something innocuous as value of funny atom, and so on.
+\f
+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: <ERROR RAN-OUT-OF-INPUT!-ERRORS INPUT-HANDLER>
+Most common ERROR call format is this.
+\f
+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: <ERRORS>
+Only possible example.
+\f
+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"
+ <OR ACTIVATION FRAME ENVIRONMENT PROCESS>)
+
+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: <EVAL '<SET X <+ .X 1>> <RESUMER>>
+
+ 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.
+\f
+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 APPLICABLE FALSE> ATOM "OPTIONAL"
+ <OR ATOM APPLICABLE>)
+
+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: <EVALTYPE LIST FORM>
+ <EVALTYPE ATOM ,LVAL>
+ <SETG CAR 1>
+ <SETG CDR ,REST>
+ <SETG LAMBDA ,FUNCTION>
+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?
+\f
+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 <OR STRING ATOM IHEADER> FIX
+ "OPTIONAL" <OR CHANNEL LOCATIVE>)
+
+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: <SET TEM <EVENT "SYSDOWN" 1>>
+Setup a SYSDOWN interrupt.
+\f
+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 <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT to take e to the power of.
+Returns -- (e ** <argument 1>)
+
+Example: <EXP <LOG 2>>
+ 2.0
+Note conversion to floating point number.
+\f
+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: <DEFMAC INC (ATM "OPTIONAL" (N 1))
+ <FORM SET
+ .ATM
+ <FORM +
+ <FORM LVAL .ATM>
+ .N>>>
+ INC
+ <EXPAND '<INC X>>
+ <SET X <+ .X 1>>
+Note that <EVAL '<INC X>> would EVAL this last form too.
+\f
+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" <OR FALSE ATOM> "TUPLE" <REST STRING>)
+
+Argument 1-4 -- file names
+Returns -- T if file exists, a FALSE otherwise
+
+Example: <FILE-EXISTS? "DSK:FOO;.FILE. (DIR)">
+Will return T if FOO is a real directory.
+\f
+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: <ACCESS .IN <FILE-LENGTH .IN>>
+Next input will detect end of file.
+\f
+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: <FILECOPY <OPEN "READ" "TTY:.FILE. (DIR)">>
+like Monit's WHO
+\f
+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 <OR FLOAT FIX>)
+
+Argument 1 -- A FLOAT to convert
+Returns -- A FIX corresponding to the FLOAT.
+
+Example: <FIX 69.910496>
+ 69
+Note the truncating.
+\f
+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" <OR FALSE FIX> 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: <FLATSIZE (1 2 3) 10>
+Will be a fix result
+ <FLATSIZE (1 2 3) 5>
+Will be a FALSE
+\f
+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: <FLOAD "MUDDLE;FIXUP">
+part of initialization for TS file
+\f
+FLOAT: Convert a FIX to a FLOAT
+
+Object-type: SUBR
+
+Category: TYPE-MANIPULATION, ARITHMETIC
+
+Reference: FIX
+
+
+Argument:
+
+ Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
+
+Argument 1 -- A FIX to convert to a FLOAT.
+Returns -- The new FLOAT.
+
+Example: <FLOAT 69>
+ 69.0
+CHTYPE would lose, of course.
+\f
+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 [REST ANY]>)
+
+Tuple of arguments -- Any objects, the elements of the FORM.
+Returns -- The FORM created.
+
+Example: <DEFINE INCR (N)
+ <FORM SET
+ .N
+ <FORM + 1 <FORM LVAL .N>>>>
+this returns the form <SET FOO <+ 1 .FOO>> when called with FOO as arg
+\f
+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" <OR ENVIRONMENT
+ ACTIVATION
+ FRAME
+ PROCESS>)
+
+(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: <DEFINE FRAMES ("OPTIONAL" (PROC <ME>))
+ <REPEAT ((X <FRAME .PROC>)
+ (N 1))
+ <COND (<==? <FUNCT .X> TOPLEVEL>
+ <RETURN TOPLEVEL>)>
+ <PRINT .N>
+ <PRIN1 <FUNCT .X>>
+ <PRINC <ASCII 9>>
+ <PRIN1 <ARGS .X>>
+ <SET X <FRAME .X>>
+ <SET N <+ 1 .N>>>>
+A primitive version of the FRAMES function installed in MUDDLE.
+\f
+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" <OR PROCESS FALSE> PROCESS)
+
+Argument 1 -- A PROCESS to return to normal running mode.
+Returns -- The PROCESS, or FALSE if PROCESS not in one-step mode.
+
+Example: <FREE-RUN .FOO>
+Now will run free when RESUMEd.
+\f
+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" <PRIMTYPE STORAGE> <PRIMTYPE STORAGE>)
+
+Argument 1 -- A storage: the space to be released.
+Returns -- The same storage -- better not hold on to it.
+
+Example: <FREE <ISTORAGE 69 0>>
+Free up newly created STORAGE.
+\f
+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" <OR VECTOR UVECTOR STRING>
+ <OR <PRIMTYPE VECTOR>
+ <PRIMTYPE TUPLE>
+ <PRIMTYPE UVECTOR>
+ <PRIMTYPE STRING>>)
+
+Argument 1 -- a vector, tuple, uvector, or string to freeze
+Returns -- a frozen copy of arg1
+
+Example: <FREEZE <1 ,MY-RSUBR>>
+to debug an RSUBR
+\f
+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
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+Argument 1 -- an environment
+Returns -- The ATOM which is the name of the object which caused the
+ FRAME to be created.
+
+Example: <FUNCT <FRAME>>
+ LISTEN
+If done at top level.
+\f
+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: <FUNCTION (N) <+ 1 .N>>
+equivalent to #FUNCTION ((N) <+ 1 .N>)
+\f
+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" <OR 'T FALSE>
+ <OR FIX FLOAT> <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT.
+Argument 2 -- A FIX or FLOAT.
+Returns -- T if arg1 >= arg2, #FALSE() if not.
+
+Example: <G=? 2.4499998 -2>
+ <G=? -7.2300000 -10.039999>
+ <G=? 23 23.0>
+These will return T.
+ <G=? -0.42699999E-2 0.20409999>
+ <G=? 6 9.5709997>
+These will return #FALSE ().
+\f
+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" <OR 'T FALSE>
+ <OR FIX FLOAT> <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT.
+Argument 2 -- A FIX or FLOAT.
+Returns -- T if arg1 > arg2, #FALSE() if not.
+
+Example: <G? 3 2>
+ <G? -3.4230000 -5>
+These will return T.
+ <G? 0.35240000 0.34169999>
+ <G? -146 -113>
+ <G? 1.0 1>
+These will return #FALSE ().
+\f
+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" <OR 'T FALSE> ATOM)
+
+Argument 1 -- An ATOM which may have a global value.
+Returns -- T if the ATOM has a global value, #FALSE() otherwise.
+
+Example: <SETG FOO "ANYTHING">
+ <GASSIGNED? FOO>
+This will simply return the Atom T, since FOO does have a global
+value.
+ <GUNASSIGN FOO>
+ <GASSIGNED? FOO>
+This will simply return #FALSE (), since the Atom FOO has no global
+value.
+\f
+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" <OR 'T FALSE> ATOM)
+
+Argument 1 -- the atom to test
+Returns -- whether or not the atom is globally bound
+
+Example: <GBOUND? GBOUND?>
+ T
+obviously
+\f
+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" <OR ANY <UVECTOR <PRIMTYPE WORD>>>
+ ANY <OR CHANNEL FALSE>)
+
+Argument 1 -- the object to be dumped
+Argument 2 -- "PRINTB/O" channel or false
+Returns -- arg1 if arg2 is channel, else output data
+
+Example: <GC-DUMP <PROG ((L (1 2)))
+ <PUTREST .L .L>>
+ <>>
+can dump circular objects
+\f
+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: <GC-MON T>
+Turn on GC-monitoring
+\f
+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: <SET L
+ <PROG (O
+ (C <OPEN "READB" "DUMPED FILE">))
+ <STACKFORM ,LIST
+ .O
+ <SET O
+ <GC-READ .READB-CHNL <>>>>>>
+get all GC-DUMPed objects from a file
+\f
+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 <OR FALSE ANY> 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 30000 <>>
+GC and change a GC parameter
+\f
+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 [REST
+ <LIST [REST ATOM]>
+ <OR ATOM FORM>]>)
+
+List of arguments -- Pairs consisting of a LIST of ATOMs and a
+ DECL body.
+Returns -- T
+
+Example: <GDECL (FOO)
+ FIX
+ (BAR)
+ <LIST [REST LIST]>>
+Just like local DECLs.
+\f
+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" <OR ATOM FORM FALSE> <OR LOCD OFFSET>)
+
+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: <SET FOO (1 2 3)>
+ <SET BAR (4 5 6)>
+ <GDECL (FOO BAR) LIST>
+ <GET-DECL <GLOC FOO>>
+ LIST
+
+ <GET-DECL <OFFSET 1 '<CHANNEL FIX>>>
+ <CHANNEL FIX>
+
+See also PUT-DECL, for changing declarations.
+\f
+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: <PROG ((A (1 2 3 4)))
+ <PUT .A 2 5>
+ <PUTPROP .A 3 6>
+ <PUT .A X "STRING">
+ (.A
+ <GET .A 2>
+ <GETPROP .A 3>
+ <GET .A X>)>
+Notice the difference between the PROP and non-prop subrs
+\f
+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 <BITS 7>
+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 <PRIMTYPE <OR WORD STORAGE>> 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: <GETBITS -1 <BITS 3>>
+ #WORD *000000000007*
+Non-WORDs need not be CHTYPEd.
+\f
+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" <OR LOCATIVE ANY> 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: <PROG ((A (1 2 3 4)))
+ <PUT .A 2 5>
+ <PUTPROP .A 3 6>
+ <PUT .A X "STRING">
+ (.A
+ <GETL .A 2>
+ <GETPL .A 3>
+ <GETL .A X>)>
+Notice the difference between the PROP and non-prop subrs
+\f
+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" <OR LOCAS ANY> 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: <PROG ((A (1 2 3 4)))
+ <PUT .A 2 5>
+ <PUTPROP .A 3 6>
+ <PUT .A X "STRING">
+ (.A
+ <GETL .A 2>
+ <GETPL .A 3>
+ <GETL .A X>)>
+Notice the difference between the PROP and non-prop subrs
+\f
+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: <PROG ((A (1 2 3 4)))
+ <PUT .A 2 5>
+ <PUTPROP .A 3 6>
+ <PUT .A X "STRING">
+ (.A
+ <GET .A 2>
+ <GETPROP .A 3>
+ <GET .A X>)>
+Notice the difference between the PROP and non-prop subrs
+\f
+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" <OR FALSE ANY>)
+
+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: <AND <GASSIGNED? FOO> <GLOC FOO>>
+Guard against ATOMs with no GVALs.
+\f
+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 <OR ATOM TAG>)
+
+Argument 1 -- where to go to
+Returns -- RESUME arg, if tag lay in another process
+
+Example: <PROG (&)
+ <&>
+ AWAY
+ <FOO>
+ <&>
+ <GO AWAY>
+ &..>
+exactly what GO should do
+\f
+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" <PRIMTYPE <OR VECTOR UVECTOR>>
+ <PRIMTYPE <OR VECTOR UVECTOR>> 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: <GROW ![1 2 3!] 1 1>
+will grow by 32 on each end.
+\f
+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 GUNASSIGN>
+ GUNASSIGN
+Something you only do once.
+\f
+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 ,<an atom> and <GVAL <an atom>> 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!
+\f
+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 <OR HANDLER
+ APPLICABLE>
+ "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: <HANDLER <SET TEM <EVENT "CHAR" 10 .INCHAN>>
+ ,QUITTER>
+Setup a character interrupt with one handler.
+\f
+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 .FOO>
+Hang until someone (at interrupt level) sets FOO to a non-FALSE.
+\f
+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: <IBYTES 3 9 '<COND (<ASSIGNED? X> <SET X <+ 1 .X>>) (<SET X 0>)>>
+ #3 {0 1 2 3 4 5 6 7 0}
+\f
+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: <SET ROOTL <LENGTH <ROOT>>>
+ <IFORM 5 '<1 <NTH <ROOT> <MOD <RANDOM> .ROOTL>>>>
+
+Makes a FORM by picking the first elements of 5 randomly selected
+buckets in the ROOT OBLIST.
+\f
+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: <ILIST 5 0>
+Create a LIST containing five 0s.
+\f
+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: <IMAGE 1>
+ 1
+ <IMAGE 2>
+ 2
+draws an I-beam on an Imlac
+\f
+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: <SET FOO 69>
+ <IN <LLOC FOO>>
+ 69
+Like LVAL except independent of rebindings of FOO.
+\f
+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: <SET CHNUM <OFFSET 1 '<CHANNEL FIX>>>
+ %<OFFSET 1 '<CHANNEL FIX>>
+ <INDEX .CHNUM>
+ 1
+Use GET-DECL to get the DECL part of the OFFSET.
+\f
+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: <PUTPROP FOO BAR BLECH>
+ <ITEM <ASSOCIATIONS>>
+ FOO
+ <INDICATOR <ASSOCIATIONS>>
+ BAR
+ <AVALUE <ASSOCIATIONS>>
+ BLECH
+ASSOCIATIONS gets newest ASOC.
+\f
+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 <OR ATOM STRING> 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: <INSERT "GVAL" <ROOT>>
+This will fail, as the ATOM is already there.
+ <OR <LOOKUP "GVAL" <ROOT>> <INSERT "GVAL" <ROOT>>>
+Guaranteed to win.
+\f
+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: <INT-LEVEL <MIN>>
+Cause all interrupts to be deferred.
+\f
+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" <OR 'T FALSE> <OR IHEADER STRING ATOM> "TUPLE"
+ <TUPLE [REST ANY]>)
+
+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: <INTERRUPT "FOO" 1 2 3>
+Causes a FOO interrupt if an IHEADER exists.
+\f
+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: <INTERRUPTS>
+Only possible invocation.
+\f
+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 <OR STRING UVECTOR STORAGE> 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: <IPC-HANDLER "HELLO, HOW ARE YOU." 0 "CLR" "MUDDLE">
+
+Just prints this out. Actually you would never see or invoke this
+form, since only happens at interrupt level.
+\f
+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: <IPC-OFF>
+In virgin MUDDLE, disable default IPC handler, IPC-HANDLER.
+\f
+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: <IPC-ON>
+Usually jobs listen on their uname-jname to avoid confusion.
+\f
+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: <ISTORAGE 10 '<RANDOM>>
+Create a STORAGE with random contents.
+\f
+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: <ISTRING 20 '<CHTYPE <MOD <RANDOM> 128> CHARACTER>>
+Note the CHTYPEing to type CHARACTER.
+\f
+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: <PUTPROP FOO BAR BLECH>
+ <ITEM <ASSOCIATIONS>>
+ FOO
+ <INDICATOR <ASSOCIATIONS>>
+ BAR
+ <AVALUE <ASSOCIATIONS>>
+ BLECH
+ASSOCIATONS gets newest ASOC.
+\f
+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: <PROG ((A <ITUPLE 4 0>))
+ <PUT .A 2 3>
+ (!.A)>
+This is a valid usage of ITUPLE.
+
+ <DEFINE FOO (A
+ "AUX" (X
+ <REST <ITUPLE !.A>>))
+ .X>
+
+This is not a valid usage of ITUPLE, since the application is not at
+top level of the atom-value pair.
+\f
+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: <PROG ((A 2))
+ <IUVECTOR 5
+ '<SET A
+ <* .A .A>>>>
+Powers of 2.
+\f
+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: <IVECTOR 5 "ha">
+ ["ha" "ha" "ha" "ha" "ha"]
+Comedic vector.
+\f
+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: <JNAME>
+Only possible example.
+\f
+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" <OR 'T FALSE>
+ <OR FIX FLOAT> <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT.
+Argument 2 -- A FIX or FLOAT.
+Returns -- If arg1 <= arg2, T, else #FALSE().
+
+Example: <L=? 2 12>
+ <L=? -5.7308998 0.95000000E-2>
+ <L=? 23 23.0>
+These will return T.
+ <L=? 34 -3>
+ <L=? 13.000100 13>
+ <L=? -3.9530000 -4.0241000>
+These will return #FALSE ().
+\f
+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" <OR 'T FALSE>
+ <OR FIX FLOAT> <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT.
+Argument 2 -- A FIX or FLOAT.
+Returns -- T if arg1 < arg2, #FALSE() otherwise.
+
+Example: <L? 1 2>
+ <L? -2 4.0>
+ <L? -13.462000 -0.93000000E-1>
+These will return T.
+ <L? -12.340000 -12.340010>
+ <L? 3.1415899 3.1415899>
+These will return #FALSE ().
+\f
+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" <OR 'T FALSE> 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: <LEGAL? <PROG ("NAME" FOO) .FOO>>
+This will be False, since the activation is not legal outside the PROG.
+ <PROG ("NAME" FOO) <LEGAL? .FOO>>
+However, this will be True, since the activation is legal inside the
+PROG.
+\f
+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: <LENGTH <SET X (1 2 3 4 5)>>
+ 5
+Winnage.
+ <LENGTH <PUTREST <REST .X 4> .X>>
+Never returns, X is circular now.
+\f
+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 <==? <LENGTH s.o.> fix>
+or alternatively <G=? <LENGTH s.o.> fix>. Neither of these are what
+it does. It is actually closer to <L=? <LENGTH s.o.> 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" <OR FIX FALSE> 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: <SET FOO
+ <PUTREST <REST <SET FOO (1 2 3)> 2>
+ .FOO>>
+Returns circular list.
+ <LENGTH .FOO>
+Will never return.
+ <LENGTH? .FOO 69>
+ #FALSE ()
+Will work.
+\f
+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: <LINK '<ERRET> "\ 5">
+Links the ATOM of PNAME ^E to <ERRET>.
+\f
+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 [REST ANY]>)
+
+Tuple of arguments -- ANY, the elements
+
+Example: <SET X <LIST 1 2 3 4 5>>
+equivalent to (1 2 3 4 5)
+ <==? .X <LIST !.X>>
+ #FALSE ()
+ <==? .X (!.X)>
+ T
+
+Slight difference does exist between explicit application of LIST and
+using parens.
+\f
+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 <TTYECHO .INCHAN T> and <ECHOPAIR .INCHAN .OUTCHAN>
+(3) PRINTs its arguments on .OUTCHAN
+(4) PRINTs LISTENING-AT-LEVEL l PROCESS p INT-LEVEL i [as appropriate]
+(5) Either does <APPLY <VALUE REP>> 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: <LISTEN "LISTEN UP, YOU YOYOS!">
+not an overly stupid example
+\f
+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"
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+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: <PROG ((X 3) (XL <LLOC X>))
+ <PROG ((X 69105)) <PRINT <IN .XL>>>>
+Will always print 3.
+\f
+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"
+ <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>)
+
+Argument 1 -- the channel to load from
+(Optional)
+Argument 2 -- (list of) oblist(s) for looking up atoms
+Returns -- "DONE"
+
+Example: <LOAD <OPEN "READ" "MANY ATOMS"> <ROOT>>
+make yourself root-bound
+\f
+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" <OR FALSE 'T> ANY)
+
+Argument 1 -- Any MUDDLE object.
+Returns -- T argument 1 is a locative, or FALSE if it is not.
+
+Example: <LOCATIVE? <GLOC ROOT>>
+ T
+ <LOCATIVE? <AT [1 2 3] 1>>
+ T
+ <LOCATIVE? <LLOC REDEFINE>>
+ T
+All are locatives.
+\f
+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 <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT to take the LOG of.
+Returns -- The log base e of argument 1.
+
+Example: <EXP <LOG 2>>
+ 2.0
+Note conversion to floating point number.
+\f
+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: <LOGOUT>
+Never returns if it wins.
+\f
+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" <OR ATOM FALSE> 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: <OR <LOOKUP "FOO" .OB>
+ <INSERT "FOO" .OB>>
+
+Recommended way of safely inserting ATOMs. Guaranteed to return the
+ATOM of pname "FOO".
+\f
+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:
+
+ <PARSE string radixfornumberconversion oblistorlistofoblists
+ parsetable lookaheadchar>
+
+ 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:
+
+ <LPARSE string radixfornumberconversion oblistorlistofoblists
+ parsetable lookaheadchar>
+
+
+Argument:
+
+ Template: #DECL ("VALUE" LIST "OPTIONAL" STRING
+ FIX <OR OBLIST
+ <LIST [REST <OR OBLIST 'DEFAULT>]>>
+ 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: <LPARSE "() 1 A">
+ (() 1 A)
+Will return a list of three elements.
+\f
+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
+ <PRIMTYPE 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: <LSH 8 6>
+ #WORD *000000001000*
+ <LSH 8 -6>
+ #WORD *000000000000*
+Primarily useful for getting fingers directly in the bits.
+\f
+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"
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+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
+\f
+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: <==? <MAIN> <ME>>
+Is the PROCESS I am in the main process?
+\f
+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 [REST ATOM]>)
+
+Tuple of arguments -- ATOMs whose GVALs are constants.
+Returns -- T.
+
+Example: <SETG A 1>
+ <SETG B 2>
+ <MANIFEST A B>
+Most common use of MANIFEST.
+\f
+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" <OR 'T FALSE> ATOM)
+
+Argument 1 -- An ATOM.
+Returns -- T if it is MANIFEST, FALSE if it is not.
+
+Example: <SETG FOO 1>
+ <MANIFEST FOO>
+ <MANIFEST? FOO>
+ T
+ <UNMANIFEST FOO>
+ <MANIFEST? FOO>
+ #FALSE ()
+Make it a constant, then make it not a constant.
+\f
+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 <OR FALSE APPLICABLE> APPLICABLE
+ "TUPLE" <TUPLE STRUCTURED [REST STRUCTURED]>)
+
+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: <MAPF ,LIST ,+ '(1 2 3 4) '(10 11 12 13)>
+This will perform the element-wise sum of two lists
+\f
+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: <MAPF <>
+ <FUNCTION (X)
+ <COND (<N==? .X 0> <MAPLEAVE .X>)>>
+ .STRUC>
+This example will find and return the first non-zero element of STRUC
+\f
+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 <OR FALSE APPLICABLE> APPLICABLE
+ "TUPLE" <TUPLE STRUCTURED [REST STRUCTURED]>)
+
+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: <MAPR <>
+ <FUNCTION (OB)
+ <PUT .OB 1 <* <1 .OB> 2>>>
+ .STRUC>
+This will change the structure STRUC to contain double its values.
+\f
+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 [REST ANY]>)
+
+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: <MAPRET>
+This is used when one desires to return nothing.
+\f
+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 [REST ANY]>)
+
+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: <PROG ((I 10))
+ <MAPF ,LIST
+ <FUNCTION (X)
+ <COND (<L? <SET I <- .I 1>> 0>
+ <MAPSTOP>)>
+ .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.
+\f
+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" <OR FIX FLOAT>
+ "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
+
+(Optional)
+Tuple of arguments -- FIXes and FLOATs
+Returns -- FIX or FLOAT, floating is contagious.
+
+Example: <MAX 1 2.0>
+ 2.0
+Floating is contagious.
+\f
+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: <==? <MAIN> <ME>>
+Am I the main process?
+\f
+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" <OR FALSE STRUCTURED> 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: <MEMBER 69 [105 104 32 69 81]>
+ [69 81]
+MEMQ would do the same for this example.
+ <MEMBER "FOO" ["BAR" "FOO" "BLECH"]>
+But not for this example. Different strings are =? not ==?.
+\f
+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" <OR FALSE STRUCTURED> 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: <MEMQ 69 [105 104 32 69 81]>
+ [69 81]
+The copy is now the first element.
+\f
+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" <OR FIX FLOAT>
+ "TUPLE" <TUPLE [REST <OR FIX FLOAT>]>)
+
+(Optional)
+Tuple of arguments -- FIXes and FLOATs
+Returns -- FIX or FLOAT, depending on whether any args were FLOAT.
+
+Example: <MIN 1 2.0>
+ 1.0
+Takes any number of args
+\f
+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: <PROG ((OBLIST (<MOBLIST MY-OBLIST> !.OBLIST)))
+ AN-ATOM!-MY-OBLIST
+ <GET MY-OBLIST OBLIST>>
+The oblist is placed in the path by the setting of the atom OBLIST
+\f
+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: <MOD <RANDOM> 30>
+How to get a random number between 0 and 30.
+\f
+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 <NOT <STRUCTURED? object>> and
+<EMPTY? object>.
+
+Argument:
+
+ Template: #DECL ("VALUE" <OR 'T FALSE> ANY)
+
+Argument 1 -- Any MUDDLE object.
+Returns -- T if NTH and REST will not work on the object, FALSE if
+ they will work.
+
+Example: <OR <NOT <STRUCTURED? .FOO>>
+ <EMPTY? .FOO>>
+ <MONAD? .FOO>
+Result is the same for these two forms.
+\f
+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" <OR 'T FALSE> ANY ANY)
+
+Argument 1 -- Any object.
+Argument 2 -- Another object.
+Returns -- T if the two objects are different objects, FALSE otherwise.
+
+Example: <N==? "FOO" "FOO">
+ T
+These two STRINGs look identical, but are not.
+\f
+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" <OR 'T FALSE> 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: <N=? <SET V <VECTOR 1 2 3>> <EVAL .V>>
+ #FALSE ()
+If the test were =?, the result would be T.
+\f
+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" <OR FALSE CHANNEL> CHANNEL)
+
+Argument 1 -- A Network channel (a listening socket).
+Returns -- The channel, or FALSE if it is in the wrong state.
+
+Example: <NETACC <OPEN "READ" -1 -1 "NET">>
+Accept the listening socket.
+\f
+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: <NETS .NETCHAN>
+What else?
+\f
+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" <UVECTOR FIX FIX FIX> 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: <NETSTATE <OPEN "READ" -1 -1 "NET">>
+Give state of a network channel open for listening.
+\f
+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:
+
+ #<name of type> <print representation of primtype>
+
+For example, a <NEWTYPE FOO LIST> 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 <EVALTYPE FOO LIST>.
+ 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" <OR ATOM <FORM 'QUOTE FORM>>)
+
+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: [<NEWTYPE BAR LIST>
+ "Simple newtype"
+ <NEWTYPE BAR
+ LIST
+ '<<PRIMTYPE LIST> BAR [REST FIX FLOAT]>>
+ "More strongly specified, even recursive."]
+\f
+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" <OR FALSE ASOC> 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: <NEXT <ASSOCIATIONS>>
+Get second association in chain.
+\f
+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" <OR CHARACTER FIX> "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: <NEXTCHR>
+ !\\e
+what you get if called by itself
+\f
+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" <OR 'T FALSE> ANY)
+
+Argument 1 -- ANY object.
+Returns -- The logical complement of the truth value of the object.
+
+Example: <NOT <NOT #FALSE ("FILE NOT FOUND")>>
+ #FALSE ()
+Note the loss of detail in complementing the complement.
+\f
+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:
+
+ <NTH .X 1>
+ and <1 .X>
+are equivalent, but
+
+ <NTH .X <LENGTH <SET X .Y>>>
+ and <<LENGTH <SET X .Y>> .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)>
+ <NTH (4 5 6) 2>
+
+The first is equivalent to the second as long
+as order of evaluation makes no difference.
+\f
+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" <OR OBLIST FALSE> ATOM)
+
+Argument 1 -- An ATOM.
+Returns -- Either the OBLIST that ATOM is on, or FALSE if it is not on
+ any OBLIST.
+
+Example: <OBLIST? FOO>
+...SOME OBLIST....
+ <OBLIST? <REMOVE FOO>>
+ #FALSE ()
+
+If you type in the ATOM as part of the form, it will naturally be on
+an OBLIST.
+\f
+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" <OR FALSE IHEADER HANDLER>
+ <OR IHEADER HANDLER STRING ATOM> "OPTIONAL"
+ <OR CHANNEL LOCATIVE>)
+
+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: <OFF "CLOCK">
+Turns off the CLOCK interrupt.
+\f
+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 <OR ATOM FORM>)
+
+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: <SET O <OFFSET 1 '<CHANNEL FIX>>>
+ %<OFFSET 1 '<CHANNEL FIX>>
+
+\f
+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.
+
+ <ON "CLOCK" ,FOO 1 ,P>
+
+is equivalent to
+
+ <HANDLER <EVENT "CLOCK" 1> ,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 <OR STRING ATOM> APPLICABLE FIX "OPTIONAL"
+ <OR FIX PROCESS> <OR CHANNEL LOCATIVE>)
+
+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: <ON "CLOCK" <FUNCTION () <PRINC " TICK ">> 1>
+\f
+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" <OR CHANNEL <FALSE STRING STRING FIX>>
+ "OPTIONAL" STRING "TUPLE" TUPLE)
+
+(Optional)
+Argument 1 -- mode
+Tuple of arguments -- 'file specification'
+Returns -- channel or false giving reason for failure & filename
+
+Example: <OPEN-NR "READ" "OLD FILE">
+so it will be reaped sooner
+\f
+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:
+ <VALUE NM1>, if any, else "INPUT"
+ <VALUE NM2>, if any, else ">"
+ <VALUE DEV>, if any, else "DSK"
+ <VALUE SNM>, if any, else the 'working directory'
+For more details, see the manual, SYS.11.01.
+
+Argument:
+
+ Template: #DECL ("VALUE" <OR CHANNEL <FALSE STRING STRING FIX>>
+ "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: <OPEN "PRINT" "TPL:">
+Make a channel for line-printer output.
+\f
+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 <OR preconditions thing> 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" <OR FALSE ANY> "ARGS" LIST)
+
+List of arguments -- ANY evalable objects.
+Returns -- Terminating non-FALSE or FALSE if all elements were FALSE.
+
+Example: <OR <LOOKUP "FOO" <ROOT>> <INSERT "FOO" <ROOT>>>
+
+This construct only attempts to insert FOO in the ROOT if it is not
+already there, avoiding the possibility of an ERROR.
+\f
+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" <OR FALSE ANY> "TUPLE" TUPLE)
+
+Tuple of arguments -- ANY objects.
+Returns -- Terminating non-FALSE or FALSE if all elements were FALSE.
+
+Example: <MAPF ,OR? <FUNCTION (T) <G? .T 0>> .VECTOR>
+Is any element of VECTOR positive?
+\f
+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 [REST <PRIMTYPE WORD>]>)
+
+Tuple of arguments -- Objects of primtype WORD to be ORed together.
+Returns -- A WORD containing the bitwise OR of the arguments.
+
+Example: <ORB #WORD *000000000001*
+ #WORD *000000000001*
+ #WORD *000000042260*>
+ #WORD *000000042261*
+Primarily useful for getting fingers directly in the bits.
+\f
+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" <OR 'T '#FALSE ()>
+ "OPTIONAL" <OR ANY FALSE>)
+
+(Optional)
+Argument 1 -- whether or not to enable over/underflow errors
+Returns -- the previous state, initially true, or current state if no arg
+
+Example: <OVERFLOW T>
+the initial state
+\f
+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:
+
+ <PARSE string radixfornumberconversion oblistorlistofoblists
+ parsetable lookaheadchar>
+
+
+Argument:
+
+ Template: #DECL ("VALUE" ANY "OPTIONAL" STRING
+ FIX <OR OBLIST
+ <LIST [REST <OR OBLIST 'DEFAULT>]>>
+ 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: <PARSE "<+ 1 2>">
+Returns the FORM <+ 1 2>.
+\f
+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 %<PCODE "&" &>.
+
+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: <PCODE "PPRINT" 0>
+Calls like this fill FBIN files.
+\f
+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: <PNAME \ \ \ !-FOO!-BAR>
+
+Just three spaces, no backslashes, no trailers.
+\f
+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: <PRIMTYPE-C <NEWTYPE FOO TEMPLATE>>
+returns a 'storage type code' for my template
+\f
+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: <TYPE 1>
+ FIX
+ <PRIMTYPE 1>
+ WORD
+
+PRIMTYPE will obviously return the same result for a larger class of
+objects than will TYPE.
+\f
+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: <PRIN1 .X>
+boring example, sorry
+\f
+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: <PROG ()
+ <TERPRI>
+ <PRINC "LISTENING-AT-LEVEL MEZZANINE PROCESS CHEESE">
+ <TERPRI>>
+Amaze your friends!
+\f
+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: <PRINT .X>
+not a very wonderful example
+\f
+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" <OR UVECTOR STORAGE>
+ <<OR UVECTOR STORAGE> [REST <PRIMTYPE WORD>]> CHANNEL)
+
+Argument 1 -- the buffer whose contents to write
+Argument 2 -- the output channel, open in PRINTB or PRINTO mode
+Returns -- arg1
+
+Example: <PRINTB .BUFFER .PRINTB-CHNL>
+Can't use a console channel.
+\f
+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: <READSTRING .TRASH
+ .STY-IN
+ <PRINTSTRING "HI THERE!" .STY-OUT>>
+Suck out the echoed characters on your pseudo-console.
+\f
+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" <OR ATOM APPLICABLE FALSE> ATOM "OPTIONAL"
+ <OR ATOM APPLICABLE>)
+
+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: <PRINTTYPE FORM LIST>
+Combine with example for EVALTYPE and make MUDDLE look like LISP.
+ <PRINTTYPE FORM <FUNCTION (X) <PRINC "FOO">>>
+Confuse your friends.
+\f
+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:
+ <SET P <PROCESS ,LISTEN>>
+Creates a process which is a read-eval-print loop like <MAIN>.
+ <STATE .P>
+ RUNABLE
+Means P has never run.
+ <RESUME T .P>
+Starts it.
+
+To treat a process like a simple function:
+ <RESUME T <PROCESS <FUNCTION (X) .X>>>
+Starts it, returns the result of applying arg1 (T) to the function,
+and then dies.
+\f
+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" <LIST ATOM LIST DECL ANY>)
+
+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: <PROG ((C <OPEN "READ" "FOO BAR">))
+ <COND (.C
+ <FOO>
+ <CLOSE .C>)>>
+This will FOO only if the file FOO BAR exists.
+\f
+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: <PURIFY .GROUP>
+OK if no RSUBRs in the group
+\f
+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 <DECL-CHECK> 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 <OR LOCD OFFSET> <OR ATOM <FORM 'QUOTE FORM>>)
+
+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: <SETG FOO 1>
+ 1
+ <GDECL (FOO) <PRIMTYPE WORD>>
+ T
+ <GET-DECL <GLOC FOO>>
+ <PRIMTYPE WORD>
+ <PUT-DECL <GLOC FOO> FIX>
+returns locative here
+ <PUT-DECL <GLOC FOO> VECTOR>
+here ERROR, type mismatch, as GVAL of FOO is FIX.
+
+ <PUT-DECL <SET X <OFFSET 1 '<FOO FIX>>> '<CHANNEL FIX>>
+ %<OFFSET 1 '<CHANNEL FIX>>
+Note that this is a new OFFSET:
+ .X
+ %<OFFSET 1 '<FOO FIX>>
+
+\f
+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: <PUT FOO 1 BAR>
+Like PUTPROP.
+ <PUT .FOO 1 BAR>
+If .FOO is structured, clobber its first element.
+\f
+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" <PRIMTYPE WORD> <PRIMTYPE WORD> BITS
+ "OPTIONAL" <PRIMTYPE WORD>)
+
+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: <PUTBITS -1 <BITS 6 3>>
+ -505
+Args need not be of type WORD.
+\f
+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: <PUTPROP .FOO 1 BAR>
+Makes association.
+ <PUT .FOO 1 BAR>
+If .FOO is structured, clobber its first element, else make association.
+\f
+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" <PRIMTYPE LIST>
+ <PRIMTYPE LIST> <PRIMTYPE LIST>)
+
+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: <PUTREST <REST <SET X (1 2 3)> 2> (4 5 6)>
+ (3 4 5 6)
+.X will now be (1 2 3 4 5 6).
+ <PUTREST <SET CIRCULAR (0)> .CIRCULAR>
+Create a circular LIST of one element.
+\f
+QUIT: Kill a MUDDLE
+
+Object-type: SUBR
+
+Category: SYSTEM
+
+Reference: LOGOUT, VALRET
+
+ Causes a MUDDLE to VALRET the string ':KILL<cr>' to its
+superior. This will cause the superior to kill the MUDDLE job.
+
+Argument:
+
+ Template: #DECL ()
+
+Never returns.
+
+Example: <QUIT>
+Only possible example.
+\f
+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 <FRAMES> to a MUDDLE.
+\f
+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 <QUOTE object>.
+
+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.
+ '(<PUSH TP* (TB)>
+ <PUSH TP* (TB) 1>
+ <MCALL 1 PRINC>)
+This will return a list of Forms.
+\f
+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: <MOD <RANDOM> 30>
+How to generate a random number between 0 and N.
+\f
+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
+ <OR OBLIST <LIST [REST <OR OBLIST 'DEFAULT>]>>
+ VECTOR)
+
+(Optional)
+Argument 1 -- input channel, default .INCHAN
+Argument 2 -- object to eval and return at end of file, default
+ <ERROR END-OF-FILE!-ERRORS>
+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: <SET NEWOBJ <READ>>
+Calls like this make you CALICO-incompatible.
+\f
+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
+ <<OR UVECTOR STORAGE> [REST <PRIMTYPE WORD>]> 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: <READB <OPEN "READB" "DSK:.FILE. (DIR)">
+ <IUVECTOR 1024 '0>>
+Get your file directory in binary form.
+\f
+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" <OR CHARACTER FIX> "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: <READCHR>
+ !\\e
+If called alone, you get the ESC.
+\f
+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 <OR FIX STRING>
+ 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: <READSTRING " ">
+ 1
+You get the ESC if called alone.
+\f
+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" <OR FIX FLOAT> <OR FIX FLOAT>)
+
+Argument 1 -- Interval between Real-time interrupts (in seconds).
+Returns -- Argument 1.
+
+Example: <REALTIMER <* 10 60>>
+Interrupt every ten minutes.
+\f
+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" <OR ATOM FALSE> <OR ATOM STRING> "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: <INSERT <REMOVE FOO> <ROOT>>
+You can move ATOMs from one OBLIST to another with REMOVE and INSERT.
+\f
+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" <OR 'T <FALSE STRING FIX>>
+ "TUPLE" <TUPLE <OR STRING CHANNEL>>)
+
+Tuple of arguments -- rename or delete action (see description)
+Returns -- whether it succeeded
+
+Example: <RENAME "FOO 3" TO "BAR">
+ T
+Rename FOO 3 to BAR >.
+ <RENAME "FOO FOO DSK:HARRY;">
+ T
+Delete that file.
+\f
+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 <VALUE REP>.
+
+Argument:
+
+ Template: #DECL ("VALUE" ANY)
+
+Returns -- argument to ERRET
+
+Example: <REP>
+no arguments
+\f
+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" <LIST ATOM LIST DECL ANY>)
+
+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: <REPEAT ((C ()))
+ <COND (<N==? <1 <SET C (<RANDOM> !.C)>> 69>)
+ (ELSE <RETURN .C>)>>
+This will create a LIST of random numbers until RANDOM returns 69.
+\f
+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" <OR CHANNEL <FALSE STRING STRING FIX>> CHANNEL)
+
+Argument 1 -- the channel to reset
+Returns -- arg1 or a false if reopen failed
+
+Example: <RESET ,INCHAN>
+after detaching and moving to a different console
+\f
+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: <SET A <REST [1 2 3 4] 3>>
+ [4]
+ <SET B <BACK .A>>
+ [3 4]
+ <SET C <BACK .A 2>>
+ [2 3 4]
+ <SET D <TOP .A>>
+ [1 2 3 4]
+ <SET E <REST .D>>
+ [2 3 4]
+ <SET F <REST "XYZ">>
+YZ
+
+The relationships between REST, BACK, and TOP are illustrated.
+Note that only REST can work on lists
+\f
+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 "MUDDLE;NCOMP">
+Restore the compiler.
+\f
+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 <RESUMER> if there is one.
+Returns -- Whatever is passed to RESUME later in another PROCESS to
+ RESUME this one.
+
+Example: <COND (<RESUMER> <RESUME T <RESUMER>>)>
+Resumer our RESUMER, if we have one.
+\f
+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 <ME>. If no
+process has ever RESUMEd the process given, returns FALSE.
+
+Argument:
+
+ Template: #DECL ("VALUE" <OR FALSE PROCESS> "OPTIONAL" PROCESS)
+
+(Optional)
+Argument 1 -- A PROCESS, default <ME>.
+Returns -- A PROCESS, which last RESUMEd Arg 1, or FALSE if none ever
+ did.
+
+Example: <PROG ((R <RESUMER>))
+ <COND (<AND .R <==? <STATE .R> RESUMABLE>>
+ <RESUME T .R>)>>
+RESUME RESUMER if o.k. to do so.
+\f
+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: <RETRY <FRM 1>>
+Often you want to restart from just before the error.
+\f
+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: <REPEAT (X)
+ <COND (<EMPTY? .X> <RETURN "DONE">)
+ (ELSE <PRINT <1 .X>>)>
+ <SET X <REST .X>>>
+Simple use of RETURN in a REPEAT.
+\f
+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" <OR FALSE ANY>)
+
+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: <AND <GASSIGNED? FOO> <RGLOC FOO>>
+Guard against ATOMs with no GVALs.
+\f
+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: <ROOT>
+Only one there is.
+\f
+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
+ <PRIMTYPE 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: <ROT 8 6>
+ #WORD *000000001000*
+ <ROT 8 -6>
+ #WORD *100000000000*
+Primarily useful for getting fingers directly in the bits.
+\f
+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
+ <VECTOR <OR RSUBR ATOM> 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: <RSUBR-ENTRY [,FOO FOO1 #DECL ("VALUE" LIST STRING)]
+ 245>
+
+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.
+\f
+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" <OR ANY FALSE>
+ "OPTIONAL" <OR ANY FALSE>)
+
+(Optional)
+Argument 1 -- FALSE disables automatic RSUBR linking, non-FALSE
+ enables it.
+Returns -- The previous state, or the current state if no arg
+
+Example: <RSUBR-LINK <>>
+ <GROUP-LOAD "FOO BINARY">
+.....debugging.....
+ <RSUBR-LINK T>
+Done debugging.
+\f
+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
+ <VECTOR <OR CODE PCODE> 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: <RSUBR [#CODE ![1!] FOO #DECL ()]>
+Will create a useless RSUBR
+\f
+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: <RUNINT <3 .HANDLER> !.ARGS>
+Of course only the interpreter does this.
+\f
+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" <OR FIX FLOAT> <OR FIX FLOAT>)
+
+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: <RUNTIMER <* 60 60>>
+Cause interrupt after one hour time (seconds) used.
+\f
+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 <READ> 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: <SAVE>
+Will save core image to DSK:<sname>;MUDDLE SAVE.
+\f
+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
+ <OR STRING <UVECTOR [REST <PRIMTYPE WORD>]> 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: <SEND-WAIT "CLR" "MUDDLE" "HOW ARE YOU CHRIS?">
+Will return T when CLR MUDDLE takes the IPC message.
+\f
+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" <OR 'T '#FALSE ()> STRING STRING
+ <OR STRING <UVECTOR [REST <PRIMTYPE WORD>]> 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: <SEND "CLR" "MUDDLE" "HOW ARE YOU CHRIS?">
+Will return T only if CLR MUDDLE is listening for IPC messages.
+\f
+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" <OR ENVIRONMENT
+ ACTIVATION
+ FRAME
+ PROCESS>)
+
+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: <SET REDEFINE T>
+allows redefinitions
+\f
+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: <SETG REAL-PLUS ,+>
+often the first step in redefining primitives
+\f
+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: <SET FOO (1 2 3)>
+ <SET FOOL <AT .FOO 2>>
+ <IN .FOOL>
+ 2
+ <SETLOC .FOOL "BAR">
+ .FOO
+ (1 "BAR" 3)
+Just like PUT, right?
+\f
+SIN: Sine of an angle
+
+Object-type: SUBR
+
+Category: ARITHMETIC
+
+Reference: COS, ATAN
+
+
+Argument:
+
+ Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
+
+Argument 1 -- the angle in radians.
+Returns -- A FLOAT, the Sine.
+
+Example: <+ <* <COS .X> <COS .X>>
+ <* <SIN .X> <SIN .X>>>
+ 1.0
+One of the common trig. identities.
+\f
+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 <OR FIX FLOAT> "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 60 .TYPEIN>
+
+Sleep for a minute but stop early if an interrupt handler sets the
+ATOM to a non-FALSE.
+\f
+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: <SNAME "FOO">
+FOO
+ <SNAME>
+FOO
+Set and read SNAME.
+\f
+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.
+
+ <SORT function ; either FALSE or something applicable
+ ; to two sort keys which returns FALSE
+ ; if the first is not bigger than the
+ ; second. I.e, arg1 > 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" <PRIMTYPE <OR VECTOR UVECTOR TUPLE>>
+ <OR FALSE APPLICABLE> <PRIMTYPE <OR VECTOR UVECTOR TUPLE>>
+ "OPTIONAL" FIX FIX "TUPLE"
+ <TUPLE [REST
+ <PRIMTYPE <OR VECTOR UVECTOR 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: <SET A <IUVECTOR 500 '<RANDOM>>>
+ <SORT <> .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.
+ <SORT <>
+ [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.
+ <SORT <FUNCTION (X Y)
+ <G? <1 .X> <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.
+\f
+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" <OR 'T FALSE>
+ "OPTIONAL" <OR ANY FALSE>)
+
+(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: <SPECIAL-CHECK <>>
+This sets the normal initial state -- no special checking.
+\f
+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" <OR 'SPECIAL 'UNSPECIAL>
+ "OPTIONAL" <OR 'SPECIAL 'UNSPECIAL>)
+
+(Optional arguments)
+Argument 1 -- SPECIAL or UNSPECIAL, the new mode.
+Returns -- The mode at the time of the call.
+
+Example: <SPECIAL-MODE UNSPECIAL>
+Set the initial state.
+\f
+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: <SPNAME \ \ \ !-FOO!-BAR>
+
+Just three spaces, no backslashes, no trailers.
+\f
+SQRT: Square root of a number
+
+Object-type: SUBR
+
+Category: ARITHMETIC
+
+Reference: LOG, EXP
+
+
+Argument:
+
+ Template: #DECL ("VALUE" FLOAT <OR FIX FLOAT>)
+
+Argument 1 -- A FIX or FLOAT.
+Returns -- FLOAT, the square root of argument 1.
+
+Example: <SQRT 4>
+ 2.0
+Floating is always done.
+\f
+SQUOTA: Get the address of an internal interpreter symbol (for internal use only)
+"VALUE" <OR FIX FALSE>
+<PRIMTYPE WORD>
+\f
+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" <LIST APPLICABLE ANY ANY>)
+
+Arguments -- see Description.
+Returns -- see Description.
+
+Example: <STACKFORM ,STRING
+ <READCHR>
+ <NOT <==? <NEXTCHR> <ASCII 27>>>>
+
+This reads characters from the current input channel until an alt-mode
+is read. It then returns what was read as one String.
+\f
+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: <STATE <ME>>
+ RUNNING
+This should always be the case.
+\f
+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: <PROG ()
+ <SET A <STORE ![1 2 3!]>>
+ (.A <1 .A> <FREE .A>)>
+Notice that once the space is free'd it should not be accessed
+\f
+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 <OR ATOM STRING> <OR ATOM STRING>)
+
+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: <STRCOMP "FOO" "BAR">
+ 1
+ <G? <STRCOMP "FOO" "BAR"> 0>
+ T
+Converts STRCOMP into a predicate suitable for SORT.
+\f
+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 [REST <OR STRING CHARACTER>]>)
+
+Tuple of arguments -- STRINGs or CHARACTERs, the elements of the new
+ STRING.
+Returns -- Newly created STRING.
+
+Example: <STRING "This is " !\a " string">
+This is a string
+\f
+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" <OR FALSE 'T> ANY)
+
+Argument 1 -- Any MUDDLE object.
+Returns -- T if argument 1 is structured, or FALSE if it is not.
+
+Example: <STRUCTURED? <ROOT>>
+ T
+Lots of types are structured.
+\f
+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 <SUBSTITUTE 2 1>) 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: <SUBSTITUTE FOO!-BAR FOO>
+
+Only reasonable use so far found. ATOM impurification is done this
+way, more or less.
+\f
+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" <OR LIST VECTOR UVECTOR STRING BYTES>
+ <OR <PRIMTYPE LIST>
+ <PRIMTYPE VECTOR>
+ <PRIMTYPE TUPLE>
+ <PRIMTYPE UVECTOR>
+ <PRIMTYPE STRING>
+ <PRIMTYPE BYTES>>
+ "OPTIONAL" FIX FIX
+ <OR LIST VECTOR UVECTOR STRING BYTES>)
+
+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 <PRIMTYPE arg1> (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: <SUBSTRUC '(1 2 3) 0 2>
+ (1 2)
+opposite of REST
+ <SUBSTRUC "SUM OF PARTS" 7 4 <ISTRING 4>>
+ "PART"
+substring function
+\f
+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 <MAIN> 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 <RESUMER>, if there is one.
+Returns -- Nothing really, as the PROCESS SUICIDEd cannot be RESUMEd,
+ since it will be dead.
+
+Example: <SUICIDE T>
+Won't work if <ME> is <MAIN>
+\f
+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: <PROG (&)
+ &
+ LABEL
+ <FOO>
+ &
+ <LOWER .BAR <TAG LABEL>>
+ &>
+See how easy it is to make confusing programs?
+\f
+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: <TERPRI>
+ #FALSE ()
+Terminate printing on this line.
+\f
+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" <TUPLE [REST ANY]>)
+
+(Optional)
+Tuple of arguments -- ANY objects.
+Returns -- FLOAT, the run time of the MUDDLE in seconds.
+
+Example: <TIME>
+ 69.104992
+Run time.
+\f
+TOP: Replace elements of a structure removed by REST
+
+Object-type: SUBR
+
+Category: DATA-HANDLING
+
+Reference: BACK, REST
+
+ TOP replaces all items removed from a non-list structure by
+RESTing. For PRIMTYPE VECTORs, UVECTORs, STRINGs, and TEMPLATEs, TOP
+returns the object passed after having returned the pointer to the top
+of the object and changed the type to the PRIMTYPE. Since list
+structures have no back pointers, it is impossible to either BACK them
+or TOP them.
+
+Argument:
+
+ Template: #DECL ("VALUE" <OR VECTOR UVECTOR STRING TEMPLATE>
+ <PRIMTYPE <OR VECTOR UVECTOR STRING TEMPLATE>>)
+
+Argument 1 -- A structured object that can be BACKed (VECTOR, UVECTOR,
+ STRING, or TEMPLATE.
+Returns -- The object with the RESTed elements (if any) returned and
+ changed to its PRIMTYPE.
+
+Example: <==? <TOP <REST <SET X "FOOBARBLECH"> 6>>
+ .X>
+
+This will return T, as the same object is always there, just with a
+different pointer into it.
+\f
+TTYECHO: Turn TTY echoing for a CHANNEL on and off
+
+Object-type: SUBR
+
+Category: I/O
+
+Reference: TYI
+
+ TTYECHO takes a channel and a FALSE or non-FALSE, ands sets
+the TTY echoing for that channel to 'off' if FALSE, 'on' if non-FALSE.
+ This is useful in conjunction with the SUBR TYI (qv) for applic-
+ations where TTY echoing is not straight character at a time.
+ ERROR and LISTEN automatically do <TTYECHO .INCHAN T> when they
+are called.
+
+Argument:
+
+ Template: #DECL ("VALUE" CHANNEL CHANNEL <OR ANY FALSE>)
+
+Argument 1 -- A TTY CHANNEL.
+Argument 2 -- non-FALSE to turn on echoing, FALSE to turn it off.
+Returns -- The channel.
+
+Example: <TTYECHO .INCHAN T>
+ERROR and LISTEN do this automatically.
+\f
+TUPLE: Create a TUPLE with explicit elements
+
+Object-type: SUBR
+
+Category: DATA-HANDLING
+
+Reference: ITUPLE
+
+ TUPLE creates a tuple (vector on the stack) with explicit
+elements. TUPLE can only be invoked at top level of an atom-value
+pair in a parameter list, such as AUX or OPTIONALs, or the top binding
+pairs of PROG or REPEAT.
+ Note that a TUPLE cannot be returned past the FRAME in which it
+was bound.
+
+Argument:
+
+ Template: #DECL ("VALUE" TUPLE "TUPLE" TUPLE)
+
+Tuple of arguments -- ANY, the elements of the TUPLE.
+Returns -- Newly stacked TUPLE.
+
+Example: <PROG ((X <TUPLE 1 2 3 4>)) <+ !.X>>
+This is a legitimate, if trivial, use of TUPLE.
+ <PROG ((X <REST <TUPLE 1 2 3 4>>))
+ <+ !.X>>
+
+This use of TUPLE is both trivial and illegal: it is not at top level
+of the atom-value pair.
+\f
+TYI: Read a single character as it is typed on the TTY
+
+Object-type: SUBR
+
+Category: I/O
+
+Reference: TTYECHO
+
+ TYI is used to read characters from the TTY as they are typed
+rather than after an alt-mode is typed, as is the case with READCHR
+and READ. It may be used in conjunction with TTYECHO by programs
+that wish to do their own reading and echoing.
+
+Argument:
+
+ Template: #DECL ("VALUE" CHARACTER "OPTIONAL" CHANNEL)
+
+Argument 1 -- A TTY channel on which to read a character, default .INCHAN.
+Returns -- The character read.
+
+Example: <TTYECHO .INCHAN <>>
+ <REPEAT ()
+ <PRINC <CHTYPE <+ 32 <CHTYPE <TYI .INCHAN> FIX>> CHARACTER>
+ .INCHAN>>
+Turn echoing off and echo characters read as their value plus 40.
+\f
+TYPE-C: Get a type code for pure-program use
+
+Object-type: SUBR
+
+Category: TYPE-DEFINITION
+
+Reference: NEWTYPE, TYPE-W
+
+
+Argument:
+
+ Template: #DECL ("VALUE" TYPE-C ATOM "OPTIONAL" ATOM)
+
+Argument 1 -- the newtype to get a code for
+(Optional)
+Argument 2 -- its primtype, as a check
+Returns -- a type code
+
+Example: <TYPE-C MYLIST LIST>
+makes or gets a type code for my newtype
+\f
+TYPE-W: Get a type word for pure RSUBR use
+
+Object-type: SUBR
+
+Category: TYPE-DEFINITION
+
+Reference: NEWTYPE, TYPE-C
+
+
+Argument:
+
+ Template: #DECL ("VALUE" TYPE-W ATOM "OPTIONAL"
+ ATOM <PRIMTYPE WORD>)
+
+Argument 1 -- name of newtype
+(Optional)
+Argument 2 -- primtype thereof, as a check
+Argument 3 -- right half to include in result
+Returns -- a type word
+
+Example: <TYPE-W MYLIST LIST 69>
+a type word for NEWTYPE MYLIST
+\f
+TYPE: Return the type of an object
+
+Object-type: SUBR
+
+Category: TYPE
+
+Reference: UTYPE, TYPE?, PRIMTYPE, TYPEPRIM
+
+ TYPE is applied to any MUDDLE object to return an ATOM which is
+the name of the type of that object. PRIMTYPE, which is similar,
+returns the primitive 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 type of the argument.
+
+Example: <TYPE TYPE>
+ ATOM
+ <TYPE "Comments on example">
+ STRING
+
+TYPE?, which checks to see if its argument is one of a series of
+types, is often used instead of TYPE in conditionals.
+\f
+TYPE?: Is an object one of a group of types?
+
+Object-type: SUBR
+
+Category: PREDICATE, TYPE
+
+Reference: TYPE
+
+ TYPE? takes as arguments an object and at least one type name.
+If the object is one of the types given, that type is returned. If it
+is not, returns FALSE. TYPE? is essentially the same as MEMQing the
+TYPE of the object in a list of types, but is syntactically clearer
+and better understood by the compiler.
+
+Argument:
+
+ Template: #DECL ("VALUE" <OR FALSE ATOM> ANY "TUPLE"
+ <TUPLE ATOM [REST ATOM]>)
+
+Argument 1 -- Any MUDDLE object.
+Tuple of arguments -- Any number (at least one, though) type names.
+Returns -- The type if it is in the tuple, or FALSE if it is not.
+
+Example: <TYPE? 1 FIX FLOAT WORD>
+ FIX
+Will take any number of type names.
+\f
+TYPEPRIM: Return the primitive type of a type
+
+Object-type: SUBR
+
+Category: TYPE
+
+Reference: UTYPE, TYPE?, PRIMTYPE, TYPE
+
+ TYPEPRIM returns the primitive type given the name of the type
+of a MUDDLE object. It is thus different from PRIMTYPE, which takes
+the object itself.
+
+Argument:
+
+ Template: #DECL ("VALUE" ATOM ATOM)
+
+Argument 1 -- An ATOM which is the name of a type.
+Returns -- ATOM, the name of the primitive type of the argument.
+
+Example: <TYPE 1>
+ FIX
+ <PRIMTYPE 1>
+ WORD
+ <TYPEPRIM FIX>
+ WORD
+Illustrates difference between PRIMTYPE and TYPEPRIM.
+\f
+UNAME: Return the User-name of the MUDDLE
+
+Object-type: SUBR
+
+Category: SYSTEM
+
+ Returns the UNAME, or login-name of the MUDDLE. This is the
+name under which the person running the MUDDLE logged in. It is also
+one of the names of the MUDDLE job.
+
+Argument:
+
+ Template: #DECL ("VALUE" STRING)
+
+Returns -- A STRING giving the UNAME of the job.
+
+Example: <UNAME>
+Only possible example.
+\f
+UNASSIGN: Removes the local value of an ATOM
+
+Object-type: SUBR
+
+Category: IDENTIFIER
+
+Reference: LVAL, ASSIGNED?
+
+ UNASSIGN removes the local value of an ATOM. After an ATOM
+has been UNASSIGNED, LVAL of it will cause an error, and ASSIGNED?
+of it will return FALSE.
+
+Argument:
+
+ Template: #DECL ("VALUE" ATOM ATOM "OPTIONAL"
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+Argument 1 -- The ATOM to flush the LVAL of.
+(Optional)
+Argument 2 -- the environment of the LVAL
+Returns -- The ATOM you just UNASSIGNed.
+
+Example: <UNASSIGN SNM>
+ SNM
+if it's giving you trouble
+\f
+UNMANIFEST: Declare the global value of an ATOM to no longer be a constant
+
+Object-type: SUBR
+
+Category: DATA-HANDLING
+
+Reference: MANIFEST, MANIFEST?, GDECL
+
+ UNMANIFEST declares that the current global value of an ATOM is
+no longer a constant. Generally a ATOM passed to UNMANIFEST will have
+previously been passed to MANIFEST.
+ UNMANIFEST is generally used to remove the restriction on changing
+an MANIFEST variable so that it CAN be changed.
+
+Argument:
+
+ Template: #DECL ("VALUE" 'T "TUPLE" <TUPLE [REST ATOM]>)
+
+Tuple of arguments -- ATOMs whose GVALs are no longer constants.
+Returns -- T.
+
+Example: <SETG A 1>
+ <SETG B 2>
+ <MANIFEST A B>
+...
+ <UNMANIFEST A>
+ <SETG A 4>
+Most common use of UNMANIFEST.
+\f
+UNPARSE: Recreate the STRING representation of a MUDDLE object
+
+Object-type: SUBR
+
+Category: DATA-HANDLING
+
+Reference: PARSE, LPARSE
+
+ UNPARSE create a string representation of a MUDDLE object, just
+like printing into a string instead of a channel.
+
+Argument:
+
+ Template: #DECL ("VALUE" STRING ANY "OPTIONAL" FIX)
+
+Argument 1 -- ANY, object to be 'printed' into a string.
+(Optional)
+Argument 2 -- radix for FIX conversion, default ten
+Returns -- A STRING, the unparsed object.
+
+Example: <PARSE <UNPARSE (1 2 3 4)>>
+This is one way of creating a non-shared copy of a structure.
+
+Object-type: FSUBR
+
+Category: PROGRAM-CONTROL
+
+ UNWIND is an FSUBR that takes two forms. It EVALs the first
+one, and, if the EVAL returns normally, the value of that EVAL is the
+value of UNWIND. If, however, during the EVAL a non-local return
+attempts to return beyond the UNWIND in the stack, then the second
+form is EVALed, its value is ignored, and the non-local return is
+completed. The second form is evaluated in the environment that was
+present when the call to UNWIND was made.
+ This facility is useful for cleaning up data bases that are in
+inconsistent states and closing temporary channels that may be left
+around. FLOAD sets up an UNWIND to close its CHANNEL if the user
+attempts to ERRET without finishing the FLOAD.
+
+Argument:
+
+ Template: #DECL ("VALUE" ANY "ARGS" <LIST ANY ANY>)
+
+Argument 1 -- A form to be EVALed.
+Argument 2 -- A form to EVAL if a non-local return beyond the UNWIND
+ happens.
+Returns -- The result of EVALing argument 1 (only local return that
+ can happen).
+
+Example: <DEFINE FOO ACT ("AUX" (C
+ <OPEN "READ"
+ "FOOBAR">))
+ <UNWIND <PROG () "...&..."> <CLOSE .C>>>
+
+Channel C will be closed if the PROG returns non-locally, as from
+ACT, for example.
+\f
+UTYPE: Return the Uniform type of a UVECTOR
+
+Object-type: SUBR
+
+Category: TYPE
+
+Reference: UVECTOR, CHUTYPE
+
+ UTYPE returns the name of the uniform type of a UVECTOR. This
+is the type of all objects in the UVECTOR. It may be changed by using
+CHUTYPE (within limits).
+
+Argument:
+
+ Template: #DECL ("VALUE" ATOM <PRIMTYPE UVECTOR>)
+
+Argument 1 -- A UVECTOR
+Returns -- An ATOM, which is the name of the UVECTOR's uniform type.
+
+Example: <UTYPE ![1 2 3 4!]>
+ FIX
+Allows you to get the utype without accessing any individual element.
+\f
+UVECTOR: Create a UVECTOR with explicit elements
+
+Object-type: SUBR
+
+Category: DATA-HANDLING
+
+Reference: IUVECTOR
+
+ UVECTOR creates a uvector with explicit elements. Note that all
+of these elements must be of the same type, else ERROR. UVECTOR is
+different from an explicit usage of excl-[, because in such usage all
+the elements must be the same when read in -- they are already a
+UVECTOR before evaluation.
+
+Argument:
+
+ Template: #DECL ("VALUE" UVECTOR "TUPLE" <TUPLE [REST ANY]>)
+
+Tuple of arguments -- ANY, the elements must all be of same type, and
+ can't be strings, LOCDs, or on the stack.
+Returns -- A new UVECTOR.
+
+Example: <UVECTOR 1 2 3>
+Equivalent to ![1 2 3]
+ <UVECTOR 1 .FOO .BAR>
+Not equivalent to ![1 .FOO .BAR!], which is illegal
+\f
+VALID-TYPE?: Is an ATOM the name of a type?
+
+Object-type: SUBR
+
+Category: TYPE-DEFINITION, PREDICATE
+
+Reference: NEWTYPE
+
+VALID-TYPE? returns #FALSE () if its argument is not the name of a
+TYPE, and TYPE-C of its argument if it is. It is much more efficient
+than <MEMQ .arg <ALLTYPES>> .
+
+Argument:
+
+ Template: #DECL ("VALUE" <OR TYPE-C FALSE> ATOM)
+
+Argument 1 -- an ATOM that might be the name of a TYPE
+Returns -- whether or not it really is
+
+Example: <VALID-TYPE? FOO>
+ #FALSE ()
+ <NEWTYPE FOO CHARACTER>
+ FOO
+ <VALID-TYPE? FOO>
+now returns %<TYPE-C FOO CHARACTER>
+\f
+VALRET: Returns a string to MUDDLE's superior
+
+Object-type: SUBR
+
+Category: ENVIRONMENT
+
+Reference: LOGOUT, QUIT
+
+ VALRET returns a string to the MUDDLE's superior. This is
+usually only useful if the superior is a MONIT or DDT (which are the
+two normal superiors on ITS). VALRET's can be used to execute
+commands in DDT and then return to MUDDLE, but because they are
+limited to use on ITS, it is untasteful to use VALRET where other
+means would suffice.
+
+Argument:
+
+ Template: #DECL ("VALUE" ANY STRING)
+
+Argument 1 -- A STRING to return to MUDDLE's superior.
+Returns -- ANY.
+
+Example: <VALRET "\17..SENDRP/-1
+70/\e2Q
+:VP
+">
+
+This example is a VALRET string that will cause DDT to stop printout
+of unsolicited messages.
+\f
+VALUE: Return the local or else the global value of an atom
+
+Object-type: SUBR
+
+Category: IDENTIFIER
+
+Reference: LVAL, GVAL
+
+ If its argument has a local value (in a given environment),
+VALUE returns the value; else, if it has a global value, returns that;
+else error.
+
+Argument:
+
+ Template: #DECL ("VALUE" ANY ATOM "OPTIONAL"
+ <OR ENVIRONMENT ACTIVATION FRAME PROCESS>)
+
+Argument 1 -- the atom whose value to get
+(Optional)
+Argument 2 -- the environment to look for a local value in
+Returns -- local or else global value
+
+Example: <VALUE SNM>
+default disk directory for I/O
+\f
+VECTOR: Create a VECTOR with explicit elements
+
+Object-type: SUBR
+
+Category: DATA-HANDLING
+
+Reference: IVECTOR
+
+ VECTOR creates a vector with explicit elements. It is the
+same as enclosing the arguments to VECTOR in [ and ].
+
+Argument:
+
+ Template: #DECL ("VALUE" VECTOR "TUPLE" <TUPLE [REST ANY]>)
+
+Tuple of arguments -- ANY, the elements
+Returns -- A new VECTOR.
+
+Example: <VECTOR 1 2 3>
+equivalent to [1 2 3]
+\f
+XORB: Bitwise logical Exclusive OR
+
+Object-type: SUBR
+
+Category: ARITHMETIC
+
+Reference: EQVB, ORB, ANDB
+
+ XORB takes any number of objects of Primtype WORD, and returns
+a WORD containing the bitwise logical exclusive OR of the arguments.
+
+Argument:
+
+ Template: #DECL ("VALUE" WORD
+ "TUPLE" <TUPLE [REST <PRIMTYPE WORD>]>)
+
+Tuple of arguments -- Objects of primtype WORD to be XORed together.
+Returns -- A WORD containing the bitwise XOR of the arguments.
+
+Example: <XORB #WORD *000000000001*
+ #WORD *000000000001*
+ #WORD *000000042263*>
+ #WORD *000000042263*
+Primarily useful for getting fingers directly in the bits.
+\f
\ No newline at end of file
projects / pdp10-muddle.git / commitdiff