Subject: prims.doc &&& man The following topics are currently indexed: TOPIC description ----- ----------- flow flow control primitives operands mathematical and other logic logical tests testing things stack stack operations string string property property-related conversions data conversion db db operations interaction player interaction operations stamp timestamp operations daytime time operations descriptor descriptor operations system system parameters Type `man TOPIC' to get specific information, or `man op' to get information on `op'. Primitives with "[wizard]" after them are wizard-only; they work only for programs set WIZARD and owned by wizards. The descriptions use the term "wizard program" to refer to such programs. The term "effective player" refers to the player running the program, unless the program is set S(etUID), in which case it means the program's owner. A program is said to be "able to build" if it is a wizard program, if the effective player is a builder, or if the program's B bit is set. &&& MARKER - end of main man and beginning of topic pages &&& flow Flow control: : word begins definition of the word ; ends a definition begun with : var word declares word as a variable if ( i -- ) begins a conditional construct else separates then-part from else-part eif marks an else-if construct then ends an if construct exit ( -- ) returns from the word it appears in to whatever called that word call ( d -- ? ) call another program sleep ( i -- ) sleep for i seconds sleep ( d -- ) sleep until a wakeup is done on the dbref wakeup ( d -- ) wake up anyone sleeping on the dbref kill ( d -- ) kills a daemon nop ( -- ) does nothing begin ( -- ) marks the begining of a while loop while ( i -- ) execute the body of the while loop, if i is nonzero do ( -- ) marks the beginning of DO .. LOOP for ( i1 i2 i3 -- i1 ) initiates a FOR .. LOOP i1 is the begin, i2 is the end, and i3 is the stepsize. Each run through the loop will place the new value of the counter on the stack. loop ( -- ) terminates a begin/while, do, or for loop. break ( -- ) terminates a begin/while, do, or for loop prematurely, that is, before it normally would. This affects the smallest enclosing such loop. continue ( -- ) branches to the end of a loop, just before the closing "loop". fork ( -- i ) forks a new daemon; in the original daemon or player, the pushed value is the number of the new daemon; in the new daemon, it's 0. ' word ( -- ptr ) Pushes a pointer to the word on the stack. The word must have already been defined. The resulting pointer is good for nothing except passing to the exec primitive. exec ( ptr -- ) Pops a pointer to a word and executes the word. 'word ( -- addr ) Pushes address of a word. execute ( addr -- ) Executes a word, given its address. yield ( -- ) Lets others execute. An iteration counter has been added to the server. See `man system'. &&& operands Operands: + ( i i -- i ) add - ( i i -- i ) subtract * ( i i -- i ) multiply / ( i i -- i ) divide % ( i i -- i ) remainder/modulus | ( i i -- i ) bitwise or & ( i i -- i ) bitwise and << ( i i -- i ) bit shift left >> ( i i -- i ) bit shift right ~ ( i -- i ) bitwise not < ( i i -- i ) less than > ( i i -- i ) greater than = ( i i -- i ) equals <= ( i i -- i ) less than or equals >= ( i i -- i ) greater than or equals dbcmp ( d d -- i ) compare two dbrefs, 1 = same random ( -- i ) a random # from 0 to MAXINT @ ( v -- x ) fetch value of a variable ! ( x v -- ) set value of a variable ++ ( v -- ) increment value of a variable -- ( v -- ) decrement value of a variable &&& logic Logical operators: and ( x x -- i ) logical and or ( x x -- i ) logical or not ( x -- i ) logical not The empty string, the integer 0, and #-1 are false; anything else is true. &&& tests Tests: address? ( x -- i ) is arg an address object? ptr? ( x -- i ) is arg a pointer object? awake? ( x -- i ) is arg a connected player? builder? ( d -- i ) is the dbref a builder? daemon? ( x -- i ) is arg a daemon dbref? dbref? ( x -- i ) is arg a dbref? exit? ( x -- i ) is arg an exit dbref? flag? ( d s -- i ) is the named flag set on the dbref? getflags ( d -- i ) get flags word as integer god? ( d -- i ) is the dbref god? int? ( x -- i ) is arg an integer? locked? ( d -- i ) is the dbref locked? mucker? ( d -- i ) is the dbref a mucker? number? ( x -- i ) is arg a string that contains a number? ok? ( x -- i ) is arg a valid dbref? passlock? ( d1 d2 -- i ) does d1 pass the lock on d2? player? ( x -- i ) is arg a player dbref? program? ( x -- i ) is arg a program dbref? prop-exists? ( d s -- i ) does the property exist on the dbref? room? ( x -- i ) is arg a room dbref, or #-3? set ( d s -- ) set/clear the named flag on the dbref string? ( x -- i ) is arg a string? thing? ( x -- i ) is arg a thing dbref? var? ( x -- i ) is arg a variable? wizard? ( d -- i ) is the dbref wizard? &&& stack Stack manipulation: depth ( -- i ) returns number of entries on the stack dup ( x -- x x ) duplicates top element over ( x1 x2 -- x1 x2 x1 ) copies next-to-top element pick ( x1 ... xN N -- x1 ... xN x1 ) copies Nth element down from stack (thus, dup = 1 pick, over = 2 pick) pop ( x -- ) pops top element off stack put ( x1 ... xN y N -- y x2 ... xN ) replaces Nth element down on stack roll ( xN ... x1 N M -- xM ... x1 xN ... xM-1 ) rotates top N elements M places rot ( x1 x2 x3 -- x2 x3 x1 ) rotates top three elements (3 -1 roll) rotate ( x1 x2 ... xN N -- x2 ... xN x1 ) ( x1 ... xN-1 xN -N -- xN x1 ... xN-1 ) rotates top N elements (N -1 roll or N 1 roll) swap ( x1 x2 -- x2 x1 ) swaps top two elements pstack ( i -- ) debugging aid - prints part or all of stack &&& string String operations: caps ( s -- s' ) uppercases first char, lowercases rest explode ( sA sB -- s1 ... sN N ) explodes sA, with sB as delimiter instr ( s1 s2 -- i ) finds first s2 in s1 pronoun_sub ( d s -- s' ) performs % substitution rinstr ( s1 s2 -- i ) finds last s2 in s1 strcat ( s1 s2 -- s ) concatenates two strings strcmp ( s1 s2 -- i ) compares two strings strcut ( s i -- s1 s2 ) cut a string in two stringcmp ( s1 s2 -- i ) comapres two strings, ignoring case strlen ( s -- i ) finds length of string strncmp ( s1 s2 n -- i ) compares prefixes of two strings subst ( s s1 s2 -- s' ) substitutes s1 for s2 in s tolower ( s -- s' ) maps string to lower case toupper ( s -- s' ) maps string to upper case &&& property Dbref property and message manipulation: pennies ( d -- i ) gets money of dbref addpennies ( d i -- ) adds money to dbref name ( d -- s ) gets name of dbref desc ( d -- s ) gets description of dbref drop ( d -- s ) gets drop message of dbref fail ( d -- s ) gets fail message of dbref succ ( d -- s ) gets success message of dbref odrop ( d -- s ) gets odrop message of dbref ofail ( d -- s ) gets ofail message of dbref osucc ( d -- s ) gets osuccess message of dbref setname ( d s -- ) sets name of dbref setdesc ( d s -- ) sets description of dbref setdrop ( d s -- ) sets drop message of dbref setfail ( d s -- ) sets fail message of dbref setsucc ( d s -- ) sets success message of dbref setodrop ( d s -- ) sets odrop message of dbref setofail ( d s -- ) sets ofail message of dbref setosucc ( d s -- ) sets osuccess message of dbref addprop ( d sp sv n -- ) adds/changes property on dbref getpropstr ( d s -- s' ) gets property string value getpropval ( d s -- i ) gets property integer value propfirst ( d -- d s 1 / 0 ) gets first property name of dbref propnext ( d s -- d s 1 / 0 ) gets next property name of dbref remove_prop ( d s -- ) removes property from dbref addprop-if ( d sp sv -- s / 0 ) test-and-set property setting remprop-if ( d sp sv -- i) test-and-remove property &&& conversions Conversion functions: atoi ( s -- i ) convert string to int intostr ( i -- s ) convert int to string dbref ( i -- d ) convert int to dbref int ( d -- i ) convert dbref to int variable ( i -- v ) convert int to variable &&& db DB operations: db_top ( -- i ) integer = highest element in db + 1 dbtop ( -- d ) highest dbref in db moveto ( d d -- ) move object 1 to 2 contents ( d -- d ) returns first content of dbref exits ( d -- d ) returns first exit of dbref next ( d -- d ) find next of contents/exits/daemons match ( s -- d ) match string in current location rmatch ( d s -- d ) match string in remote location copyobj ( d -- d ) returns dbref of copy of thing location ( d -- d ) returns the location of a dbref owner ( d -- d ) returns owner of a dbref getlink ( d -- d ) returns link of a dbref dig ( s d -- d d ) create a room named 1 with parent 2 returns the room dbref as 1 and parent as 2 open ( s d -- d ) open an exit online ( -- d1 ... dN N ) returns a list of players chown ( d d -- ) changes ownership of 1 to 2 recycle ( d -- ) recycles an object create ( s i -- d ) creates a new object unlink ( d -- ) unlink an exit/object addlink ( d d -- ) links object 1 to object 2 linkcount ( d -- i ) find the number of links on an object getlinks ( d -- d1...dN N ) returns all the links on an object trig ( -- d ) returns the dbref of the trigger prog ( -- d ) returns the dbref of the current program caller ( -- d ) returns the player who ran the program callers ( -- d1...dN N ) returns a list of callers backlinks ( d -- d1...dN N ) returns a list of objects linked to obj backlocks ( d -- d1...dN N ) returns a list of objects locked to obj nextowned ( d -- d' ) returns the next in an owned list numowned ( d -- i ) returns count of owned dbrefs daemons ( -- d ) returns the first in a list of the daemons daemon ( -- d ) returns the dbref of the daemon, #0 if being run by a player. kill ( d -- ) kills a daemon unparse_flags ( d -- s ) returns verbose flags, eg "Player" flagstr ( d -- s ) returns short flags i.e. "PWAJ" unparse_lock ( d -- s ) returns lock as a human-readable string lockstr ( d -- s ) returns lock as string usable for lock lock ( d s -- ) sets the key on d unlock ( d -- ) unlocks a dbref force ( d s -- ) force player to execute command &&& interaction Player interaction: read ( -- s ) reads in a string notify ( d s -- ) notify one player notify_except ( d1 d2 s -- ) notify all but 2 in room 1 prompt ( s -- s' ) read with a prompt &&& stamp Timestamp operations: time_created ( d -- i ) get time dbref was created time_modified ( d -- i ) get time dbref was last modified time_used ( d -- i ) get time dbref was last used touch ( d -- ) sets the last-used time to now &&& daytime Time-of-day operations: ctime ( i -- s ) convert time value to a string date ( -- d m y ) get current date (day/month/year) time ( -- s m h ) get current time (second/minute/hour) systime ( -- i ) get current time in timestamp form gmtsplit ( i -- s m h md m y wd yd ) split a timestamp value in UTC timesplit ( i -- s m h md m y wd yd ) split a timestamp value in local timezone &&& this is for later, in case these come back gmtmerge ( s m h md m y wd yd -- i ) inverse of gmtsplit timemerge ( s m h md m y wd yd -- i ) inverse of timesplit &&& descriptor Descriptor stuff: concount ( -- i ) the number of connections to the MUCK, connections ( -- i1...iN N ) returns a list of descriptor #'s conidle ( i -- i ) returns the idle time in seconds contime ( i -- i ) returns the connection time in seconds conhost ( i -- s ) [wizard] returns the host connected from condbref ( i -- d ) returns the dbref of a connection, #-1 if not connected connotify ( i s -- ) [wizard] notifies a connection conboot ( i -- ) [wizard] disconnects a descriptor connected? ( i -- i ) is the descriptor connected? &&& system System values: ilimit ( -- i ) get current ilimit value setilimit ( i -- ) set ilimit &&& MARKER - end of topic pages and beginning of individual descriptions &&& ! ! ( x v -- ) Sets a variable. The value on top of the stack must be a variable; the value below can be any MUF object. The variable's value is set to the object. &&& % % ( i1 i2 -- i ) Returns i1 % i2, unless i2 is zero, in which case zero is returned. This uses the C % operator, so the same caveats apply: if both arguments are positive, the result is the mathematical modulus, but if either of the arguments is negative, the result may be negative. Its absolute value will be less than that of i2, and it will always be the case that, given two integers on the stack, with the top one non-zero, over over % 3 pick 3 pick / rot * + = will always return 1. (For those who know C, this corresponds to the C identity ((a/b)*b)+(a%b) == a, for b != 0.) &&& & & ( i1 i2 -- i ) Returns the bitwise AND of its operands. &&& ' ' word ( -- ptr ) ' generates a pointer that points to the word following the '. Aside from manipulations that work on any MUF types, such as stack operations, this pointer is good for nothing but passing to the exec primitive. Note that there is a similar syntax, which has no space between the ' and the following word, which generates a different type of pointer (called an address) that can be passed only to the execute primitive. These two types of pointers are incompatible; each may be used only with the corresponding primitive to call the word pointed to. Pointers work correctly when calling from one program to another; addresses don't, but are slightly faster to call. Note that this works only with words defined with :. It cannot be used with built-in primitives. &&& * * ( i1 i2 -- i ) Multiplies its arguments and returns the product. &&& + + ( i1 i2 -- i ) Adds its arguments and returns the sum. &&& ++ ++ ( v -- ) Increments the value of the variable; the value must be a number or dbref (or a run-time error occurs). &&& - - ( i1 i2 -- i ) Subtracts i2 from i1, returning the difference. &&& -- -- ( v -- ) Decrements the value of the variable; the value must be a number or dbref (or a run-time error occurs). &&& / / ( i1 i2 -- i ) Divides i1 by i2, returning the quotient, unless i2 is zero, in which case 0 is returned. In the presence of negative operands, the rounding direction is not guaranteed; see the % operator for more information. &&& : : word This begins the definition of a word. The definition extends until the following ;. Note that, unlike real FORTH, : and ; cannot be embedded in the definition of a word; also, the body of a word cannot be empty. &&& ; ; Ends a definition begun with :. See : for more information. &&& < < ( i1 i2 -- i ) Returns 1 if i1 is less than i2, 0 otherwise. &&& << << ( i1 i2 -- i ) Returns i1 left-shifted i2 bits. Unlike the C operator, if i2 is negative, this shifts right instead. However, like C, if the magnitude of i2 is greater than or equal to the number of bits used to represent an integer, the result is undefined. &&& <= <= ( i1 i2 -- i ) Returns 1 if i1 is less than or equal to i2, 0 otherwise. &&& = = ( i1 i2 -- i ) Returns 1 if i1 is equal to i2, 0 otherwise. &&& > > ( i1 i2 -- i ) Returns 1 if i1 is greater than i2, 0 otherwise. &&& >= >= ( i1 i2 -- i ) Returns 1 if i1 is greater than or equal to i2, 0 otherwise. &&& >> >> ( i1 i2 -- i ) Returns i1 right-shifted i2 bits. Unlike the C operator, if i2 is negative, this shifts left instead. However, like C, if the magnitude of i2 is greater than or equal to the number of bits used to represent an integer, the result is undefined. &&& @ @ ( v -- x ) Fetches the value of a variable. The top element of the stack must be a variable; its value is fetched and replaces the variable on top of the stack. &&& addlink addlink ( d1 d2 -- ) Links d1 to d2, much like the @link game command. The program must be able to build. If d1 is an exit, then except for wizard programs, it must be owned by the effective player, unless it has no links currently, and in any case the effective player is charged for the link. If d1 is is a player, thing, or room, then except for wizard programs, the effective player must control d1, and it must be possible for the effective player (or for wizard programs, d2's owner) to perform the link. Programs and daemons are not acceptable as d1. &&& addpennies addpennies ( d i -- ) Gives i dollars to d. Works only for wizard programs. d may be a player or a thing; i may be positive or negative. Things may not have their money supply reduced below 1; players' money supply is unrestricted. &&& addpennies-conserving [This entry is here to avoid throwing away the documentation for this variant of addpennies. There is no addpennies-conserving primitive.] addpennies ( d i -- ) Gives i dollars to d. Wizard programs are allowed to use addpennies without restriction to change the money supply of players or objects; the following apply to all other uses: - The dbref must refer to a player, or an error occurs. - The money is taken away from the effective player. - If the amount is negative, money is transferred in the other direction. - If the effective player is a wizard, that player's money supply is not affected. Whether the target player is a wizard makes no difference. - No player's money supply may be reduced below 0. - If the game was compiled with a limit on player money amounts, no player's money supply may exceed this limit. Attempts to violate the last two restrictions cause a run-time error. &&& addprop addprop ( d s1 s2 -- ) Adds property s1 to thing d with s2 as the value. Any previous property with the same name is replaced. (For compatability with old versions, addprop also accepts (d s1 s2 i), and ignores the integer.) &&& addprop-if addprop-if ( d s1 s2 -- s / 0 ) If d already has a property s1, its value is pushed; otherwise, the property is set to s2, and 0 is pushed. This operation is atomic with respect to all other property manipulations. &&& address? address? ( x -- i ) Returns 1 if its argument is an address object, 0 otherwise. (See the ' operator for more information.) &&& and and ( x1 x2 -- i ) Logical AND. The result is 1 if neither argument is false and 0 otherwise (see `man logic'). &&& atoi atoi ( s -- i ) Converts a string to an integer. If the string doesn't look like a number, the result will be 0. &&& awake? awake? ( d -- i ) Given the dbref of a player, this returns the number of times that player is connected. If given a non-player, it will always return 0. &&& backlinks backlinks ( d -- d1 d2 ... dN N ) Given an object, this returns a list of the objects which are linked to it. &&& backlocks backlocks ( d -- d1 d2 ... dN N ) Given an object, this returns a list of the objects which are locked and whose locks involve it. &&& begin This marks the beginning of a `while' loop construct. See `man while'. &&& break break ( -- ) break causes an immediate unconditional exit from the smallest enclosing do, for, or begin-while loop (see `man do', `man for', and `man while'). Control passes immediately to a point just after the closing "loop". &&& builder? builder? ( d -- i ) Returns true if the dbref is a builder. Precisely what this means can be changed at compile time, but for players it corresponds to the ability to use builder commands like @create and @dig, and typically is equivalent to something like `dup wizard? swap "b" flag? or'. &&& call call ( d -- ? ) Call hands execution over to a program specified by the dbref on the top of the stack. You either have to own the program being called or it has to have its L flag set. Be aware that when the program called finishes, it returns control to the caller, and the stack will be in the state that the called program left it in. &&& caller caller ( -- d ) Returns the player that called the first program in the chain of calls that eventually led to this program being executed. &&& callers callers ( -- d1 d2 ... dN N ) This returns a rudimentary stack trace. The list pushed onto the stack is a trace of the chain of calls by which control arrived in the program being executed: dN called dN-1 which called ... which called d2 which called d1 which called the program being executed. &&& caps caps ( s -- s ) Uppercases the first character of the string, lowercases the rest. &&& chown chown ( d1 d2 -- ) Changes ownership of d1 to d2. &&& conboot conboot ( i -- ) [wizard] Boots a specific connection. This is the only way to forcibly disconnect only one connection of a player who is connected multiple times. &&& concount concount ( -- n ) Returns the number of connections to the muck. This includes connections that have not yet issued a `connect' command to connect to a character. &&& condbref condbref ( i -- d ) Returns the dbref of the player connected on the specified connection. If the connection has not yet connected to a character, #-1 is returned. &&& conhost conhost ( i -- s ) [wizard] Returns the name of the host from which the specified connection was made. &&& conidle conidle ( i -- i ) Returns the idle time for a connection, measured in seconds. &&& connected? connected? ( i -- i ) Returns true if there is a connection on the specified descriptor. This will return true for connections that have not yet connected to a player; condbref can be used to tell. &&& connections connections ( -- d1 d2 ... dN N ) Returns a list of all connected descriptors. &&& connotify connotify ( i s -- ) [wizard] Writes the string to the connection. &&& contents contents ( d -- d ) Returns the first thing contained in a dbref. `next' should be used to step through the list of contents. Note that moving things into or out of the containing thing can invalidate this list; care is called for. &&& contime contime ( i -- i ) Returns the time since the descriptor was connected, in seconds. &&& continue continue ( -- ) continue causes the current iteration of the smallest enclosing do, for, or begin-while loop (see `man do', `man for', and `man while') to end and the next to begin. Thus, it's equivalent to braching to a point immediately before the closing "loop". &&& copyobj copyobj ( d -- d ) Clones the thing and returns the copy. Works only for objects, not players, rooms, exits, etc. In most respects, the copy is identical to the original; it differs only in that it has a different dbref number (of course) and that it has no actions attached to it. All other fields - property list, description, etc - are copied. The program must be able to build; except for wizard programs, the effective player is charged for the copy. The copy is owned by the same player as the original and is placed in the effective player's inventory. &&& create create ( s i -- d ) Creates an object with the string as its name and the number as its cost. The new object is owned by the effective player and is placed in that person's inventory. The program must be able to build, and except for wizard programs, the effective player is charged for the object. &&& ctime ctime ( i -- s ) Convert a time value, such as is returned by systime, to a human-readable string. (For those who know C, this is done with asctime(localtime(...)), with the trailing newline removed.) &&& daemon daemon ( -- d ) Returns the dbref of the daemon that executes the call. If the code is being run by a player instead of a daemon, returns #0. (#-1 would make more sense, granted.) &&& daemon? daemon? ( d -- i ) Returns true if the dbref refers to a daemon, false otherwise. &&& daemons daemons ( -- d ) Returns the first in a list of all daemons in the system (if there are no daemons, #-1 is returned). The `next' primitive can be used to step through the list. &&& date date ( -- d m y ) Returns the current date. y includes the century number. m is 1..12; d is 1..28, 1..29, 1..30, or 1..31 depending on y and m. Note that the returned values apply to the timezone the muck is running in, which doesn't necessarily bear any relation to the timezone any particular player is in. &&& db_top db_top ( -- i ) Returns the lowest dbref number that does not exist at all (that is, one more than the highest dbref that does exist). The returned value is an integer; see `man dbtop'. &&& dbcmp dbcmp ( d1 d2 -- i ) Returns true if d1 and d2 are identical (both must be dbrefs). Neither one need be a valid dbref. Note that unlike strcmp, this returns true if the dbrefs are equal. &&& dbref dbref ( i -- d ) Converts an integer to the corresponding dbref. No checks are made; if the integer is out of range, the result will not be a valid dbref. &&& dbref? dbref? ( x -- i ) Returns true if the thing is a dbref (room, player, object, etc), false if it's anything else (integer, string, etc). &&& dbtop dbtop ( -- d ) Returns the highest valid dbref. Identical to `db_top 1 - dbref' (except that it doesn't need an extra space on the stack, compiles to one instruction instead of 4, and is correspondingly faster). &&& depth depth ( -- i ) Returns the number of things on the stack. (The number returned is the count of things on the stack *before* the result is pushed; thus, the smallest possible returned value is 0, not 1.) &&& desc desc ( d -- s ) Returns the description string of a dbref. &&& dig dig ( s dp -- dr dp ) Digs a new room with name s and parent room dp; the new room (dr) is pushed on the stack and then the parent is pushed as well. (I'm not sure why the parent is pushed back on.) The program must be able to build, the effective player must be able to link rooms to the parent, and except for wizard programs, the effective player is charged for the room. The new room inherits its J flag setting from the effective player's J flag setting. &&& do do ( -- ) loop ( -- ) format: do loop do repeats body between the do and the loop indefinitely. This loop can be broken only by an exit or break within it, an interpreter error, or (if it's running in a daemon) by killing the daemon. See also `man break' and `man continue'. &&& drop drop ( d -- s ) Returns the drop message of a dbref. &&& dup dup ( x -- x x ) Duplicates the top element of the stack. &&& eif See `man if'. &&& else See `man if'. &&& exec exec ( ptr -- ) This takes a pointer to a word on top of the stack and executes the word it points to. See ' for more information. &&& execute execute ( addr -- ) This takes an address on top of the stack and executes the word it points to. See ' for more information. &&& exit exit ( -- ) Exits from the word it appears in, returning to whatever called that word. &&& exit? exit? ( x -- i ) Returns true if the argument is an exit dbref; otherwise (if the argument is not a dbref, or is some other kind of dbref), returns false. &&& exits exits ( d -- d ) Returns the first exit of a dbref. The `next' primitive can be used to step through the list. &&& explode explode ( sA sB -- sN ... s1 N ) Breaks sA into pieces, with occurrences of sB being the boundaries. Pushes the piecs and the number of pieces. Note that multiple consecutive occurrences of sB will produce empty strings in the resulting list. As a special case, if sB is "", sA is broken into single-character strings. The pieces are pushed in reverse order. Some examples: "this is a test" " " explode => "test" "a" "is" "this" 4 "foo bar" " " explode => "bar" "" "foo" 3 "a$b@c$@d$e@f" "$@" explode => "d$e@f" "a$b@c" 2 "this is a test" "xx" explode => "this is a test" 1 "hello" "" explode => "o" "l" "l" "e" "h" 5 &&& fail fail ( d -- s ) Returns the fail message for a dbref. &&& flag? flag? ( d s -- i ) The second argument must be a valid flag name or abbreviation. The flag? primitive returns true if the flag is set on the dbref, false otherwise. &&& flagstr flagstr ( d -- s ) Returns the short flag string for a dbref, with each flag represented by a single character (eg, Pmb or Rnjhv). &&& for for ( i i i -- i ) format: for <> loop The parameters to the for primitive are: the starting number, the ending number, and the size of the step [size of 0 will result in an endless loop]. The for primitive pushes the current value onto the stack and then executes the block of code. The body is always run at least once, even if the arguments would seem to imply otherwise. For example, `1 4 1 for dup loop' will push the same numbers on the stack that `1 1 2 2 3 3 4 4' would. See also `man break' and `man continue'. &&& force force ( d s -- ) The dbref must be a player. This causes the string to be executed as a command, as if the player had typed it. This does not work for QUIT, OUTPUTPREFIX, or OUTPUTSUFFIX. Except for wizard programs, the player running the program, the player who owns the program, and the player being forced must all be the same. &&& fork fork ( -- i ) Creates a new daemon (see sleep, @ps, @kill for more info). In the old thread, the number pushed is the number of the dbref of the new daemon; in the new daemon, the number pushed is zero. The new daemon is executing the same code its parent thread was, at the same place; the only difference is the value pushed onto the value stacks by the fork call. &&& getflags getflags ( d -- i ) Returns all the flags of a dbref, as an integer. This is of little use, as there is no corresponding setflags, and the bit definitions are undocumented and liable to change between versions of the system, but the various flags do correspond to bits in the integer. &&& getlink getlink ( d -- d ) Returns the thing a dbref is linked to. If the argument is an exit that is linked to more than one thing, only the first thing is returned; use getlinks if you need to access the others. &&& getlinks getlinks ( d -- d1 d2 ... dN N ) Returns all the things a dbref is linked to. If the argument is a room, thing, or player, the list consists of its drop-to or home (as appropriate), unless it's #-1, in which case the list is empty. If the argument is an exit, the list consists of all things the exit is linked to. If the argument is anything else, the list is empty. &&& getpropstr getpropstr ( d s -- s ) Fetches a property string. The first argument is the dbref whose property list is to be accessed; the second is a string naming the property. The result is the string value of the property, or "" if the property is not set. &&& getpropval getpropval ( d s -- i ) Fetches a property value. The first argument is the dbref whose property list is to be accessed; the second is a string naming the property. The result is the integer value of the property, or 0 if the property is not set. &&& gmtmerge gmtmerge ( i i i i i i i i -- i ) Converts a split-up time (see `man timesplit') to a timestamp value, interpreting the arguments as being UTC (nee GMT). &&& gmtsplit gmtsplit ( i -- i i i i i i i i ) Splits a timestamp value into a split-up time (see `man timesplit'), converting it to UTC (nee GMT) values. &&& god? god? ( d -- i ) Returns 1 if the argument has god privileges, 0 if not. Precisely what this means can be changed at compile time; it is typically equivalent to something like `dup #1 dbcmp swap "g" flag? or'. &&& if if ( i -- ) basic format: if [else ] then The if command will execute the block between it and the then (or the else, if present) if the value on the top of the stack is true. If the value is false, it will execute the block between the else and the then, if any. The test value is popped from the stack before either block is executed. (See `man logic' for the definitions of true and false.) An additional primitive, eif, is available, which functions as an "else if" conditional: the code between the else and the eif is executed, and if the top of the stack is true, the block after the eif is executed, otherwise control passes to the next else: if else eif else .... then This is equivalent to if else if else .... then then except that only one then is needed to close the whole structure. &&& ilimit ilimit ( -- i ) Returns the iteration count limit. If a program attempts to execute more than this many iterations, a fatal error will be generated. &&& instr instr ( s1 s2 -- i ) Finds s2 within s1, returning the offset of the first such occurrence, or 0 if s2 does not occur within s1. (The returned offset is 1-origin, that is, if s2 occurs at the very beginning of s1, the returned value is 1.) &&& int int ( d -- i ) Converts a dbref to its integer index in the database. (This actually works for variables as well, returning the variable number, though MUF variables are of questionable utility in any case.) &&& int? int? ( x -- i ) Returns 1 if its argument is an integer, 0 otherwise. &&& intostr intostr ( i -- s ) Converts an integer to a string. This is the converse of atoi. &&& kill kill ( d -- ) Kills a daemon, as identified by its dbref. The daemon being killed will execute no further code after this call. Thus, for example, the sequence daemon kill can be used by a daemon to commit suicide. (Note that it will work only when the code is actually being run by a daemon.) &&& linkcount linkcount ( d -- i ) Returns the link count of a dbref. For players, always returns 1; for programs and daemons, always returns 0. For objects, returns 1 if the object has a home, otherwise 0; for rooms, returns 1 if the room as a drop-to, otherwise 0. For exits, returns the number of things the exit is linked to. &&& location location ( d -- d ) Returns a thing's location. For players, objects, and programs, this is the room the thing is in; for rooms, it is the room's parent. For exits, it is the thing the exit is attached to. For daemons, I'm not sure what it does. &&& lock lock ( d s -- ) Locks a dbref. s is a string giving the lock expression. If s is "", the dbref is unlocked. (unlock can also be used to unlock a dbref.) &&& locked? locked? ( d -- i ) Returns true if the dbref is locked, false if it's unlocked. &&& lockstr lockstr ( d -- s ) Returns the lock of the dbref as a string. If the dbref is not locked, "" is returned. The resulting string is acceptable to the lock primitive, but is generally not appropriate for human interaction. See also unparse_lock. &&& loop loop terminates a for, while, or do loop. See `man for', `man while', and `man do'. &&& match match ( s -- d ) Matches a string, returning the dbref of the matched thing. If the match fails, #-1 is returned; if the match is ambiguous, #-2 is returned. (#-3 is returned if the string is "home".) &&& moveto moveto ( d1 d2 -- ) Moves d1 to location d2. Unfortunately this is fairly restrictive; several restrictions apply. They are rather complicated and the details vary depending on the type of thing being moved. In all cases, though, the thing being moved must either be set J(ump_OK) or be owned by the effective player running the program (exception: wizard programs are free from this restriction). To see the other restrictions, ask for `man moveto-', where is the type of the thing being moved: player, thing, room, or exit (programs are treated as things for the purposes of moveto). (Eg, `man moveto-player' to see the restrictions that apply when moving a player with moveto.) Objects of other types (eg, daemons) cannot be moved with moveto at all. To send a player or thing to its home, #-3 can be given as the destination. &&& mucker? mucker? ( d -- i ) Returns 1 if the thing has mucker privileges, 0 if not. Precisely what this means can be changed at compile-time; it is typically equivalent to something like `dup wizard? swap "m" flag? or'. For players, this corresponds to permission to use the @prog and @edit commands. &&& name name ( d -- s ) Returns a dbref's name. &&& next next ( d -- d ) If the dbref is an exit, returns the next exit in the internal list of exits attached to the object the exit is attached to. If the dbref is some other type, returns the next object in the list of contents in the object's containing object. If the dbref is a daemon, returns the next daemon. This is intended to be used to step down a list obtained with the contents, exits, or daemons primitive. #-1 is returned to indicate the end of the list. &&& nextowned nextowned ( d -- d ) Returns the next object in the internal list of objects owned by the owner of the specified object. This is intended to be used to step down the list of everything owned by a player. (The proper way to start such a loop is to use the player itself as the beginning of the list.) #-1 is returned to indicate the end of the list. &&& nop nop ( -- ) Does nothing. Doesn't even show up on debug traces. Exists mainly for internal reasons, though can be used as a placeholder where an empty block is not allowed (such as the body of a word that is supposed to do nothing). &&& not not ( x -- i ) Returns 1 if its argument is false, 0 if its argument is true. (See `man logic' for a description of what is considered false and true.) &&& notify notify ( d s -- ) Sends the string to the dbref. If the dbref is a player, the string is sent to all of that player's connections. If the dbref is a player or thing, all hear exits attached to it are activated. If the dbref is of any other type, nothing happens. &&& notify_except notify_except ( d1 d2 s -- ) Sends the string to everything contained in d1, which must be a room, except that if d2 is one of the things contained in d1, it does not get notified. (Notification is done as if with the notify primitive.) In addition, any hear exits attached to d1 or any of its ancestors are activated. Any hear exits attached to the player running the program are also activated, [may be the effective player, but I think not]. &&& number? number? ( s -- i ) Returns 1 if the argument is a string which contains a valid number, 0 if the argument is not a string or doesn't look like a number. &&& numowned numowned ( d -- i ) Returns the number of dbrefs owned by the player who owns the argument dbref. Wizard programs may use this with any dbref; for other programs, the player whose ownership count is to be computed must be the player running the program (or if running in a daemon, the player owning the daemon.) &&& odrop odrop ( d -- s ) Returns the odrop message on the argument dbref, or "" if the dbref has no odrop message. &&& ofail ofail ( d -- s ) Returns the ofail message on the argument dbref, or "" if the dbref has no ofail message. &&& ok? ok? ( d -- i ) Returns true if the dbref is a valid object: its number is not less than 0 or larger than the current size of the database, and is not a garbage object. &&& online online ( -- d1 ... dN N ) Returns a list of players online. Players connected more than once appear in the list more than once. The list is in the order it happens to be kept in internally, which is not useful for much. &&& open open ( s d -- d ) Opens a new exit with the specified name, attached to the specified dbref. The new exit's dbref is left on the stack. The new exit is owned by the effective player, but is not linked (note that linking an unlinked exit affects its owner). The program must be able to build, and except for wizard programs, the effective player (a) must own the argument dbref and (b) is charged for the exit. &&& or or ( x x -- i ) Returns 1 if either of its arguments is true, otherwise 0. (See `man logic' for a description of what is considered true and false.) &&& osucc osucc ( d -- s ) Returns the osuccess message on the argument dbref, or "" if the dbref has no osuccess message. &&& over over ( x1 x2 -- x1 x2 x1 ) Duplicates the next-to-topmost thing on the stack, pushing it on top, over the topmost thing. &&& owner owner ( d -- d ) Returns the dbref of a dbref's owner. &&& passlock? passlock? ( d1 d2 -- i ) Returns 1 if d1 passes the lock on d2, otherwise 0. If d2 is not locked, this will always return 1. &&& pennies pennies ( d -- i ) Returns the amount of money of a dbref. The argument must be a player or thing. &&& pick pick ( d1 ... dN N -- d1 ... dN d1 ) Copies the Nth item down on the stack, pushing the copy on top of the stack. Thus, 1 pick is equivalent to dup and 2 pick is equivalent to over. &&& player? player? ( x -- i ) Returns true if the argument is a dbref that refers to a player, 0 if it's not a dbref or is some other type of dbref. &&& pop pop ( x -- ) Pops the top element off the stack and throws it away. &&& prog prog ( -- d ) Returns the dbref of the program the call occurs in. &&& program? program? ( x -- i ) Returns true if the argument is a dbref that refers to a program, 0 if it's not a dbref or is some other type of dbref. &&& prompt prompt ( s -- s' ) Like read, but prints its argument string first, without a line break following it, as a prompt. (This message is invisible to hear exits.) &&& pronoun_sub pronoun_sub ( d s -- s ) Performs pronoun substitution on the string, using the dbref as the source of replacement strings. Pronoun substitution is done with % signs in the string. When a % occurs, the following character determines what the pair is replaced with. In each case, the sex: property on the dbref also affects the result, and in some cases the dbref's name (which is assumed to be "Name" in the table below). First, the % and the following character are taken as a two-character property name which is looked for on the dbref. If it's found, the property string value is used as the replacement string. Otherwise, the following table describes the replacement string. sex:male sex:female sex:neuter other %a his hers its Name's %s he she it Name %o him her it Name %p his her its Name's %r himself herself itself Name %n Name Name Name Name If the character after the % is uppercase, the first character of the replacement string is uppercased, except when the replacement comes from the "other" column of the table; in that case, the initial character is left alone. (I don't know why this is, particularly when the %n row and properties get the capitalization.) If the sequence is not one given in the table and no property is found, the % is dropped and the following character retained as the replacement. &&& prop-exists? prop-exists? ( d s -- i ) Returns 1 if the specified dbref has a property whose name is the given string, 0 otherwise. The value of the property is irrelevant; thus, this is more reliable than calling getpropstr and checking to see whether the result is "", since a property can exist with "" as its value. &&& propfirst propfirst ( d -- d s 1 ) [or] ( d -- 0 ) If the dbref has any properties, the first one's name is pushed on the stack, followed by 1. If the dbref has no properties, it is popped from the stack and 0 is pushed. (The number is intended to be used by a conditional of some sort, with the dbref and string ready to hand to propnext in the "true" case.) See propnext for more information. &&& propnext propnext ( d s -- d s 1 ) [or] ( d s -- 0 ) Given a dbref and a property name, the next property name is returned; if there are no more properties, the dbref and name are popped and 0 is pushed. The order in which properties are accessed by propfirst and propnext is unspecified. What happens if properties are added or deleted during the iteration is also unspecified; however, in the absence of any addprop or remove_prop calls on the dbref, starting with propfirst and iterating with propnext is guaranteed to find all properties the dbref has. &&& pstack pstack ( i -- ) pstack ( i s -- ) The integer argument is taken as a count of stack elements; the top that many elements of the stack are printed. The output goes to the same place the debugging output from programs set D goes. If the string second argument is present, it is printed as a tag at the beginning of the line; otherwise, a default ("Stack" as of this writing) is used instead. There is a length limit (about 500 characters at this writing) on the resulting line; if this is exceeded, remaining elements will be printed as "...". This is intended as a debugging aid. &&& ptr? ptr? ( x -- i ) Returns 1 if its argument is a pointer object, 0 otherwise. See ' for more information. &&& put put ( x1 ... xN y N -- y x2 ... xN ) This simply replaces the Nth element down on the stack, rather like an assignment, with the stack treated as an array. &&& random random ( -- i ) This returns a random positive integer, from 0 through the largest positive integer the muck can represent. Normally this is followed with a % operation to reduce the range of the number to something manageable. &&& read read ( -- s ) Returns a string read from the player. The program must be being run by a player rather than a daemon, or an error is generated. The program stops running and waits until the player types a line of input. This line of input is pushed on the stack as a string, and the program resumes execution at the point just after the read call. (Currently, this does not work in a program being run as part of testing a lock.) &&& recycle recycle ( d -- ) Recycles the dbref, like the @recycle command. The object must be owned by the effective player, even for wizard programs. The object also must not be the program the recycle call appears in, nor any of the programs in its chain of callers. You also can't recycle the global environment or player start rooms, or any daemon, player, or garbage object. &&& remove_prop remove_prop ( d s -- ) Removes the specified property from the specified dbref. If a property with the specified name existed, it is removed; otherwise, nothing happens. &&& remprop-if remprop-if ( d s1 s2 -- i ) If d already has a property s1 whose value is s2, it is removed and 1 is pushed; otherwise, no property changes occur and 0 is pushed. This operation is atomic with respect to all other property manipulations. &&& rinstr rinstr ( s1 s2 -- i ) Finds s2 within s1, returning the offset of the last such occurrence, or 0 if s2 does not occur within s1. (The returned offset is 1-origin, so that, for example, if s2 occurs only at the very beginning of s1, the returned value is 1.) &&& rmatch rmatch ( d s -- d ) Matches the string in the context of the dbref, returning the result of the match. The dbref must be a player, room, or thing; in any case, the string is matched against the exits attached to the dbref, and in the case of a player or room, against the inventory or contents as well. Unfortunately "here" and "me" and "home" don't work; also, if the dbref is a player, the player's location and its parent rooms are not searched. &&& roll roll ( xN ... x1 N M -- xM ... x1 xN ... xM-1 ) Rotates the top N elements of the stack M places. If N is less than zero, and error occurs; if N is 0, nothing is done but popping N and M off the stack. Otherwise, there must be at least N additional elements on the stack (or an error occurs); the top M of them are removed and placed below the others. M is taken modulo N, so the effective M value is always 0 through N-1; the value actually found on the stack may be any value, positive, negative, or zero. &&& room? room? ( x -- i ) Returns 1 if the argument is dbref that refers to a room, or is #-3. Otherwise 0 is returned. &&& rot rot ( x1 x2 x3 -- x2 x3 x1 ) Rotates the top three elements of the stack. This is equivalent to `3 rotate'. &&& rotate rotate ( x1 x2 ... xN N -- x2 ... xN x1 ) ( x1 ... xN-1 xN -N -- xN x1 ... xN-1 ) Rotates the top N elements of the stack. If the argument is positive, pulls an element from N elements down on the stack and puts it on top; with a negative argument, performs the converse operation, moving the top element to a lower place on the stack. Thus, 3 rotate is identical in effect to rot, and 2 rotate (or -2 rotate) is identical in effect to swap. &&& set set ( d s -- ) Sets or clears a flag on a dbref. The string must be one of the valid flag names, or such a name with a ! prefixed to it. (Abbreviations are accepted.) This sets the flag, or with the ! prefix, clears it, on the dbref. Except for wizard programs, the effective player must own the dbref. Some flags cannot be set or cleared from MUF at all; as of this writing, they are Wizard, Mucker, Visual, Unseen, Quell, and God. In addition, non-wizard programs are not allowed to set or clear the Dark bit on anything but a room or program. &&& setdesc setdesc ( d s -- ) Sets the description string for the dbref. Except for wizard programs, the effective player must own the dbref. &&& setdrop setdrop ( d s -- ) Sets the drop message for the dbref. Except for wizard programs, the effective player must own the dbref. &&& setfail setfail ( d s -- ) Sets the fail message for the dbref. Except for wizard programs, the effective player must own the dbref. &&& setilimit setilimit ( i -- ) [wizard] Sets the iteration limit. If a MUF program attempts to run for more than this many cycles, it will be aborted with an error. (If this is set to too small a number, MUF will be useless until the muck is shut down and restarted; no check is made for this. If it is more than about 3, though, a program can be written that will set it back.) Note that if the program does a sleep, the count of iterations it has used is reset to zero. &&& setname setname ( d s -- ) Sets the name of the dbref. Except for wizard programs, the effective player must own the dbref. Only wizard programs are allowed to use this when the dbref is a player. &&& setodrop setodrop ( d s -- ) Sets the odrop message for the dbref. Except for wizard programs, the effective player must own the dbref. &&& setofail setofail ( d s -- ) Sets the ofail message for the dbref. Except for wizard programs, the effective player must own the dbref. &&& setosucc setosucc ( d s -- ) Sets the osuccess message for the dbref. Except for wizard programs, the effective player must own the dbref. &&& setsucc setsucc ( d s -- ) Sets the success message for the dbref. Except for wizard programs, the effective player must own the dbref. &&& sleep sleep ( i -- ) sleep ( d -- ) Sleep with an integer argument causes the current program to sleep for i seconds. With a dbref as an argument, it sleeps until some (other) program uses the wakeup primitive on the same dbref. Technical information: When a player starts a program and that program does a sleep call, a daemon [see @ps, @kill for more info] is spawned that will continue executing the program at the designated time. If the program does another sleep, it will extend the life of the daemon. An example program: : main do me @ "test" notify 60 sleep loop ; This will run an endless loop that notifies you every 60 seconds with the "test" message. To stop the program use @kill on the dbref of the daemon. &&& strcat strcat ( s1 s2 -- s ) Concatenates two strings, returning the result. For example, `"foo" "bar" strcat' will leave the string "foobar" on top of the stack. &&& strcmp strcmp ( s1 s2 -- i ) Compares two strings, returning an integer that is less than, equal to, or greater than zero, as s1 is less than, equal to, or greater than s2. Upper/lower case distinctions are significant, and machine character values are used to determine what constitutes less than or greater than. &&& strcut strcut ( s i -- s1 s2 ) Cuts a string. i must not be less than zero. If i is larger than the length of s, then s1 is s and s2 is ""; otherwise, s1 consists of the first i characters of s, with s2 holding the remainder. &&& string? string? ( x -- i ) Returns 1 if its argument is a string, 0 otherwise. &&& stringcmp stringcmp ( s1 s2 -- i ) Compares two strings, returning an integer that is less than, equal to, or greater than zero, as s1 is less than, equal to, or greater than s2. Both strings are mapped to lower case for purposes of the comparison, with machine character values used to determine what constitutes less than or greater than after the mapping. &&& strlen strlen ( s -- i ) Returns the length of its string argument. &&& strncmp strncmp ( s1 s2 n -- i ) Compares two strings. At most the first n characters are compared; this is otherwise identical to strcmp. &&& subst subst ( s1 s2 s3 -- s ) Performs substitution. The returned string s is just the same as s1, except that wherever s3 occurs in it, it is replaced with s2. s3 must not be "", but either of the other two arguments may be. In case multiple occurrences of s3 overlap, the ones that are replaced are the ones found in a simple left-to-right scan. When a replacement occurs, the left-to-right scan starts afresh; characters before the match point and characters coming from s2 are not considered when looking for possible occurrences of s3. Some examples: "xaabaabaax" "cha" "aabaa" subst => "xchabaax" "xaabaaabaax" "cha" "aabaa" subst => "xchaabaax" "xcabaabaax" "cha" "aabaa" subst => "xcabchax" "axxyxyx" "" "xyx" subst => "axyx" &&& succ succ ( d -- s ) Returns the success message for the dbref. &&& swap swap ( x1 x2 -- x2 x1 ) Exchanges the top two elements of the stack. &&& systime systime ( -- i ) Returns the current system time, which presently is an integer number of seconds since 00:00:00 GMT, Jan 1, 1970. &&& then See `man if'. &&& thing? thing? ( x -- i ) Returns 1 if the argument is a dbref that refers to a thing, or 0 otherwise (if the argument isn't a dbref, or is a dbref of some other type). &&& time time ( -- is im ih ) Returns the current time of day, in seconds, minutes, and hours. Note that this is the time of day in the timezone the muck is running in, which doesn't necessarily bear any relation to the timezone any particular player is in. &&& time_created time_created ( d -- i ) Returns the time the dbref was created, in seconds since 00:00:00 GMT, Jan 1, 1970. &&& time_modified time_modified ( d -- i ) Returns the time the dbref was last modified, in seconds since 00:00:00 GMT, Jan 1, 1970. &&& time_used time_used ( d -- i ) Returns the time the dbref was last used, in seconds since 00:00:00 GMT, Jan 1, 1970. &&& timemerge timemerge ( i i i i i i i i -- i ) Converts a split-up time (see `man timesplit') to a timestamp value, interpreting the arguments as being in the timezone the muck is running in. &&& timesplit timesplit ( i -- i i i i i i i i ) Splits a timestamp value into a split-up time, converting it to the appropriate values for the timezone the muck is running in. A split-up time is eight integers on the stack. From bottom to top, they are seconds (0-60), minutes (0-59), hours (0-23), day-of-month (1-31), month (1-12), year (eg, 1992), day-of-week (1-7, 1=Sunday), and day-of-year (1-366). &&& tolower tolower ( s -- s ) Returns the argument string, with all uppercase characters converted to the corresponding lowercase characters. &&& touch touch ( d -- ) This sets the last-used time of the dbref to the current time. &&& toupper toupper ( s -- s ) Returns the argument string, with all lowercase characters converted to the corresponding uppercase characters. &&& trig trig ( -- d ) Returns the dbref that triggered the program run; normally this will be an exit, but may be something else, particularly when dbrefs are locked to programs. This is always the value initially stored in the trigger variable; normally, trigger @ is to be preferred over trig, because the former can be changed. &&& unlink unlink ( d -- ) Unlinks a room or exit. If the argument is an exit, it is unlinked from everything it is linked to. If the argument is a room, its drop-to, if any, is removed. Other argument types produce an error. The program must be able to build, and except for wizard programs, the effective player must own the thing being unlinked. &&& unlock unlock ( d -- ) Unlocks a dbref. Except for wizard programs, the effective player must own the dbref. &&& unparse_flags unparse_flags ( d -- s ) Returns the flags of the dbref as a string. This returns the same information flagstr does, but in the long, human-readable, form, like Type: PLAYER Flags: Mucker Builder or Type: ROOM Flags: NoInventory Jump_OK Haven Visual &&& unparse_lock unparse_lock ( d -- s ) Returns the lock of the dbref as a string. If the dbref is not locked, "*UNLOCKED*" is returned. The string is intended to be human-readable and it is not acceptable as the second argument to lock. See also lockstr. &&& unparse_object unparse_object ( d1 d2 -- s ) Returns the name of d1 as it would be seen by d2. d2 must be a player, and checks for control and Author flags and all similar things are performed just as they would be by the muck itself, if it were to generate the name of d1 to be displayed to d2. &&& var var word This declares the following word as a variable. All variable declarations must appear outside all : definitions in a program. Unfortunately the variable allocation scheme is rather badly broken; you are probably better off avoiding variables altogether, except for the three built-in ones (me, loc, trigger). &&& var? var? ( x -- i ) Returns 1 if its argument is a variable, 0 otherwise. &&& variable variable ( i -- v ) Given a variable number, returns the corresponding variable object. Variable allocation in MUF is rather badly broken; you are probably better off avoiding variables altogether, except for the three builtin ones (me, loc, trigger). &&& wakeup wakeup ( d -- ) This wakes up any daemons that are sleeping on the given dbref. No indication is given of how many daemons are awakened, or indeed if any are. (All daemons sleeping on the dbref are awakened, not just one.) &&& while while ( x -- ) format: begin while loop An indefinite loop. The code is executed. The `while' pops the top object off the stack; if it is false (see `man logic'), the loop terminates and control passes immediately to the code following the terminating `loop'. Otherwise, the code is executed and control returns to the beginning of the code. Note that while the code will normally push one thing on the stack, this is not required; when the while is encountered, it just takes whatever it finds on the top of the stack as the test value. Any begin-while loop can be written as a do loop with a break inside it. See `man break' and `man continue'. &&& wizard? wizard? ( d -- i ) Returns true if its argument has wizard privileges. Precisely what this means is a compile-time option, but it is typically equivalent to something like `dup god? over "w" flag? or swap "q" flag? not and'. &&& yield yield ( -- ) The muck timeshares among all currently-executing programs. When a player or daemon has executed enough, it is suspended and others are given a chance to run. The yield primitive allows a thread to voluntarily give up the rest of its time-slice. &&& | | ( i1 i2 -- i ) Returns the bitwise OR of its operands. &&& ~ ~ ( i -- i') Returns the bitwise complement of its operand. &&& MARKER - end of descriptions &&& moveto-player Restrictions on moving a player with moveto: The destination must be a room or #-3. For wizard programs, this is the only restriction. Otherwise, the room the player is being moved from must either be set J(ump_OK) or be owned by the effective player; the same must be true of the destination room, unless it's #-3, which is always allowed. &&& moveto-thing Restrictions on moving a thing (or program) with moveto: The destination must be a room or player. For wizard programs, this is the only restriction. Otherwise, a rather strange algorithm is applied. If the effective player owns the destination, then the condition below must be true of it; otherwise, if the effective player owns the current location of the thing being moved, the condition below must be true of that. If neither the current location nor the destination is owned by the effective player, no further condition applies (this is the really peculiar part). The condition referred to above is that the location in question must either be set J(ump_OK) or be owned by the effective player. &&& moveto-room Restrictions on moving a room with moveto: The destination must be a room. The room being moved must not be the global environment room (usually #0). If the destination is #-3, the effective destination is the global environment room and no further checks are done. The destination must not be contained in the room being moved, either directly or indirectly. For non-wizard programs, the the effective player must own the room being moved and must be able to link to the destination. &&& moveto-exit Restrictions on moving an exit with moveto: The destination must be a room, player, or thing. For non-wizard programs, the effective player must own the exit being moved and must be able to link to the destination.