irc(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

✨ irc(n) — Low Level Tcl IRC Interface ✨

okay bestie, sit down, we're learning the low-level Tcl IRC interface 💖 this is the manual page for irc(n), and yes it's giving ✨networking✨ but in a cute way I promise.

🌸 NAME 🌸

irc — make an IRC connection and an interface to go with it. That's the whole vibe. 💅

🎀 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 🦋

So like, what IS this — this package hands you the low-level commands for dealing with the IRC protocol (Internet Relay Chat) so you can do immediate and interactive multi-cast communication. Basically: group chat, but you're building the plumbing yourself. Main character energy fr. 💅

  • ::irc::config ?key? ?value? — sets the config ?key? to ?value?. The config keys that exist right now are the boolean flags logger and debug. logger makes irc use the logger package for printing error. debug needs logger and prints extra debug output. If you don't hand it a ?key? or ?value?, it returns the current values. 🫶
  • ::irc::connection — creates a brand new object to deal with an IRC connection. Important bestie: creating this IRC object does not automatically create the network connection. It returns a new irc namespace command that you use to interact with your new IRC connection. > ⚠️ NOTE: the old form of the connection command — the one that took a hostname and port as arguments — is deprecated. Use connect instead to specify that info. no cap.
  • ::irc::connections — returns a list of all the current connections that were created with connection. it's giving roster. 📋

💖 PER-CONNECTION COMMANDS 💖

In this next list of available connection methods, net represents a connection command as returned by ::irc::connection. ✨

  • net registerevent event script — registers a callback handler for that specific event. The events available are the ones described in RFC 1459 http://www.rfc-editor.org/rfc/rfc1459.txt. On top of those, there are several other events defined too: defaultcmd adds a command that gets called if no other callback is present. EOF gets called if the connection signals an End of File condition. The events defaultcmd, defaultnumeric, defaultevent, and EOF are required. The script runs in the connection namespace, which means it can take advantage of several commands (peep the Callback Commands section below) to help with parsing data. 🔥
  • net getevent event script — returns the current handler for the event if one exists. If not, you get an empty string back. 🤷
  • net eventexists event script — returns a boolean value telling you whether that event handler exists or not. vibe check ✅
  • net connect hostname ?port? — this is what actually causes the socket to be established. ::irc::connection created the namespace and the commands to be used, but it did not actually open the socket. That happens here. > ⚠️ NOTE: the older form of ´connect' did not require you to specify a hostname and port, because those were specified with 'connection'. That form is deprecated. 😭
  • net config ?key? ?value? — same as ::irc::config but it sets and gets options for the net connection only. 🎀
  • net log level message — if logger is turned on by config, this writes 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. true/false era.
  • 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 it's 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 it's currently connected. 🌍
  • net socket — returns the Tcl channel for the socket used by the connection. 🔌
  • net user username localhostname localdomainname userinfo — sends the USER command to the 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. fun fact: the 2nd and 3rd arguments are normally ignored by the IRC server. 🙈
  • net nick nick — the NICK command. nick is the nickname you wish to use for that particular connection. 👑
  • net ping target — sends a CTCP PING to target. 🏓
  • net serverping — pings the server. 🖥️
  • net join channel ?key? — channel is the IRC channel to join. IRC channels typically begin with a hashmark ("#") or an ampersand ("&"). #️⃣
  • net part channel ?message? — makes the client leave channel. Some networks may support the optional message argument. 👋
  • net quit ?message? — tells the IRC server to close the current connection. If you don't specify a message, the package uses a generic default. 🚪
  • net privmsg target message — sends message to target, which can be either a channel, or another user — in that 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 that 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 message part 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. self-care mode setting.
  • 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. 💀 rest in peace bestie

🌈 CALLBACK COMMANDS 🌈

These commands can be used inside callbacks 🫶

  • who ?address? — returns the nick of the user who performed a command. The optional keyword address makes the command return the user in the format "username@address". 🔍
  • action — returns the action performed, like KICK, PRIVMSG, MODE, etc... Normally not useful, because callbacks are bound to a particular event anyway. 🤷♀️
  • 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 🐛

Real talk bestie: this document, and the package it describes, will undoubtedly contain bugs and other problems. 😭 Please report those in the category irc of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. Also please report any ideas for enhancements you may have for either the package and/or the documentation. 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Also note further that attachments are strongly preferred over inlined patches. You can make attachments 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

and that's the whole page, bestie 💖 this one came from tcllib, version 0.8.0, and it's the irc(n) page — go build something iconic with it 🎀✨🦋🌸💅👑

📦 where this page comes from