1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin irc n 0.6.1] 3[moddesc {Low Level Tcl IRC Interface}] 4[titledesc {Create IRC connection and interface.}] 5[category Networking] 6[require Tcl] 7[require irc [opt 0.6.1]] 8[description] 9 10This package provides low-level commands to deal with the IRC protocol 11(Internet Relay Chat) for immediate and interactive multi-cast 12communication. 13 14[para] 15 16[list_begin definitions] 17 18 19[call [cmd ::irc::config] [opt key] [opt value]] 20 21Sets configuration [opt key] to [opt value]. The configuration keys 22currently defined are the boolean flags [const logger] and [const debug]. 23[const logger] makes [package irc] use the logger package for printing 24error. [const debug] requires [const logger] and prints extra debug output. 25 26If no [opt key] or [opt value] is given the current values are returned. 27 28 29[call [cmd ::irc::connection]] 30 31The command creates a new object to deal with an IRC connection. 32Creating this IRC object does not automatically create the network 33connection. It returns a new irc namespace command which can be used 34to interact with the new IRC connection. NOTE: the old form of the 35connection command, which took a hostname and port as arguments, is 36deprecated. Use [cmd connect] instead to specify this information. 37 38 39[call [cmd ::irc::connections]] 40 41Returns a list of all the current connections that were created with 42[const connection] 43 44[list_end] 45 46[section {Per-connection Commands}] 47[para] 48 49In the following list of available connection methods [arg net] 50represents a connection command as returned by 51[cmd ::irc::connection]. 52 53[list_begin definitions] 54 55[call [arg net] [method registerevent] [arg event] [arg script]] 56 57Registers a callback handler for the specific event. Events available 58are those described in RFC 1459 59 60[uri http://www.rfc-editor.org/rfc/rfc1459.txt]. 61 62In addition, there are several other events defined. 63 64[const defaultcmd] adds a command that is called if no other callback 65is present. [const EOF] is called if the connection signals an End of 66File condition. The events [const defaultcmd], [const defaultnumeric], 67and [const defaultevent] are required. 68 69[arg script] is executed in the connection namespace, which can take 70advantage of several commands (see [sectref {Callback Commands}] 71below) to aid in the parsing of data. 72 73 74[call [arg net] [method getevent] [arg event] [arg script]] 75 76Returns the current handler for the event if one exists. Otherwise an 77empty string is returned. 78 79 80[call [arg net] [method eventexists] [arg event] [arg script]] 81 82Returns a boolean value indicating the existence of the event handler. 83 84 85[call [arg net] [method connect] [arg hostname] [opt port]] 86 87This causes the socket to be established. [cmd ::irc::connection] 88created the namespace and the commands to be used, but did not 89actually open the socket. This is done here. NOTE: the older form of 90'connect' did not require the user to specify a hostname and port, 91which were specified with 'connection'. That form is deprecated. 92 93[call [arg net] [method config] [opt key] [opt value]] 94 95The same as [cmd ::irc::config] but sets and gets options for the [arg net] 96connection only. 97 98[call [arg net] [method log] [arg level] [arg message]] 99 100If logger is turned on by [method config] this will write a log [arg message] 101at [arg level]. 102 103[call [arg net] [method logname]] 104 105Returns the name of the logger instance if logger is turned on. 106 107[call [arg net] [method connected]] 108 109Returns a boolean value indicating if this connection is connected to a server. 110 111 112[call [arg net] [method sockname]] 113 114Returns a 3 element list consisting of the ip address, the hostname, and the port 115of the local end of the connection, if currently connected. 116 117 118[call [arg net] [method peername]] 119 120Returns a 3 element list consisting of the ip address, the hostname, and the port 121of the remote end of the connection, if currently connected. 122 123 124[call [arg net] [method socket]] 125 126Return the Tcl channel for the socket used by the connection. 127 128[call [arg net] [method user] [arg username] [arg localhostname] [arg localdomainname] [arg userinfo]] 129 130Sends USER command to server. [arg username] is the username you want 131to appear. [arg localhostname] is the host portion of your hostname, [arg localdomainname] 132is your domain name, and [arg userinfo] is a short description of who you are. The 2nd and 3rd 133arguments are normally ignored by the IRC server. 134 135 136[call [arg net] [method nick] [arg nick]] 137 138NICK command. [arg nick] is the nickname you wish to use for the 139particular connection. 140 141 142[call [arg net] [method ping] [arg target]] 143 144Send a CTCP PING to [arg target]. 145 146 147[call [arg net] [method serverping]] 148 149PING the server. 150 151 152[call [arg net] [method join] [arg channel] [opt [arg key]]] 153 154[arg channel] is the IRC channel to join. IRC channels typically 155begin with a hashmark ("#") or ampersand ("&"). 156 157 158[call [arg net] [method part] [arg channel] [opt [arg message]]] 159 160Makes the client leave [arg channel]. Some networks may support the optional 161argument [arg message] 162 163[call [arg net] [method quit] [opt [arg message]]] 164 165Instructs the IRC server to close the current connection. The package 166will use a generic default if no [arg message] was specified. 167 168 169[call [arg net] [method privmsg] [arg target] [arg message]] 170 171Sends [arg message] to [arg target], which can be either a channel, or 172another user, in which case their nick is used. 173 174 175[call [arg net] [method notice] [arg target] [arg message]] 176 177Sends a [const notice] with message [arg message] to [arg target], 178which can be either a channel, or another user, in which case their nick is used. 179 180 181[call [arg net] [method ctcp] [arg target] [arg message]] 182 183Sends a CTCP of type [arg message] to [arg target] 184 185 186[call [arg net] [method kick] [arg channel] [arg target] [opt [arg message]]] 187 188Kicks the user [arg target] from the channel [arg channel] with a [arg message]. 189The latter can be left out. 190 191 192[call [arg net] [method mode] [arg target] [arg args]] 193 194Sets the mode [arg args] on the target [arg target]. [arg target] may be a channel, 195a channel user, or yourself. 196 197 198[call [arg net] [method topic] [arg channel] [arg message]] 199 200Sets the topic on [arg channel] to [arg message] specifying an empty string 201will remove the topic. 202 203 204[call [arg net] [method invite] [arg channel] [arg target]] 205 206Invites [arg target] to join the channel [arg channel] 207 208 209[call [arg net] [method send] [arg text]] 210 211Sends [arg text] to the IRC server. 212 213 214[call [arg net] [method destroy]] 215 216Deletes the connection and its associated namespace and information. 217 218[list_end] 219 220[section {Callback Commands}] 221[para] 222 223These commands can be used within callbacks 224 225[list_begin definitions] 226 227[call [cmd who] [opt [const address]]] 228 229Returns the nick of the user who performed a command. The optional 230keyword [const address] causes the command to return the user in the 231format "username@address". 232 233[call [cmd action]] 234 235Returns the action performed, such as KICK, PRIVMSG, MODE, etc... 236Normally not useful, as callbacks are bound to a particular event. 237 238[call [cmd target]] 239 240Returns the target of a particular command, such as the channel or 241user to whom a PRIVMSG is sent. 242 243[call [cmd additional]] 244 245Returns a list of any additional arguments after the target. 246 247[call [cmd header]] 248 249Returns the entire event header (everything up to the :) as a proper list. 250 251[call [cmd msg]] 252 253Returns the message portion of the command (the part after the :). 254 255[list_end] 256 257[section {BUGS, IDEAS, FEEDBACK}] 258 259This document, and the package it describes, will undoubtedly contain 260bugs and other problems. 261 262Please report such in the category [emph irc] of the 263[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 264 265Please also report any ideas for enhancements you may have for either 266package and/or documentation. 267 268 269[see_also {rfc 1459}] 270[keywords irc chat] 271[manpage_end] 272