irc(3tcl) Low Level Tcl IRC Interface irc(3tcl)
______________________________________________________________________________
NAME
irc - Create IRC connection and interface.
SYNOPSIS
package require Tcl
package require irc ?0.6.2?
::irc::config ?key? ?value?
::irc::connection
::irc::connections
net registerevent event script
net getevent event script
net eventexists event script
net connect hostname ?port?
net config ?key? ?value?
net log level message
net logname
net connected
net sockname
net peername
net socket
net user username localhostname localdomainname userinfo
net nick nick
net ping target
net serverping
net join channel ?key?
net part channel ?message?
net quit ?message?
net privmsg target message
net notice target message
net ctcp target message
net kick channel target ?message?
net mode target args
net topic channel message
net invite channel target
net send text
net destroy
who ?address?
action
target
additional
header
msg
______________________________________________________________________________
DESCRIPTION
This package provides low-level commands to deal with the IRC protocol
(Internet Relay Chat) for immediate and interactive multi-cast communi-
cation.
::irc::config ?key? ?value?
Sets configuration ?key? to ?value?. The configuration keys cur-
rently defined are the boolean flags logger and debug. logger
makes irc use the logger package for printing error. debug re-
quires logger and prints extra debug output. If no ?key? or
?value? is given the current values are returned.
::irc::connection
The command creates a new object to deal with an IRC connection.
Creating this IRC object does not automatically create the net-
work connection. It returns a new irc namespace command which
can be used to interact with the new IRC connection. NOTE: the
old form of the connection command, which took a hostname and
port as arguments, is deprecated. Use connect instead to spec-
ify this information.
::irc::connections
Returns a list of all the current connections that were created
with connection
PER-CONNECTION COMMANDS
In the following list of available connection methods net represents a
connection command as returned by ::irc::connection.
net registerevent event script
Registers a callback handler for the specific event. Events
available are those described in RFC 1459 http://www.rfc-edi-
tor.org/rfc/rfc1459.txt. In addition, there are several other
events defined. defaultcmd adds a command that is called if no
other callback is present. EOF is called if the connection sig-
nals an End of File condition. The events defaultcmd, defaultnu-
meric, defaultevent, and EOF are required. script is executed
in the connection namespace, which can take advantage of several
commands (see Callback Commands below) to aid in the parsing of
data.
net getevent event script
Returns the current handler for the event if one exists. Other-
wise an empty string is returned.
net eventexists event script
Returns a boolean value indicating the existence of the event
handler.
net connect hostname ?port?
This causes the socket to be established. ::irc::connection
created the namespace and the commands to be used, but did not
actually open the socket. This is done here. NOTE: the older
form of 'connect' did not require the user to specify a hostname
and port, which were specified with 'connection'. That form is
deprecated.
net config ?key? ?value?
The same as ::irc::config but sets and gets options for the net
connection only.
net log level message
If logger is turned on by config this will write a log message
at level.
net logname
Returns the name of the logger instance if logger is turned on.
net connected
Returns a boolean value indicating if this connection is con-
nected to a server.
net sockname
Returns a 3 element list consisting of the ip address, the host-
name, and the port of the local end of the connection, if cur-
rently connected.
net peername
Returns a 3 element list consisting of the ip address, the host-
name, and the port of the remote end of the connection, if cur-
rently connected.
net socket
Return the Tcl channel for the socket used by the connection.
net user username localhostname localdomainname userinfo
Sends USER command to server. username is the username you want
to appear. localhostname is the host portion of your hostname,
localdomainname is your domain name, and userinfo is a short de-
scription of who you are. The 2nd and 3rd arguments are normally
ignored by the IRC server.
net nick nick
NICK command. nick is the nickname you wish to use for the par-
ticular connection.
net ping target
Send a CTCP PING to target.
net serverping
PING the server.
net join channel ?key?
channel is the IRC channel to join. IRC channels typically be-
gin with a hashmark ("#") or ampersand ("&").
net part channel ?message?
Makes the client leave channel. Some networks may support the
optional argument message
net quit ?message?
Instructs the IRC server to close the current connection. The
package will use a generic default if no message was specified.
net privmsg target message
Sends message to target, which can be either a channel, or an-
other user, in which case their nick is used.
net notice target message
Sends a notice with message message to target, which can be ei-
ther a channel, or another user, in which case their nick is
used.
net ctcp target message
Sends a CTCP of type message to target
net kick channel target ?message?
Kicks the user target from the channel channel with a message.
The latter can be left out.
net mode target args
Sets the mode args on the target target. target may be a chan-
nel, a channel user, or yourself.
net topic channel message
Sets the topic on channel to message specifying an empty string
will remove the topic.
net invite channel target
Invites target to join the channel channel
net send text
Sends text to the IRC server.
net destroy
Deletes the connection and its associated namespace and informa-
tion.
CALLBACK COMMANDS
These commands can be used within callbacks
who ?address?
Returns the nick of the user who performed a command. The op-
tional keyword address causes the command to return the user in
the format "username@address".
action Returns the action performed, such as KICK, PRIVMSG, MODE,
etc... Normally not useful, as callbacks are bound to a partic-
ular event.
target Returns the target of a particular command, such as the channel
or user to whom a PRIVMSG is sent.
additional
Returns a list of any additional arguments after the target.
header Returns the entire event header (everything up to the :) as a
proper list.
msg Returns the message portion of the command (the part after the
:).
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category irc of the
Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
SEE ALSO
rfc 1459
KEYWORDS
chat, irc
CATEGORY
Networking
tcllib 0.6.2 irc(3tcl)