# $EPIC: userhost,v 1.8 2002/02/09 20:16:21 brian Exp $
Synopsis:
   $userhost()
   $userhost(<nickname list>)

Technical:
   * When used with no arguments, this function returns the userhost of the
     person who sent the protocol command that is currently being processed,
     in the bodies of, or any aliases/functions called from the bodies of:
	/ON ACTION		/ON CHANNEL_NICK	/ON CHANNEL_SIGNOFF
	/ON CTCP		/ON CTCP_REPLY		/ON CTCP_REQUEST
	/ON DCC_CHAT		/ON DCC_REQUEST		/ON ENCRYPTED_NOTICE
	/ON ENCRYPTED_PRIVMSG	/ON EXIT		/ON FLOOD
	/ON INVITE		/ON JOIN		/ON KICK
	/ON KILL		/ON LEAVE		/ON MODE
	/ON MODE_STRIPPED	/ON MSG			/ON MSG_GROUP
	/ON NICKNAME		/ON NOTE		/ON NOTICE
	/ON PONG		/ON PUBLIC		/ON PUBLIC_MSG
	/ON PUBLIC_NOTICE	/ON PUBLIC_OTHER	/ON SIGNOFF
	/ON TOPIC		/ON WALL		/ON WALLOP
   * When used with no arguments, and in any other context than the ones
     above, the function returns the empty string.
   * If provided with an argument, it is taken as a list of space separated
     nicknames.
   * The return value is a space separated list of userhosts corresponding
     in order to the input arguments.  If the userhost of any of the input
     nicknames is not known, the literal string "<UKNOWN>@<UNKNOWN>" will
     be provided as the userhost.
   * IT IS VERY IMPORTANT TO UNDERSTAND that the client only caches the
     userhosts of users who are on the same channels as you.  This command
     can only provide the userhosts of people who are on the same channel as
     you and only in the context of the same server as you.
   * This command does not block and will never launch a server query.  All
     answers are provided out of the channel caches.  If the client does not
     have the userhost for a nickname in the cache, the "UNKNOWN" userhost
     will be returned.
   * You must use the USERHOST(2) command to look up the userhosts of 
     people who are not on the same channel as you.  You may also need to use
     the USERHOST(2) command to look up the userhosts of people who are
     on the same channel as you, if you ask before ON CHANNEL_SYNC is
     thrown for the channel.

Practical:
   Once upon a time the server didn't give the userhost when it sent messages
   to you.  When /ON was invented, userhosts weren't available and they could
   not put them in $*.  Because you can't change $* in /ONs without breaking 
   backwards compatibility (breaking people's scripts), $userhost() was 
   created to give the new userhost information to the user.

   After EPIC began caching the userhosts of people who are in the channels
   that you JOIN, $userhost() started accepting nicknames.  If you ask for
   the userhost of someone who isn't in a channel you are in, or if you ask
   before ON CHANNEL_SYNC is thrown, then you will probably get the
   "UNKNOWN" userhost.  Use the USERHOST command to ask the server for
   the userhost in these cases.

Returns:
   * When used with no arguments, the userhost of the person who sent the
     current message (if any).
   * When used with arguments, the userhost(s) of the nickname argument(s).
     This uses client-side caching; the "UNKNOWN" userhost is returned if the
     client has not cached the userhost for a nickname(s).

Examples:
   To show someone's address when they leave a channel:
      on ^leave "*" {
         echo *** $0 \($userhost()\) left channel $1
      }
      
   To show another person's address on demand (must be in same channel):
      eval echo Nuke!$userhost(Nuke) writes terrible help files.

History:
   This function originally appeared in ircII-2.1.5
   Support for nickname arguments originally appeared in EPIC4pre0.027

See Also:
   lastserver(6); who(2); userhost(2).

