NAME
	msg.examples - examples on the usage of /std/msg.c

DESCRIPTION
	This document was prepared to provide explanations and examples on the
	usage of /std/msg, since the syntax might be a little hard to see
	through. The text was provided by Beldin 10:th of April 1996.

	/std/msg is a very powerful tool for the delivery of messages to
	several groups of people.
 
	The main function in /std/msg that you'll need to use is msg().  This
	is the function that your code will call when it needs to deliver a
	message. It takes between 1 and 4 arguments.
 
	The first argument is a special string processed by /std/msg.  The
	"escape character" used by this string is \b.  All of the tokens that
	/std/msg processes start with \b.  This format string is explained in
	more detail below.
 
	The second argument is the "first person".  If this argument is not
	given, it defaults to this_player().  It can be given as a single
	object, or as an array of objects.
 
	The third argument is the "second person".  It can be given as a single
	object, or as an array of objects.  You will mostly use this where one
	person (or group of people) is doing something to another person (or
	group of people).
 
	The fourth argument is the "third person".  It can be given as a single
	object, or as an array of objects.  If not given, it defaults to all
	people in the room that do not appear in the first or second person.
	You will not normally give this argument.
 
	The special string uses a number of tokens to make things more
	convenient. All of these tokens start with \b, and may have a number
	(1-3) after them to refer to a specific "person".  If that number is
	not given, 1 is assumed.
 
	  A list of the tokens follows:
	  PRON: The person that the token refers to sees "you".
	        Others see the person's name.
	  pron: The person that the token refers to sees "you".
	        Others see he/she/it.
	  OBJ:  The same as PRON, basically.
	  obj:  The person that the token refers to refers to sees "you".
	        Others see him/her/it.
	  POSS: The person that the token refers to refers to sees "your".
	        Others see "'s".
	  poss: The person that the token refers to refers to sees "your".
	        Others see his/hers/its.
	  {a,b} The person that the token refers to sees a.  Others see b.
	  $:    This is used when you need an 's' on the end of a word for all
	        but the person that the token refers to.
	        This is the same as {,s}
	  is:   The person that the token refers to refers to sees "are".
	        Others see "is".
	        This is the same as {are,is}
	  are:  Absolutely identical to is.
	 
	  cap   This is a special token; you put it in front of another token
		to capitalize it: capPRON, capis, capposs, etc.
 
	In addition to all these tokens, you can send completely different
	messages to first, second, and third persons, using a special token,
	\b|.
 
	If there is one \b| in the message, whatever's to the left of it will
	be used for the first person only, and the part to the right will be
	used for the second and third persons.
 
	If there are two \b| in the message, the part to the left of the first
	\b| goes to the first person.  The part in the middle of the two \b|
	goes to the second person.  The part to the right of the second \b|
	goes to the third person.
 
	If there are no tokens at all in the message, then /std/msg will simply
	print the message to the first person, and not to the second or third.
 

	_Examples_of_/std/msg_strings:_

	  "\bcapPRON smile\b$ happily.\n"
	    If the first person is a player named Ritual, he will see:
	      You smile happily.
	    Everyone else will see:
	      Ritual smiles happily.
	 
	  "\bcapPRON kick\b$ \b2PRON in the shins.\n"
	    If the first person is a player named Ritual, and the second person
	    is a player named Beldin, Ritual will see:
	      You kick Beldin in the shins.
	    Beldin will see:
	      Ritual kicks you in the shins.
	    Everyone else will see:
	      Ritual kicks Beldin in the shins.
	 
	  "\bcapPRON \bare now a Wizard.\n"
	     The first person is Ritual.
	     He sees:
	       You are now a Wizard.
	     Everyone else sees:
	       Ritual is now a Wizard.
	     "\bcapPRON \bis now a Wizard.\n" would give the exact same
	     message.
	
	  "\bcapPRON hit\b$ \b2PRON with \bposs sword.\n"
	    The first person is Ritual.  The second person is Beldin.
	    Ritual sees:
	      You hit Beldin with your sword.
	    Beldin sees:
	      Ritual hits you with his sword.
	    Everyone else sees:
	      Ritual hits Beldin with his sword.
	 
	  "\bcapPOSS sword gives off a flash of bright blue light.\n"
	     The first person is Ritual.
	     Ritual sees:
	       Your sword gives off a flash of bright blue light.
	     Everyone else sees:
	       Ritual's sword gives off a flash of bright blue light.
	  
	  "\bcapPRON slash\b{,es} \bposs wrists.  \bcappron " +
	  "\b{feel weak,looks pale}.\n"
	     The first person is Ritual.
	     Ritual sees:
	       You slash your wrists.  You feel weak.
	     Everyone else sees:
	       Ritual slashes his wrists.  He looks pale.
	 
     "You grin evilly as you stab \b2PRON with your powerful sword.\n\b|" +
     "\bPRON looks stupid as \bpron pokes at \b2PRON with \bposs tiny sword.\n"
	     The first person is Ritual.  The second person is Beldin.
	     Ritual sees:
	       You grin evilly as you stab Beldin with your powerful sword.
	     Beldin sees:
	       Ritual looks stupid as he pokes at you with his tiny sword.
	     Everyone else sees:
	       Ritual looks stupid as he pokes at Beldin with his tiny sword.
	     Note the \b| at the end of the first line.
	 
 "The earth shakes as you cast a mighty spell of healing at \b2PRON.\n\b|" +
 "You feel much better as \bPRON casts a powerful healing spell on you.\n\b|" +
 "\bPRON casts some sort of spell on \b2PRON.\n"
     The first person is Ritual.
     The second person is Beldin.
     Ritual sees:
       The earth shakes as you cast a might spell of healing at Beldin.
     Beldin sees:
       You feel much better as Ritual casts a powerful healing spell on you.
     Everyone else sees:
       Ritual casts some sort of spell on Beldin.
     Note that we don't have to use tokens like \bPRON and \b$ here in some
     places; you have enough control over the messages that you don't need to.
	 

	 _Examples_of calls_to_/std/msg:_

	   "std/msg"->msg("\bPRON smile\b$ happily.\n");
	     If this_player() is Ritual, Ritual sees:
	       You smile happily.
	     Everyone else in the room sees:
	       Ritual smiles happily.
	     Note that we don't have to give the second, third, or fourth
	     arguments in this example, because the defaults take care of it.
	 
	   "std/msg"->msg("\bPRON kick\b$ \b2PRON in the shins.\n",
	     this_player(), present("beldin", environment(this_player())));
	     If this_player() is Ritual, Ritual sees:
	       You kick Beldin in the shins.
	     Beldin sees:
	       Ritual kicks you in the shins.
	     Everyone else sees:
	       Ritual kicks Beldin in the shins.
	     Note that this will probably generate a bug if Beldin isn't in the
	     room.
	 
	   "std/msg"->msg("\bPRON \bis now a Wizard.\n",0,0,
	     users() - ({ this_player() }));
	   Here, if this_player() is Ritual, Ritual sees:
	     You are now a Wizard.
	   Everyone else in the game sees:
	     Ritual is now a Wizard.
	   The first person (the second argument to msg()) defaults to
	   this_player(). The second person (the third argument to msg())
	   defaults to ({}), an empty array. The third person is all the
	   players in the game except for this_player().

Help topics available:

booklet.doc

msg.doc

msg.examples

text.doc