TinyMUSH Manual Version 2.007:
   Last revised 8/29/93. Amberyl. lwl@eniac.seas.upenn.edu

Section III: Programming Applications

5. Vehicle programming
 5.1  Entering and leaving objects: @enter, @aenter, @oenter, @oxenter,
      @leave, @aleave, @oleave, @oxleave
 5.2  Inside vehicles: @idesc, @listen, relays, and commands, @remit, 
      AUDIBLE, @prefix, @filter, @forwardlist
 5.3  Do it!  --  Wagon controller
6. Complex programming
 6.1  Useful functions: 
         General use: NUM(), LOC(), NEARBY()
         List creation: LCON(), LEXITS(), LWHO()
         Parsing: POS(), FIRST(), REST(), STRLEN(), MID(), WORDS()
         Matching: EXTRACT(), MATCH(), MEMBER(), UCSTR(), LCSTR(), CAPSTR()
 6.2  Non-standard attributes: & and attribute flags
 6.3  Introduction to @dolist
 6.4  Applications of @dolist
 6.5  Time synchronization: semaphores, complex @wait, @notify, @drain
 6.6  Security problems in programming, INHERIT, ESCAPE(), SECURE(),
         @fsay, @femit, @fpose
 6.7  Debugging: PUPPET and VERBOSE
 6.8  On the New Programming Style
7. What to do next
 7.1  Hints and tips


5. Vehicle programming

5.1   Entering and leaving objects

      Objects can be used as containers if they are set ENTER_OK. You can
enter an object by typing "enter <object>" and exit an object by typing
"leave". You may enter any object that you own or is set ENTER_OK, and,
in 1.50, that you pass the enter lock of.
      You may set EALIAS and LALIAS attributes on objects. The string in 
these two aliases may be used as a substitute for "enter <object>" and "leave".
      Entering an object triggers the messages @enter, @oenter, @oxenter, and
@aenter. The player who enters is shown the @enter message. The others inside
the object see the @oenter message. People in the room that the player just
left (which may not necessarily be the same room that the object is in, if
the object is @tel'ed to) see the @oxenter message. @aenter is the action
list to be executed.
      Leaving an object triggers the @leave, @oleave, @oxleave, and @aleave
messages. @leave is shown to the leaving player, @oleave is shown to the
things inside the object the player just left, @oxleave is shown to the 
things in the room the player goes to (not the room that the container object
is in  - if the player teleports or goes home, for example, the @oxleave
message is shown at the player's destination). @aleave is the action list
to be executed.

========================
[ Example 5.1:  Wagon ]
[ This creates the most basic of container objects ]
> @create Wagon
Wagon created as object #953
> @enter wagon=You climb into the wagon.
Set.
> @oenter wagon=climbs up into this wagon.
Set.
> @oxenter wagon=climbs up into the wagon.
Set.
> @leave wagon=You climb down from the wagon.
Set.
> @oleave wagon=climbs off this wagon.
Set.
> @oxleave wagon=climbs off the wagon.
Set.
> @set wagon=enter_ok
Set.
========================


5.2   Inside objects: internal descriptions, echoing, and relays

      An object's internal description - the description displayed to those
inside it - can be set using @idesc <object>=<description>. This functions
identically to @desc, except it is only visible by those inside.
      To enable those inside the object to hear what is going on outside, set
the @listen of the container to *. Anything that is in the object's @listen
match will be relayed to the occupants.
      Talking and posing within objects is identical to talking and posing in
rooms. Unless there is some sort of relay set up (described below), only those
inside the object can hear you. 

      It is frequently useful to be able to talk to the outside world, and
perform other actions, like looking at the room that the object is in. This
is best done with user-defined commands on an object which is placed inside
the container object. It's a bad idea to define the commands directly on the
container, since they can be used by those who are outside the object.

      The simplest way to handle looking outside is to do a user-defined
command which forces the object to do a "look".  This is extremely inelegant,
though. On MUSHes which provide it (all 1.50 and most 2.0), the command
"look/outside" will allow you to look outside the container you are in.
      Taking objects which are outside, however, generally requires a
user-defined command which forces the object to do a 'get' or @teleport.


In the past:
      The simplest way of doing relays is to add special user-defined commands
for say and pose which force the object to emit. When the object emits, both
players inside and outside the object will hear the message.
      Another, more direct, way of talking to the outside world from the
inside - actually, of showing a message to only those outside - is to
use @emit/room. This outputs the message to the outermost container - the
room that the wagon or similar object is in.

      The 'best' way to relay information, however, is to use the AUDIBLE 
flag. This flag essentially outputs text from one place to another, without
danger of looping.
      When set on an object, anything "said" (posed, emitted, etc.) inside 
the object will be broadcast to the object's location, prepended with the
string "From <name of AUDIBLE object>,"  The AUDIBLE object does not receive
its own propagated messages, nor does it bounce back things it hears via
"@listen *" from the outside world.
      AUDIBLE exits "funnel" noise from their source room to their 
destination room. In 1.50, the room itself must be set AUDIBLE, to activate
AUDIBLE exits. The AUDIBLE exit propagates the message to the next room
and no farther; if there are AUDIBLE exits in the next room, they do NOT
pass the information on to their destinations. Messages channeled through
AUDIBLE exits are prepended with, "From <name of AUDIBLE exit's source>,"
(1.50) or "From a distance,"  (2.0).
      2.0 also provides an additional command, @forwardlist. This command,
with the syntax "@forwardlist <object>=<space-separated list of dbrefs>",
forwards all messages heard by <object> to every object in the list of
dbrefs. <object> must have its AUDIBLE flag set.
      You can filter out messages by setting the @filter attribute with
a (possibly wildcarded) pattern to suppress. For example, if you don't
want "<name> has left." messages, "@filter <exit>=* has left.", and messages
matching that pattern will not be propagated. You can have more than one
pattern; they should be separated by commas.  (i.e., you can do:
"@filter <exit>=* has left.,* has arrived." to suppress both arrival
and departure messages). If the pattern contains a comma, the entire
pattern should be enclosed in curly braces {} (just like in @switch).
      You can change the string prepended to propagated messages via
the "@prefix" attribute on the AUDIBLE object. The game always puts a 
space between the prefix and the propagated message. Generally, prefixes
are of the format, "From Mnedranth's back,"  or  "In the gazebo,"  or
the like -- something which indicates where the message is coming from.
The game automatically prepends one if the @prefix attribute is not set.
There are times when it is desirable to have no prefix prepended at all;
in those cases, set the @prefix attribute to "\". 

      There is an additional refinement: @infilter and @inprefix.
@infilter suppresses text that is normally sent to the object via @listen
(usually "@listen *"). @inprefix will prefix text forwarded from the outside
with a string. Normally, text forwarded via @listen is not prepended with
anything.


5.3   Do it!  --  Wagon controller

      This section assumes that you have created a wagon as described in
example 5.1. Below, <#wagon> refers to the dbref number of that wagon, and
<#cont> refers to the dbref number of the controller.

Enter the following commands:

@idesc <#wagon>=<description>
@listen <#wagon>=*
@create Wagon controller
@lock control=me
drop control

Possibilities:

This is the old way of doing things:
@va <#cont>=$'*:@fo <#wagon>=@emit {On the wagon, %N says, "%0"}
@vb <#cont>=$.*:@fo <#wagon>=@emit {On the wagon, %N %0}
[ These two commands define ' and . as alternates to " and : inside the wagon.
  They relay to the outside world, as well as to those inside the vehicle.
  There is one major problem with this: because of the @listen, the players
  inside the wagon hear exactly what the wagon hears, which is the message
  "You emit: <whatever>"  This is ugly, but it's effective. ]
@vc <#cont>=$view:@fo <#wagon>=l
@vd <#cont>=$view *:@fo <#wagon>=l %0
[ These two commands substitute for look. ]

This is the new way of doing things:
@set <#wagon>=AUDIBLE
@prefix <#wagon>=On the wagon,
[ There is no need for the view command; "look/outside" will suffice. ]

@ve <#cont>=$snag *:@fo <#wagon>=get %0
[ This command forces the wagon to get an object outside. ]


6.    Complex programming

6.1   Useful functions

       Often, you will want to build machines that accept input from players 
only; the NUM() function is useful for checking whether or not something
is a player. Simply evaluate: num(*%N), assuming that you are checking if
the enactor is a player. The * forces %N to be evaluated as a player; if
there is no player by that name, the function returns "#-1". The only case
in which this trick with num(*%N) fails is if the enactor has the same
name as a player.  You can also use the TYPE() function to see if an
object is a player.

      The LOC() function is useful for several things. If it is used to
locate a player, it will return the number of the player's location, assuming
that the player is not set UNFINDABLE. If it is used to locate an object
that you control, it will return the number of its location. It will return
#-1 if you try to locate an object you don't control. Used on an exit,
LOC() will return the dbref number of the exit's destination (to get an
exit's source, use the HOME() function). The LOC() function returns the
drop-to of a room; usually, this is #-1.
      Related to the loc function is the %L substitution. This returns
the location of the enactor. Since it requires the enactor to trigger
off a command of some sort, however, it cannot replace the LOC() function,
unless you just want LOC(%N).

      The NEARBY() function tests if one object is near another. It is
called with: nearby(obj1,obj2). For this function to work, you must control
at least one of the objects, or be near one of them. Object1 is considered
to be nearby Object2 if it is in the same location, if it is being carried
by Object2, or it is carrying Object2. If the two objects are nearby, the
function returns a 1; otherwise, it returns 0.

      The MUSH functions you will use most often will probably be those
which return names and dbrefs. But almost all of MUSH programming involves 
the manipulation of lists - adding items, removing items, finding certain 
items within, etc. Lists, for MUSH purposes, are generally defined as a
list of space-separated of words. The first word in a list is 1.
Strings, on the other hand, are composed of arbitrary characters. The
first character in a string is 0. Lists are basically special types of
strings. Everything in MUSH is eventually treated as a string.

     Several functions create lists: LCON(), LEXITS(), and LWHO() are
perhaps the most frequently used of these. LCON() gives a list of the 
dbref numbers of all objects in a room (including dark objects). LEXITS() 
gives a list of the dbref numbers of all non-dark exits out of a room. 
LWHO() gives a list of all non-dark connected players.

     Several functions are useful for parsing lists. The POS() function,
called with pos(string1,string2), returns the position number of string1
in string2. If string1 is not in string2, the function returns #-1. 
The first character is considered to be position 1. This function
is particularly useful when checking flags on an object. For example, to
check if an object is a puppet, check pos(p,flags(object))   If this returns
anything but #-1, the object is a puppet.  (An easier way to do this is to 
use the HASFLAG function: HASFLAG(object,puppet) will return 1 if the object 
is a puppet).

     For parsing, FIRST() and REST() are useful. They return the "head"
and the "tail" of a list, respectively, and are basically identical to
the LISP functions CAR() and CDR(). The "head" of a list is the first
word in that list; the "tail" of the list is everything else.

     The WORDS() function counts the number of words in a list. This is
useful for a loop counter ("repeat this action until the counter variable
is greater than the number of words in the list"), and for finding the
last word in a list, which is done as follows:
  Assuming that the list is in %0: extract(%0,words(%0),1)
  This counts the number of words in the list, then uses extract to take a
  one-word long list starting from that position - the last.

      The STRLEN() function returns the length of an entire string (list).
It is extremely useful when used in conjunction with the MID() function.
The latter is called with: mid(string,position of first character,length)
and returns a string of <length> characters starting from <position>.
The first character in the string is numbered 0, not 1.
Supposing you wish to return a string starting with its third character.
You would use: mid(string,2,strlen(string))

      The EXTRACT() function, mentioned above, called with
extract(list,first,length), is used to pull out words from the middle
of a list. "Length" is the number of words to be extracted, _not_ the
number of letters.
      MATCH(), called with match(list,pattern), returns the number of the
word where <pattern> first occurs. The first word in the list is numbered 1.
If no match is found, the function will return 0. The pattern may be straight 
text, or it may contained the wildcards * and ?. The MEMBER() function is 
similar, except that it does not take wildcards, and is case-sensitive,
so match(a B c d,b) will return 2, but member(a B c d,b) will return 0.
      The case-sensitivity of MEMBER() can be worked around using the 
UCSTR(), LCSTR(), and CAPSTR() functions. These functions return a list with
all letters capitalized, all letters in lowercase, or with the first letter
of the first word of the list capitalized, respectively.

      EXTRACT() and MATCH() functions can be combined to match two lists:
  Suppose you have two registers, va and vb. The first contains a list of first
  names, and the second contains a list of last names. Given a first name, you
  want to find the last name. Assume that the first name given as input is in
  %0, and that it is in the va. Then, the matching last name will be:
  extract(v(vb),match(%va,%0),1)
  It uses the match() function to find the position of the name in the first
  name list, then uses extract() to get the word in the corresponding position
  on the last name list.

6.2   Non-standard attributes and attribute flags

      Non-standard attributes act much like V-attributes, except that they
may be arbitrarily named, as long as the names do not conflict with the names
of any existing attribute. Objects can have an unlimited number of attributes,
thus freeing the programmer from the necessity of creating multiple objects
to handle extremely complex programs.  Non-standard attributes are set using 
one of two methods:
  &<attribute name> <object>=<whatever>
  @set <object>=<attribute name>:<whatever>
1.50 also allows:  @_<attribute name> <object>=<whatever>

      Non-standard attributes may be locked (prevented from being changed
by anyone other than the person doing the locking, or a wizard), or 
chowned separately of the object. The syntax for doing this is
"@lock <object>/<attribute>"; "@unlock <object>/<attribute>" unlocks
the attribute.

      Attributes can also have flags. These are set via the command
"@set <object>/<attribute> = [!]<flag name>".  There are three flags
which may be set. The VISUAL flag makes an attribute public; anyone
can read it via the GET() function. The NO_COMMAND flag prevents an
attribute from being checked for $-commands and ^-listens. The
NO_INHERIT flag prevents an attribute from being inherited by the
children of the object.

      When you examine something, a locked attribute will have a "+"
sign next to it. Attributes such as LAST are owned and locked to God;
mortals may not change them. VISUAL attributes will be marked with "v",
NO_COMMAND attributes will be marked with "$", and NO_INHERIT attributes
will be marked with "i". 

      Certain 1.50 configurations always give the dbref of an attribute's
owner next to the attribute name; other configurations, and 2.0, only
show the attribute owner's dbref is it's different from the object's owner.

      In 1.50, the ANSI_DISPLAY flag, when set on a player, will cause
attribute names to be highlighted in boldface (if the player's terminal
supports ANSI control sequences). This is useful if you are examining a 
very large object, and need to be able to quickly and easily see where 
the breaks between attributes are.

      These attributes may be accessed via the get() and v-functions,
%-substitutions of the form %attrib do not work for user-named attributes,
as they do with @va-@vz. In all other respects, however, user-named attributes
behave like @va-@vz.

      Non-standard attributes can make MUSH code much easier to read; it
is also good practice to do a &purpose or &program register on the object
which explains a little bit of the programming, for future reference.
      One useful thing about non-standard attributes is that they are very
useful when programming objects which contain numbered registers - mail
objects, bulletin boards, etc. Instead of going through the clumsy method
of putting get(me/va) get(me/vb) get(me/vc) etc. in a register and using
extract() to force an evaluation, you can directly set registers, like:
@va object=$foo *=*:&r%0 me=%1
@vb object=$bar *:@pemit %N=get(me/r%0)
Note the use of the brackets within the get() to force register evaluation
early. The two statements above allow you to set and retrieve numbered
non-standard attributes.


6.3   Introduction to @dolist

      One very useful command is @dolist <list>=<action>. It performs
<action> for every item in the list, replacing the symbol "##" with a
word from the list. For example, @dolist [lexits(here)]="[name(##)]
will make you say the names of all exits in the room you are in.
It can be used to multi-page: @dolist Culyn RosaLil Jellan = page ## = Hello!

      @dolist evaluates its arguments in order. So, for example,
"@dolist Culyn RosaLil Jellan = page ## = Hello!"  would page Culyn,
then RosaLil, then Jellan.

      @dolist can also become rather confused by @switch statements and
semi-colons. It is best to enclose the entire <action> section of the
@dolist with braces - @dolist <list> = { <action> } 
This will prevent most errors.

      @dolist should replace most list-based loops. In the past, the
following was an efficient implementation of the problem listed above:

VA: $name-exits: @tr me/vb=[extract(lexits(here), 1, 1)], 1
VB: @switch %1=>[words(lexits(here)],{},{"[name(%0)];
     @tr me/vb=[extract(lexits(here), add(%1,1), 1)], [add(%1,1)]}
(It might be more efficient, if there are a lot of exits, to set
 @vc me=lexits(here) in the VA, but this is a small point).

Now, all that's needed is:  VA: $name-exits: @dolist [lexits(here)]="[name(##)]

      Not only is this much cleaner, but it's considerably faster than
the old method. Triggers take up quite a bit of time to execute, and
@dolist is vastly more efficient.

      One useful application of @dolist is multi-page. The following code
has been formatted for easy reading:

&PAGECOM multi-pager = $mp *=*:@emit Paging.;
  @switch pos(:,%1) = 1,
    {@dolist %0 = @switch num(*##)=#-1,
        {@emit Error: ## is not a player.},
        {@pemit *##={(To: %0) % %[v(player)] [mid(%1,1,strlen(%1))]}};
     @emit {(Sent to: %0) % %[v(player)] [mid(%1,1,strlen(%1))]}},
    {@dolist %0=@switch num(*##)=#-1,
         {@emit Error: ## is not a player.},
         {@pemit *##={(To: %0) % % [v(player)] says, "%1"}};
     @emit {(You told: %0) %1}}

&PLAYER multi-pager = <Your name>

      To page multiple people, use "mp <list of players>=<message>"
If you begin the message with a ":", it is done as a page-pose.
The command checks to see if the person you are paging is a player; if not,
it emits an error message. Otherwise, it sends the person the message as
a @pemit. It uses the MID()/STRLEN() combination to extract out the ":" from
poses. This code should be, for the most part, self-explanatory.


6.4   Applications of @dolist

      This entire section is outdated, dating from the era when @dolist
evaluated its arguments backwards. The discussion has been left intact,
for use as a general example of how to get around odd evaluation problems.
Rewriting this code to use a forward-evaluated @dolist is left as an
exercise for the reader. If you are not already comfortable with reading
MUSHcode, you will probably want to skip this section. Also, this code
doesn't demonstrate the best or the easiest ways to do things; if you
wish to create an object like the one described below, you are best off
using other methods. Several interesting MUSHcoding principles are 
illustrated here, nonetheless.

      The (old) backwards evaluation of @dolist arguments presented some minor
programming problems. Often, loops in MUSH programming involve EXTRACT()'ing
some element from a list. The list is often pre-set, created at an earlier
time by another command on the object.
      There are two obvious ways to handle this problem. The first is to
create the list backwards, and manipulate functions to do the correct thing.
The second is to reverse the list at execution time.

      Reversing a list is not difficult, but it isn't the most efficient
of things to do. The code for this is quite simple. Assuming that the
original list is in OLDLIST and the reversed list should be in NEWLIST,
&REVERSE object = $reverse: @dolist [v(oldlist)] = &NEWLIST me=[v(newlist)] ##
(Under the newer versions of MUSH code, there's an even easier way to do
 this: use the REVWORDS() function, which reverses the elements in a list).

      The first method is explained below, using the example of a notepad.
The notepad is a fairly simple device, intended for use by one person. It
keeps track of notes, complete with time-stamp and subject line.

      The notepad uses a variable called "TOP-ID", the total number of
messages written. Each note that is written is assigned the value of TOP-ID
and that variable is incremented, ensuring that the note has a unique
message ID. The list of ID numbers is kept in a list called MESS-LIST. The
EXTRACT() function is used to get the correct messages, in chronological
order, so the user never needs to see message IDs.

&TOP-ID Notepad=0
&NUM-MESS Notepad=0

&NOTE Notepad = $note *=*:
  &TOP-ID me=add(v(top-id),1);
  &NUM-MESS me=add(v(num-mess),1);
  @tr me/note2={%0},{%1}

&NOTE2 Notepad = 
  &S[v(top-id)] me=[time()]: %0;
  &M[v(top-id)] me=Text: %1;
  &MESS-LIST me=[v(top-id)] [v(mess-list)];
  @emit You stuff a note into your belt pouch.

These two commands are used for writing the actual notes. Note that
the MESS-LIST is created backwards, with the newest message at the
head of the list.

&QUICKSCAN Notepad=$scan:@switch v(num-mess)=0,{@emit You have no
notes.},1,{@emit You have one note.},{@emit You have [v(num-mess)] notes.}

This command is simple: by typing "scan" the user is shown the total
number of messages on the notepad.

A more complex command follows: "scan <message number or "all">".
This will show the subject lines of notes.

&SCAN Notepad = $scan *:
  @switch v(num-mess) = 0,
     {@emit You have no notes.},
      {@switch %0 = a*,
          {@tr me/scan-all;@emit You have [v(num-mess)] notes.},
          {@switch %0 = >[v(num-mess)], {@emit Note #%0 does not exist.},
                        0, {@emit Note #%0 does not exist.},
              {@tr me/scan-one = %0,
                 [extract(v(mess-list),sub(words(v(mess-list) xx),%0),1)]}}

That truly horrible last line is what's required to extract out a specific
message, since MESS-LIST is backwards. The first and last arguments to
the EXTRACT() are simple - they say, "take from the variable MESS-LIST
one word."  The second function means: subtract from (one plus the total 
length of the MESS-LIST) the (number of the message the user wants to read).
The "xx" is there because it's simpler than adding one to the WORDS() count.
Adding is one is necessary, or the subtract function will return 0 for the
last message, for example.

&SCAN-ONE Notepad = 
  @emit Note #%0:;
  @emit get(me/s%1)

Once the ID number is found, though, the actual printing out of the 
subject line is simple.

&SCAN-ALL Notepad = @dolist xx [v(mess-list)] =
  {@switch ##=xx,
     {@emit End of notes.},
     {@emit 
   Note #[sub(words(v(mess-list) xx),member(v(mess-list),##))]: [get(me/s##)]}}

The reason for the subtract function in this command is similar to the
reasons given above - it's needed because the list is backwards. Once
again, xx is used in the function because it's more efficient than using
ADD(). Note that "xx" is used in the @dolist as a delimiter - a signal
to stop. Because @dolist evaluates the list backwards, the delimiter must
be the first item in the list.

The "read" functions are similar to the "scan" functions, except they
show messages as well as subjects. These functions and the "erase"
functions below have been left unformatted, since the code is similar.

&READ Notepad=$rn *:@switch v(num=mess)=0,{@emit You have no notes.},{@switch
%0=a*,{@tr me/read-all;@emit You have [v(num-mess)] notes.;@emit
--------------------------------},{@switch %0=>[v(num-mess)],{@emit Note #%0
does not exist.},0,{@emit Note #%0 does not exist.},{@tr
me/read-one=%0,[extract(v(mess-list),sub(words(v(mess-list) xx),%0),1)]}}}

&READ-ONE Notepad=@emit Note #%0:;@emit get(me/s%1);@emit get(me/m%1)
@VA Notepad=@dolist [v(vb)]=:[extract(##,wordpos(v(vb),##),1)]

&READ-ALL Notepad=@dolist xx [v(mess-list)]={@switch ##=xx,{@emit End of
notes.},{@emit Note #[sub(words(v(mess-list)
xx),member(v(mess-list),##))]:;@emit get(me/s##);@emit get(me/m##);@emit
--------------------------------}}

The "erase" functions also follow the same programming logic. Here, it
becomes obvious why a message ID is used instead of straight message numbers.
It is much easier to extract out an ID than it is to recursively copy each
message up (as would be the case if you had messages 1 through 5, and
removed message 1 - you would have to move each message up one number.
Using the message ID, you merely have to remove the ID from the list and
reduce the counter of total messages).

&ERASE Notepad=$junk *:@switch v(num-mess)=0,{@emit You have no notes to
junk.},{@switch %0=a*,{@emit Junking notes. One moment please...;@tr
me/erase-all},{@switch %0=>[v(num-mess)],{@emit Note #%0 does not
exist.},0,{@emit Note #%0 does not exist.},{@tr
me/erase-one=%0,[extract(v(mess-list),sub(words(v(mess-list) xx),%0),1)]}}}

&ERASE-ONE Notepad=&S%1 me= ;&M%1 me= ;&MESS-LIST
me=remove(v(mess-list),%1);&NUM-MESS me=sub(v(num-mess),1);@emit Note #%0
junked.

&ERASE-ALL Notepad=@dolist xx [v(mess-list)]={@switch ##=xx,{&MESS-LIST me=
;&NUM-MESS me=0;@emit You junk all your notes.},{&S## me= ;&M## me= }}

This should now be a working notepad.

In 1.50 and the present versions of 2.0, this can be done in a much
cleaner manner by using LNUM(). Not having to worry about a reversed
list is also a bit of a plus.


6.5   Time synchronization

      Semaphores are a very flexible tool for the synchronization of
objects. In practical terms, they make sure things occur in a specified
order, and prevent simultaneous actions from conflicting with each other.
The name "semaphore" comes from the name for signal flags used on ships;
in modern computer systems, semaphores are used to prevent sections of
memory from being concurrently read from or written to by different
processes. Indeed, one of the main purposes of semaphores in MUSH is
preventing two things from attempting to change the same attribute at
the same time. More generally, in MUSH, semaphores are good for two
major things: preventing an already triggered object from being used again
until it has finished the action list associated with that trigger, and
preventing a command from being run until a certain other command has
executed. It is, fortunately, not necessary to completely understand how
semaphores work in order to use them.

      "Synchronized" actions are those which are correctly performed in
some specified order. Semaphores effectively delay the execution of
commands by queueing them up in the correct order, and preventing the
execution of the next command before the previous command has finished,
thus synchronizing the objects and actions. Every semaphore is associated 
with a number, called the "semaphore count", which is the number of actions
(or in the case of MUSH, action lists) it is trying to synchronizing.
Such actions are also referred to as "pending", "blocking", or "waiting" on
the semaphore.

      In MUSH, this semaphore count is stored in the SEMAPHORE attribute.
A semaphore which has no commands pending will have a count of 0. If
the semaphore count is positive, the semaphore has that many actions 
waiting on it. A negative semaphore count indicates that actions will not
block on it; for example, a count of -3 indicates that the next three
actions to wait on the semaphore will be immediately executed.
(Computer science types: please note that this is the REVERSE of the
convention generally used in operating systems theory!)

      Two operations are used to control a semaphore: wait, and notify.
"Waiting" an action list on a semaphore puts those actions at the end
of that semaphore's queue. Each time a semaphore is notified, the first
action list on its queue is executed. Thus, an action which waits on
a semaphore is delayed until the semaphore is notified. A command which
is waiting for its associated semaphore to be notified is referred to
as "blocked"; when its semaphore allows it to be executed, the command
is then "unblocked."

      Eexecuting a wait on a semaphore increases its semaphore count by
one, and executing a notify on a semaphore decreases the count by one. To
execute a wait on a semaphore, use "@wait <semaphore>=<action>"; if
<action> is a list of commands, it must be enclosed in curly braces.
To notify a semaphore, use "@notify <semaphore>". Please note that the
object that does the waiting executes the action; the semaphore is 
simply a timing device. Thus, in MUSH, you can use objects you do not
own as semaphores, if they are LINK_OK.

      Objects waiting on a semaphore run their actions on a first-come,
first-served basis, If #2, #3, and #4 execute waits, in that order, on
semaphore object #5, the first notify the semaphore receives will begin
#2's action list. The next notify will execute #3's action list, and so
on. In other words, notification of a semaphore just releases the FIRST
object which waited on it. 

      It is possible to notify a semaphore repeatedly, by providing a
numeric argument to @notify: "@notify <semaphore>=<times to notify>"
If the number of times is not specified, the semaphore will be notified
once. The semaphore executes the first <times> commands that were @waiting
on it. As a reminder, if the semaphore is notified more times than it has 
commands queued, the semaphore count will become negative and further 
@waits dependent on that semaphore will be immediately executed, until the 
semaphore count is zero. This normal @notify is shorthand for the default 
switch, "@notify/first".

      If you want all waits pending on the semaphore to execute, use 
"@notify/all <semaphore>". This will cause all the actions waiting on
the semaphore to be executed, and resets the semaphore count to 0.
The other method of clearing a semaphore is "@drain <semaphore>". This
will reset the semaphore count to 0. Actions waiting on the semaphore
are simply discarded. In 1.50, destroying an object automatically 
executes a @drain on it.

      MUSH also allows for semaphore waits to have a timeout expiration.
An object can use "@wait <semaphore>/<time in seconds>=<action>".
If <semaphore> is notified before <time> passes, the action is executed
and the semaphore count decreases by one, just as if a regular semaphore
wait were done. If <time> passes, and the action is still blocked pending
semaphore notification, it is executed anyway, and the semaphore count
on the <semaphore> is decremented by one.

      Most MUSH programmers will never use semaphores for anything more
than basic synchronization. The most common form of this is preventing
an action list associated with a trigger from being run while the action
list from a prior trigger is still executing. This is especially 
important for vending machine objects that need to work on a single
item at a time. One way of preventing this is to use an attribute BUSY;
a @switch at the beginning of trigger checking for this attribute will
tell you if the object is already trying to execute something. This,
however, can force the player to make repeated attempts to trigger the
object. A better way to do this is to associate the entire action list
of the trigger with a semaphore.

      Triggers for action lists are generally @a-actions like @apay,
or user-defined commands, like $buy. We thus set up our wait in one
of the following two forms:

@apayment object = @wait me={ @@ list of actions @@; @notify me}
&DO_COMMAND object =$command: @wait me={ @@ list of actions @@; @notify me}

      We also need to initialize the semaphore state; this is best done
by "@startup object = @drain me; @notify me".  The @drain makes sure that
we start with a clear semaphore. We need the @notify in the startup because
we don't want the first action we trigger on the object to block. The
semaphore state of the object should thus begin at -1. (When programming
your object, please remember that the very first time you use it, you will
have to @notify it.)

      In the above example, if someone tries to trigger the object before
a prior trigger has completed, the action list will block. The last command
in the prior action list is "@notify me"; this will clear the block, and
allow the next action list to begin immediate execution. This simple
technique is extremely useful for avoiding the headaches associated with
preventing concurrent attribute updates.


      The following object is a mail system. In order for it to work
correctly, it must be able to use wizard powers. It still is, however,
a fairly good example of how to use semaphores, non-standard attributes,
and @dolist. Those not presently interested in more than the basics of
MUSH programming can feel free to skip it.

      This mail system is based around an object, a fire-lizard mail
carrier. It must be picked up to be used, and is home based in a mailroom.
It creates objects as messages, and is a single unit; therefore, it takes
up much less database space than something like a mailpouch system.
Insisting that the user hold the object in order to use it was a design
decision; this is the simplest way to ensure that two people don't try
to send a message at the same time. Note that this object was written
a very long time ago, before certain useful MUSH features became
available; in the interests of providing a simple example, this "old"
coding style has been preserved in the example below. 


Description:
This is a fire-lizard mail carrier. Please pick it up before using it.
Type "send <list of players>=<subject>" to begin sending a message. Then,
enter your message, using "+" as the first character of every line. Use "++"
to send the message or "+" by itself to enter the mail editor. Editing
commands are:%r add: return to adding to message.%r clear: throw out message
and exit sending mail.%r edit string1/string2: edit message.%r proof: read
message.%rNote that Speedy can deliver messages to several players at once.
Also, if you take longer than 10 minutes to send mail, Speedy will
automatically reset himself. Dropping Speedy will also reset the mailer.

This @desc of the mail object, which will henceforth be referred to as
"Speedy", summarizes the features of the system. It supports sending to
multiple players at one time, subject lines, and messages whose lengths
are virtually unlimited. It also supports the ability to edit a message.

Several registers will be used in all the commands. The first is ACTIVITY.
This indicates what the mailer thinks it's doing at the time, and is used
to prevent the user from doing things in the wrong order. The next two
are SFIELD and MFIELD, temporary registers used to store the subject line
and the message to be sent. SENDTO is the final register, and is used to
hold the list of people to send the message to. It, too, is temporary.

The object is primed by picking it up. When the object is not being used,
and is not being held, its ACTIVITY state is "none". When it is picked
up, this is set to "idle". Picking up the object activates a semaphore
wait, with the object using itself as a timer. The timer runs out in 10
minutes - giving the user plenty of time to send a message, but not so
long that someone waiting to use the mailer might become overly annoyed -
or when the object is notified. Notification is done when the object
completes sending a message, when the user types "clear", or when the
object is dropped.

Succ:You settle Speedy on your shoulder and take out a piece of paper from the
case on its back. Type "send <list of players>=<subject>" to begin sending
mail.
Osucc:settles Speedy on %p shoulder and prepares to send some mail.
Asucc:&ACTIVITY me=idle; @wait me/600={&ACTIVITY me=none; &SFIELD me ; &MFIELD
me= ; &SENDTO me= ; @tel [v(mailroom)]; @emit The fire-lizard returns, ready to
deliver more messages.}

Drop:You release the fire-lizard.
Odrop:allows Speedy to fly off %p shoulder.
Adrop:@notify me

The WRITE attribute is used for the "send" command, which gives the mailer
the list of people to send to and the subject line, plus primes the mailer
for entering messages. It changes the ACTIVITY to "enter", sets up the
MFIELD, SFIELD, and SENDTO registers, and provides directions.
It generates error messages if the mailer is already busy, or if the
user is not holding it.
Note that SENDTO is prefixed with "xx"; this will later be used as a
delimiter for @dolist, much as "xx" was used in the earlier notepad example.

WRITE:$send *=*:@switch [v(activity)]=idle, {&ACTIVITY me=enter; &MFIELD
me=Text: ; &SFIELD me=From %N at [time()]: %1; &SENDTO me=xx
%0; @emit You may now enter your message. Start each line with a "+". Use a
"++" to send the message. Use a "+" by itself to enter the mail
editor.},none, {@pemit %#=Please pick Speedy up before attempting to send
mail.}, {@emit Working... try again later.}

The ENTERMESS attribute is used to add to the message field. The switch
to check if the user typed "++" is used to prevent a trailing "+" from
being appended when the user types "++" to send off a message. To prevent
the user from adding to the message without being in "enter" mode, but
to prevent error messages from being generated when "++", which works in
both "enter" and "edit" modes, is used, when ACTIVITY is edit, nothing
is executed.

ENTERMESS:$+*:@switch [v(activity)]=enter, {@switch %0=+,{}, {&MFIELD
me=[v(mfield)] %0}},edit,{}, {@emit You are not currently entering a
message.}

The FINISH attribute looks for "+" by itself, which is an indication to
enter the mail editor. It changes the ACTIVITY to "edit" and displays
the editing commands.

FINISH:$+:@switch [v(activity)]=enter, {&ACTIVITY me=edit; @emit Mail editor
commands:%r add: return to adding to message.%r clear: throw out message and
exit sending mail.%r edit string1/string2: edit message.%r proof: read
message.%rOr use "++" to send the mail directly.}, {@emit You are not
currently entering a message.}

The "clear" command throws out the message and returns the mail carrier
to its original state, by having it @notify itself. The commands that
were waiting for a @notify are contained in the @asucc attribute. Besides
dropping the mailer and actually sending off the message, "clear" is the
only other way to reset the mailer.

CLEAR:$clear:@switch [v(activity)]=edit, {@emit You tear up your message and
Speedy flies off.; @notify me}, {@emit You are not currently editing a
message.}

"Add" is basically just a way of returning to message-enter mode. It changes
ACTIVITY to "enter" and re-displays the instructions.

ADD:$add:@switch [v(activity)]=edit, {&ACTIVITY me=enter; @emit You return to
adding to your message. Start each line with a "+". Use a "++" to send the
message. Use "+" by itself to enter the mail editor.}, {@emit You are not
currently editing a message.}

"Proof" displays the message text that the user has entered. It may be
used in either "enter" or "edit" mode.

PROOF:$proof:@switch [v(activity)]=e*, {@emit -------------------------; @emit
[v(mfield)]; @emit -------------------------}, {@emit You are not currently
editing a message.}

"Edit" replaces one string with another. It triggers the "proof" command on
itself to show the edited message to the user. In order for this to work,
the config option "MatchOwn$Commands" must be enabled. Otherwise, simply
substitute in the relevant part of the "proof" command.

EDIT:$edit */*:@switch [v(activity)]=edit, {@edit
me/mfield={%0},{%1}; @emit You change the message to:;proof}, {@emit You
are not currently editing a message.}

The SENDMESS attribute is quite large, and does a fair number of things.
The "++" command to send the completed message can be used from either
"enter" or "edit" mode. The user is told what the final message is, and
then the mailer sets its status to "sending", which is essentially a
state which prevents the user from doing anything while the mailer is in
the process of doing a send.

A @dolist is then performed on the SENDTO attribute. Previously, when the
SENDTO was set in WRITE, it was started by the delimiter "xx"; this is
where that is used. When the delimiter is reached, the mailing has been
completed and the object does a @notify on itself, finishing the wait
on the @asucc, which clears out its temporary registers, sets its ACTIVITY 
to "none", and returns it to the mailroom.

For each name, the mailer first checks to see if the player exists, using
the num(*player) trick mentioned earlier in this manual. If the player
exists, the mailer then creates the appropriate object, sets it QUIET and
DESTROY_OK, locks it to the message originator and recipient, and sets its
@desc to the subject field. To prevent persons other than the recipient
from reading the mail, an @adesc is used to hold the actual message. The
@adesc checks to see if the person looking at the message is the recipient.
If so, it @pemits the message; if not, it returns an error.

To ensure that the mailer has time to set all the registers before it
attempts to deliver the mail, a @trigger is used to slightly delay the 
actual delivery. If this isn't used, the botched messages may be generated.

Finally, note the liberal use of braces. These are required to make sure that 
commas and semi-colons are trapped, and that all the @switch statements
work correctly. It is imperative that these braces match correctly.

SENDMESS:$++:@switch [v(activity)]=e*, {@emit You send the following
message:; @emit -------------------------; @emit [v(mfield)]; @emit
-------------------------; &ACTIVITY me=sending; @dolist [v(sendto)]={@switch
##=xx, {@notify me}, {@switch num(*##)=#-1, {@emit ## is not a player.},
{@create Fire-lizard message scroll to ##; @set Fire-lizard message scroll to
##=quiet; @set Fire-lizard message scroll to ##=destroy_ok; @lock Fire-lizard
message scroll to ##=%#|*##; @desc Fire-lizard message scroll to
##={[v(sfield)]}; @adesc Fire-lizard message scroll to ##={@switch
%%N=##, {@pemit %%#={[v(mfield)]}}, {@pemit %%#=This is not your
message!}}; @tr me/deliver=##}}}}, {@emit You have no message to send.}

The actual delivery is simple. Triggered by the @dolist, with the name
of the player to deliver the message to as its sole argument, this attribute
merely emits a delivery message to the room that the player is in, and
uses "give *player" to deliver the message. Note that "give *player" can
only be used by something that has wizard powers. This bypasses the need
for a player to be ENTER_OK in order to receive something.

DELIVER:@pemit/contents [loc(*%0)]=A fire-lizard mail carrier bursts in from
Between and delivers a message to [capstr(%0)].;give *%0=Fire-lizard message
scroll to %0

The final steps to get this mail system working are:
1. Setting a MAILROOM attribute on the object which is the room number
   of the mailroom.
2. Setting the object STICKY and linking it to the mailroom.
3. Giving it wizard powers, either through directly giving it a WIZARD
   bit, or by having a wizard own it and setting it INHERIT.
4. Setting the ACTIVITY register to "none", dropping the object, and then
   doing a "@notify/all" on it, reseting its semaphore count.

Make sure that the mailer is not locked, since it must be picked up
in order to be used.

The system is vulnerable to @halt and @allhalt; if one of these is done,
it may be necessary to reset ACTIVITY to "none" and do a "@notify/all"
on it. Also, the STARTUP: &ACTIVITY me = none; @notify/all me
may be useful. Aside from problems that arise from the mailer being stuck
in a "limbo state", this should be a fairly reliable mail system.

This mailer demonstrates a fairly basic use of semaphores, using them as a
generic way of reseting the "busy" status of an object, by allowing the 
object to be reset either through the passage of time, or through the
action of a user.


6.6   Security problems in programming

      Although, in MUSH 1.50 and 2.0, any object that you own cannot force 
you, care should still be taken to make sure that objects are reasonable
secure. Be extremely careful not to leave control objects lying around. 
_Always_ lock them to yourself, since possessive get works in 2.0 code.
get <person>'s <object> will enable someone to take any unlocked object that
you are carrying. One simple check you can make is to put a @switch in all
commands that checks to see that the triggering object is its owner:
@switch %#=<Your dbref>,{action list},{@pemit %#=You're not my owner!}
Another secure way of doing this is to use "@lock/use" to prevent anyone
but those who pass the lock from triggering $-commands on the object.

      One common problem is carelessness with semi-colons. Unless enclosed by
curly braces { }, commands like %0 can be extremely hazardous. For
example, take the object Foo, with a @va of $foo *:@emit %0
Type "foo bar" will force the object to emit bar. 

      Under old parsers, there's a nasty trick that can be done: 
"foo bar;@destroy me" (or, for that matter, any other command). Foo will 
emit bar, and then happily blow itself up. This, obviously, is a Bad Thing.
The @va should be $foo *:@emit {%0}   This safely traps any semi-colons.
Although this kind of trick shouldn't be (easily) possible to do under the 
new parser, it should still be something to keep in mind and avoid if possible.

      Other problems involve registers that are directly set to whatever
someone types in; if this is a force, triggering the register will execute
the command. There are many variations on this; the most common is the
bulletin board-type object which has a command like "post <subject>=<message>"
and sets attributes to the subject and message, perhaps like this:
$post *=*: &SUBJ_[secs()] me={From %N: %0}; &MSG_[secs()] me={%1}
	Here, the SUBJ attribute is safe, since the "From" component
prevents the placement of a $command into the attribute. The MSG, however,
is subject to something like this: "post Problem=$foo: @emit Gotcha!"
This would set something like MSG_746606174 to "$foo: @emit Gotcha!"
thus allowing any player to type "foo" and force the bulletin board
to @emit Gotcha!  This is, obviously, dangerous. This problem can
be gotten around by setting MSG to "XX %1" or something similar, and
using REST() to retrieve the message when it is needed. Never allow a
player to directly set an attribute in such a manner, even for a moment!
To do so is to invite trouble.

      A great many problems can be taken care of under INHERIT. Only objects
set INHERIT may force their owner. Objects that aren't INHERIT may not force
objects that are. If a player is set INHERIT, all of his objects are
considered to be INHERIT. This flag is reset in a @chown.
      In 2.0, INHERIT objects owned by wizards have wizard powers. Any object 
with wizard powers may force anything else, regardless of its status. This 
flag is most useful for wizards and people who own large, complex, publicly
used systems, such as mail.

      Sometimes it's useful to be able to have a non-INHERIT object force
one that is, for a single command or group of commands. Since the most common
use of this is for say/pose/emit output, in 2.0, the commands @fsay, @femit, 
and @fpose have been provided. These do the obvious. The only thing to note is
that @fpose has a switch, @fpose/nospace, which does eliminates the space
between the name of the object and its pose (making it equivalent to
player ";"). 

      There are two other notable techniques for getting around INHERIT
restrictions. Frequently, you are going to want to have a non-INHERIT
object trigger one that is; this is especially true if you are a wizard
on a 2.0 MUSH and should not, for security reasons, set objects INHERIT
unless they absolutely have to be. You can use LINK_OK as a "@trigger-ok"
flag in 1.50, but this is not possible under 2.0. Therefore, there must
be a kind of "message passing" used. 
      The first method is to uselock the object you want triggered (the
"victim") to an auxiliary object inside it, and then have the non-INHERIT
triggering object (the "actor") trigger the auxiliary, which then does
something which matches a $command on the victim. In the following example,
#88 is the auxiliary object.

&DO_ACTION actor=$test *: @trigger #88/PROPAGATE=%0
&PROPAGATE #88=do_it %0
&ACTION victim=$do_it *: @dolist %0={@set ##=dark}
@tel #88=victim
@lock/use victim=#88

      Unfortunately, the $command method is not very fast. A better
method is to use ^-patterns, and uselock the victim to the actor to
prevent spoofing. The victim should also be kept in a secure location
where it's not going to "hear" anything accidentally. The actor
@pemit's an action pattern to the victim, which acts on it.
In the following example, #90 is the victim.

&DO_ACTION actor=$test *:@pemit #90=TEST_PCODE %0
&TEST_PCODE_LISTEN #90=^TEST_PCODE *: @dolist %0={@set ##=dark}
@set #90=LISTENER  (or MONITOR, in 2.0)
@lock/use #90=actor

As long as you are careful to make sure that the victim doesn't hear
anything other than the actor, and then only when appropriate, this
is the best method for getting around INHERIT.

      The SECURE() function returns a string with all semi-colons and
braces {}  converted to spaces. This is useful if you want to prevent
people from abusing your stuff via triggers and the like.

      The ESCAPE() function inserts the escape "\" character before
all [ ], preventing the expression within from being evaluated - the string
is returned exactly as typed. An escape character is also inserted before
the first character of the string. The parser's handling of the escape
character is reliable and consistent; another less reliable character
which can act as an escape is the percent "%" character.


6.7   Debugging

      One of the things that is sadly lacking from MUSH is an easy way
to debug objects. One is often reduced to having an object say registers
out loud, or setting the object PUPPET.
      If the object is PUPPET, you will see all the output from the commands
it executes, such as "Set."  Unfortunately, in TinyMUSH 2.0, "Set." is
used to acknowledge setting attributes, flags, and miscellaneous other
things. Thus, puppet output can be rather useless (although an "I don't
see that here." or "Huh?" or similar messages can be useful in notifying
you of a typo).  1.50's output is a bit more informative; it will tell
you which object is getting set, and differentiate between attribute
sets and flag sets, enabling the PUPPET flag to be fairly useful for
debugging purposes.

      The VERBOSE flag has been provided for debugging purposes. It
displays the commands getting executed, which is useful for checking
evaluation order and the like.
      In 2.0, it displays all commands executed by the object to the 
object's owner, in the format <object name>] <command>. The output can be 
slightly messy, especially if @switches are involved. When it goes to 
evaluate the switch, it will display the entire switch statement; it will 
then show the entire branch of commands and then go to execute them.
      In 1.50, the VERBOSE flag displays all commands executed by the
object to the object's owner, in the format <object dbref>] <command>.
As with the 2.0 version of this flag, this is the command _before_ it has
been interpreted by the parser. Placing a @force before the command
_might_ be useful for _debugging purposes only_, since this will parse
all the arguments, resulting in VERBOSE output which shows the final
form of the arguments to the command.

      In 1.50, there is a flag called DEBUG. Objects set DEBUG cause their
owner to be notified of the results every call to the parser that that object
makes. If used in conjunction with the VERBOSE flag, it can pinpoint
precisely which expression is being evaluated to an undesirable quantity. The
output is in the format <object dbref>! <unparsed string> => <parsed string>
      A similar flag, called TRACE, exists in 2.0.  Be forewarned, though:
using TRACE on an object can cause the MUSH to eat up huge amounts of 
memory. You might wish to check with an administrator before trying this
flag; some 2.0 MUSHes strongly discourage its use.

      One interesting thing to note about @dolist is that it evaluates
all switches on one "level" of command before executing the results of
those switches. For example, if you run the "multi-page" code given
earlier in this manual under VERBOSE, it will first check all names in
the list for player status before proceeding to execute the pages and/or
print out error messages.
      This is a quirk which is only affects the output of @dolist; in
terms of execution order, @dolist simply repeats its command sequence on
each item in the list, completing the command sequence for each item before
beginning on the next.


6.8   On the New Programming Style

      The power of MUSH has increased dramatically in the past six months.
Things that used to be difficult or slow are now fairly easy to do, mostly
through the addition of new commands and functions.

       The biggest advances are in MUSH's treat of list processing. It
is now quite simple to take a list and perform a series of functions on
it, via the function ITER() or the  1.50 command @map. These functions
"map" another function onto each element of a list, returning a list.
(The terminology comes from the LISP programming language).

       ITER() and @dolist both use the "##" token to signify replacement,
so it is fairly difficult to easily combine the two.

       1.50's @map command maps a function onto a list, placing the
new list into the MAPLIST attribute on the object executing the @map.
This makes the parser somewhat more forgiving. @map can be thought of
as a command version of the ITER() function provided by both MUSH
versions. This command, however, is rather redundant and is likely to
go away in future versions of 1.50.

        Among the more useful complex list processing functions are
SETUNION, SETINTER, and SETDIFF. These three functions return a sorted 
list from two lists. SETUNION concatenates two lists, removing duplicates.
SETINTER returns the elements that the two lists have in common. SETDIFF 
returns the elements of the first list which are not in the second.

       The SWITCH() function also enables one to do the equivalent of
@switch on a pattern, but instead of triggering an action, the SWITCH()
function returns a string.

       The final major improvement is the U() function in 2.0 (also called
UFUN() in 1.50. In 1.50, UFUN() also has a close relative, ZFUN()). This
is a "user-defined function", which generally consists of a bunch of 
functions in an attribute. The uses of U() are beyond the scope of
this manual; suffice to say that it allows one to pass arguments into
a function of one's own devising, and get a string back in return.
It is most often  used to break up complex evaluations into something more
readable, or to make a commonly used sequence of functions easily accessable.

       The increasingly popular "switchless style" of programming
eschews the actual @switch command in favor of using function evaluations
to generate a word. The object is then @forced to execute the attribute 
named that word, via the V() function.
       Concatenation is merely a matter of leaving out things such as square 
brackets [] in the appropriate places. Under 1.50, the STRCAT() function can
also be used to explicitly concatenate strings.

       A very simple example of "standard" style vs. switchless coding 
follows. Let's suppose we want an object to respond with one of three 
different, randomly selected, messages, when someone types something.

Switchless style:
&FOOBASE object=$foo:@emit [v(FOO[rand(3)])]
&FOO0 object=Zero!
&FOO1 object=One!
&FOO2 object=Two!

[ or, alternatively, you could put the @emit in each statement and leave
  it out in the main one, if you wanted to execute more complex commands. ]

      A slightly more interesting example, although not one that is
really any more complicated -- there is a "cat" object upon which you
wish to place a "pet cat" command which will get the cat to respond
with a random action:

Standard style:
&PET_CAT cat=$pet cat:@switch [rand(3)]=
              0,@emit The cat purrs when %N pets her.,
              1,@emit The kitty blinks at %N.,
              2,@emit The cat arches her back and hisses at %N.

Switchless style:
&PET_CAT cat=$pet cat:@emit [s(v(PETMSG[rand(3)]))]
&PETMSG0 cat=The cat purrs when %N pets her.
&PETMSG1 cat=The kitty blinks at %N.
&PETMSSG2 cat=The cat arches her back and hisses at %N.

      In this particular example, the "switchless" style is wasteful;
it is more efficient (as well as simpler) to use a @switch.
The switchless style is useful when you have a very complex function with
many possible outcomes, or need to run one huge batch of commands at a time,
and want to avoid use of multiple @triggers.

      The switchless style for objects like this, however, does make it
quite easy to expand upon the basic object. For example, to add more
responses to the cat, one merey has to change the "rand(3)" to, say,
"rand(10)", and then add new PETMSG attributes. It is much more difficult
to edit switches (plus, the switchless style is easier to read).

      Some caution should be exercised when programming complex objects in
the switchless style. Because "switchless" programs often involve extremely
large, complicated function, they can take quite a long time to evaluate. 
Normally, in MUSH, commands are queued, so that no one object consumes a
large chunk of time all at once. The switchless style more or less defeats
that, forcing the game to focus all its time on evaluating that one
monster function. This can contribute to server lag. One should thus
save switchless programming for those objects that really require the
speed provided by the switchless style.

      Further notes on the parser:  while it is quite consistent in 
evaluation, many programmers continue to question exactly what is needed
to accomplish certain types of evaluations.
      The '\' character is an escape character. When placed in front of
a "special" character (like brackets or percent signs), it prevents them
from being evaluated. Each escape character delays evaluation for one
pass through the parser.
      The '%' character is most often used for "percent substitutions":
%N, %r, %va, etc.  When it is not being used for that purpose, though,
it, too, acts like an escape character.
      The curly braces {}  are used to group commands. Also, in "weird"
functions which cause a second pass through the parser (such as ITER())
the curly braces are used to delimit functions that should not be 
evaluated on the first pass through the interpreter.
      The square brackets [] signal the start and end of a function
evaluation group. They can be nested, and for the purposes of concatenation
show where "normal" text ends and substitutions begin.  Square brackets
say, "Evaluate me now."  If you put square brackets into something like
a call to ITER(), you will need to escape them out.
      Note that functions such as ITER() and U() are _exceptions_ to
the parser rules; because they call the interpreter again, the behavior
of the special characters sometimes seems strange. Successfully getting
ITER() to return the correct value depends on careful use of curly braces
and escape characters.

      For further details on complex programming in this style, as well
as notes on efficiency and further parser details, consult the final 
section of this manual.


7. What to do next

7.1   Hints and tips

      This is by no means a complete guide to MUSH. The code is constantly
changing, and new features are constantly being implemented. There are far
more commands and functions available than can be covered in a manual like
this one. If you are interested in MUSH programming, you should read through
all the help files, on @-commands, functions, and flags.
      The best way to learn how to program MUSH is to do it! Find some sort
of project and work at it. If you come up with something really neat, I'd
love to hear about it - I'm especially interested in unique applications of
non-standard attributes. Besides, I like getting mail.
      The non-standard attributes available in TinyMUSH make
certain ways of doing things obsolete. Most notable is the use of extract()
and member() combined with a list containing va-vz to access the va-vz
attributes in numerical order; attributes can now be numbered a1-a10, for
example. Also, worrying about running out of registers is now a thing of
the past.
      Corrections, complaints, or congratulations are always welcome;
I can be found as Amberyl on most MU*s, or emailed at lwl@eniac.seas.upenn.edu


INDEX OF SECTION III EXAMPLES:

5.1  Wagon
5.3  Wagon controller
6.4  Multi-pager
6.5  Notepad
6.6  Mail system
6.9  Cat