Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+======Synopsis:======
+__userhost__ [-direct] [-count <number>] [-extra <stuff>] [<nickname> [<nickname> ...] [-cmd <command>]]
+======Description:======
+This asks the server for the address (user@hostname) of each of the
+specified nicknames.  You may query as many nicknames as you wish,
+however the irc protocol limits any one request to 5 nicknames; the client
+will break your list into groups of 5 and request each group separately.
+If you query too many nicknames, you may flood yourself off the server.
+If you specify the **-cmd** option, then anything that follows that
+option will be taken as a [[block]] that shall be executed for each and
+every nickname in the list **IN THE SAME ORDER AS THE LIST**.  If any of
+the nicknames in the list are not on irc, a placeholder userhost will be
+passed to the -cmd block in that nickname's turn. (further described below)
+======About asynchronous behavior:======
+The traditional behavior of USERHOST was to execute the -cmd option
+asynchronously.  Asynchronous execution means that execution of code
+is postponed until the future, when the server replies to the query.
+When USERHOST behaves asynchronously, the USERHOST command simply submits
+a request for userhosts to the server and returns immediately.  The -cmd
+option will not have been executed -- not even once -- and will not be
+executed until the next time EPIC checks for data from the server.
+======About synchronous behavior:======
+However, if all of the nicknames in the list are present in the client's
+internal userhost cache, then this command behaves synchronously.  The
+-cmd option will be executed for **all** nicknames in the list **before**
+**the USERHOST command returns.**  If you do not want this behavior, you
+can use the **-direct** option to force __USERHOST__ to send the request
+to the server instead of looking in the cache.
+However, EPIC cannot cache the "away status" or "oper status" that is
+provided by a userhost request and whenever it behaves synchronously, the
+away status and oper status will be wrong.  If you need the away status or
+oper status, you should use the **-direct** option to get this information
+from the server.
+The use of the [[wait]] command arranges for synchronous behavior after
+the execution of an asynchronous command.
+======Extra data:=======
+Sometimes you want to pass extra data to the **-cmd** callback, and because
+of the asynchronous behavior of [[userhost]], it's difficult to arrange this
+without [[wait]]ing.  The [[userhost]] command supports an **-extra** flag
+that takes a variable name and saves the contents of that variable at the
+time you do the request, and then appends that value when the userhost
+callbacks are executed.  The variable is only used at the time you make the
+userhost request, so you can change it (or use a local variable) and that
+won't affect the value passed to the callbacks.
+The extra data is appended to $* in the /on 303 numeric as well.
+======Options:======
+|  -direct    |Require __userhost__ to query the server.                     |
+|  -cmd       |Pass the output from __userhost__ as input to other commands: |
+|  -count     |Maximum number of nicks EPIC will query for in every request  |
+|  -extra     |Add the contents of a variable to the callback data           |
+__USERHOST__ passes the following arguments to -cmd:
+  $0  - nickname
+  $1  - a '+' if the user is an irc operator, a '-' otherwise
+  $2  - a '+' if the user is marked as away, a '-' otherwise
+  $3  - username
+  $4  - hostname
+  $5- - The extra data, if any.
+======Examples:======
+To get the userhosts of JoeBob and Jimbo:
+      /userhost joebob jimbo
+To use their userhost output as another command's input in a script:
+      userhost joebob jimbo -cmd {
+         echo $0 is $3@$4
+         if ( [$1] == [+] ) echo $0 is an irc operator
+         if ( [$2] == [+] ) echo $1 is away
+      }
+To pass extra data to a userhost callback:
+      @ var = [This is" a compli\cat\\ed string"]
+      userhost -extra var joebob jimbo -cmd {
+         xecho -b $0 is $3@$4 ($5-)
+      }

EPIC

User Tools

Site Tools

Differences

Page Tools