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