github.com/PDP-10.its
1
0
Fork 0
mirror of https://github.com/PDP-10/its.git synced 2026-01-13 15:27:28 +00:00
Code Issues Releases Wiki Activity
PDP-10.its/doc/mudman/muddle.order
Lars Brinkhoff 61b0dd1dfa Various ITS documentation files.
2018-05-15 19:36:36 +02:00

7907 lines
215 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

MUDDLE F/SUBRS: (for MUDDLE 55) PDL/SWG 3/8/79
The following is a very brief description of all the
primitives currently available in MDL. These descriptions are in
no way to be considered a definition of the effects or values
produced by the primitives. They just try to be as complete and
as accurate as is possible in a single-statement description.
However, because of the complexity of most primitives, many
important defaults and restrictions have been omitted.
*: Multiplication of fixes and floats.
Object-type: SUBR
Category: ARITHMETIC
* (Multiply) takes any number of FIXes or FLOATs, and multiplies
them together, returning the result. If any of the arguments are
FLOATs, the result will be FLOAT. If no argument is given, * returns
1, if one argument is given, * returns that argument.
* will given an arithmetic overflow error (unless disabled by OVERFLOW)
if the word size of the PDP-10 is exceeded.
Argument:
Template: #DECL ("VALUE" <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.
+: 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.
-: 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.
/: 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.
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?
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.
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.
==?: 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.
=?: 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.
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.
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
ACTIVATE-CHARS: Set or inspect interrupt characters for console typing (TENEX only)
"VALUE" STRING
"OPTIONAL" STRING
AGAIN: Restart a FUNCTION, PROG, or REPEAT
Object-type: SUBR
Category: PROGRAM-CONTROL
Reference: FUNCTION, PROG, REPEAT
AGAIN takes one argument: an ACTIVATION. It means 'start doing
this again', where 'this' is specified by the ACTIVATION. Specifically,
AGAIN causes EVAL to return to where it started working on the body of
the FUNCTION, REPEAT, or PROG in the application specified by the
ACTIVATION. The application is not re-evaluated completely: no
rebinding of variables is done.
In a PROG or REPEAT, where there is always a defined ACTIVATION,
AGAIN with no arguments defaults to AGAIN of the top-level ACTIVATION
in the PROG or REPEAT.
Argument:
Template: #DECL ("VALUE" ANY "OPTIONAL" ACTIVATION)
(Optional)
Argument 1 -- The ACTIVATION to restart. If not given, that of the
immediately surrounding PROG or REPEAT is used.
Returns -- Nothing, restarts the ACTIVATION.
Example: <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.
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.
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.
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?
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.
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.
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.
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
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.
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*.
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
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.
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
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
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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
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}]
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
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.
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
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.
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.
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.
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).
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))
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.
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.
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.
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
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
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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?
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.
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.
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.
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.
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.
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
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.
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
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
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.
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
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.
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.
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.
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
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.
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>)
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 ().
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 ().
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.
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
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
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
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
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
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.
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.
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
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.
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
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
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
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.
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
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.
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.
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!
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.
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.
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}
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 ().
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 ().
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.
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.
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.
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> "">
Links the ATOM of PNAME ^E to <ERRET>.
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.
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
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.
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
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.
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.
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.
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".
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.
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.
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
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?
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.
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.
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
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
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.
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.
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.
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.
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?
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 ==?.
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.
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
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
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.
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.
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.
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.
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.
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?
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.
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."]
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.
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>
!\
what you get if called by itself
NOT: Change the truth value of an object to its complement
Object-type: SUBR
Category: LOGICAL, CONDITIONAL
Reference: AND, OR, COND
NOT complements the truth value of its argument. If its
argument was a FALSE, NOT returns T, if its argument was non-FALSE,
NOT returns a FALSE.
Argument:
Template: #DECL ("VALUE" <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.
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.
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.
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.
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>>
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>
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
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.
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.
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?
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.
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
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>.
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.
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.
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
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.
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
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!
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
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.
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.
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.
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.
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.
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
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>>
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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>
!\
If called alone, you get the ESC.
READSTRING: Read into a string from an I/O channel
Object-type: SUBR
Category: I/O
Reference: READB
READSTRING is the string analog to READB (q.v.). It fills a string
buffer with characters from a channel, returning the number of characters
input. One argument tells when to stop reading: after a certain number
of characters or upon reading one of a set of characters.
Argument:
Template: #DECL ("VALUE" FIX STRING "OPTIONAL" CHANNEL <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.
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.
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.
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.
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
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.
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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
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
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?
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.
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.
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.
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.
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.
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.
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.
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.
SQUOTA: Get the address of an internal interpreter symbol (for internal use only)
"VALUE" <OR FIX FALSE>
<PRIMTYPE WORD>
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.
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.
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
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.
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
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.
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.
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
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>
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?
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.
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.
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.
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.
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.
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.
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
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
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.
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.
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.
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.
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
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.
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.
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.
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
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>
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 "..SENDRP/-1
70/2Q
:VP
">
This example is a VALRET string that will cause DDT to stop printout
of unsolicited messages.
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
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]
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.
Reference in New Issue View Git Blame Copy Permalink