--- name: "irc" section: "3tcl" platform: "linux" package: "tcllib" version: "2.0+dfsg-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/irc/3tcl" --- # irc(3tcl) Create IRC connection and interface. ``` ``` ## NAME irc - Create IRC connection and interface. ## SYNOPSIS package require **Tcl 8.6 9** package require **irc ?0.8.0?** **::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 communication. - **::irc::config** ?key? ?value? Sets configuration ?key? to ?value?. The configuration keys currently defined are the boolean flags **logger** and **debug**. **logger** makes **irc** use the logger package for printing error. **debug** requires **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 network 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 specify 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-editor.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 signals an End of File condition. The events **defaultcmd**, **defaultnumeric**, **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. Otherwise 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 connected to a server. - *net* **sockname** Returns a 3 element list consisting of the ip address, the hostname, and the port of the local end of the connection, if currently connected. - *net* **peername** Returns a 3 element list consisting of the ip address, the hostname, and the port of the remote end of the connection, if currently 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 description 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 particular 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 begin 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 another user, in which case their nick is used. - *net* **notice** *target* *message* Sends a **notice** with message *message* to *target*, which can be either 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 channel, 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 information. ## CALLBACK COMMANDS These commands can be used within callbacks - **who** ?**address**? Returns the nick of the user who performed a command. The optional 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 particular 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 output 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