picoirc(n)

💖 picoirc — the tiny embeddable IRC bestie 💖

okay so. you want IRC. in your app. but like, small. cute. minimal. no cap, that's literally what picoirc is — a small and simple embeddable IRC client, and she's giving main character energy in the smallest possible package. 🎀

---

✨ SYNOPSIS ✨

package require Tcl 8.6 9

package require picoirc ?0.14.0?

::picoirc::connect callback nick ?password? url

::picoirc::post context channel message

---

🌸 DESCRIPTION 🌸

So here's the vibe: this package hands you a general purpose, minimal IRC client that's built to be embedded inside other applications. Every single bit of communication with the parent application happens through an application-provided callback procedure — that's the whole gossip channel, bestie.

And the way each connection keeps its own state?? Obsessed. It means you can hook up multiple servers in one single application instance. multiple. servers. at once. iconic behaviour. 💅

To kick off an IRC connection you gotta call picoirc::connect with:

• a callback procedure,
• a nick-name to use on IRC, and
• the IRC URL that describes the connection.

That call returns a variable name, and that variable name is your irc connection context. (Peep the CALLBACK section below for the tea. 🫖)

Also, real talk: this package is a fairly simple IRC client. If you need something with more capability, go investigate the irc package instead. She's not mad, she's just being honest. 😭

---

👑 COMMANDS 👑

💫 ::picoirc::connect callback nick ?password? url

Creates a brand new irc connection to the server specified by url, and logs in using nick as the username, plus optionally password.

If the url starts with ircs:// then a TLS connection is created. (Secure! Locked down! We love her. 🔐)

The callback has to be exactly as specified in CALLBACK.

Returns a package-specific variable that you use when calling other commands in this package. Keep that little variable safe, she's your ticket to everything else. 🎟️

Note: for connecting via TLS, the Tcl module tls must already be loaded — otherwise an error is raised. No tls, no vibes.

# must be loaded for TLS
package require tls
# default arguments
tls::init -autoservername true -command workaround \
    -require 1 -cadir /etc/ssl/certs -tls1 0 -tls1.1 0
# avoid annoying bgerror, errors are already catched internally
proc workaround {state args} {
    if {$state == "verify"} {
        return [lindex $args 3]
    }
}

💌 ::picoirc::post context channel message

This is the one you call to process user input and yeet it off to the server.

If message is multiline, then each line gets processed and sent individually. One at a time. Patiently.

A bunch of commands get recognised when they're prefixed with a forward-slash (/). Those get converted into IRC command sequences and then sent off.

If channel is empty, then all raw output to the server is handled.

The default action is to write the message to the irc socket. BUT. Before that happens, the callback gets called with "debug write". Why? So the application author can inspect the raw IRC data, and — if they feel like it — return a break error code to halt further processing. That's how the application can override the default send via the callback procedure. You have the power, bestie. ✨

---

🦋 CALLBACK 🦋

The callback must look like this:

proc Callback {context state args} {
}

where context is the irc context variable name (in case you need to pass it back to a picoirc procedure).

state is one of a number of states, and here's the full list, no skipping, we're doing all of them:

• init — called just before the socket is created.
• connect — called once we have connected, before we join any channels. like, we're in the building but we haven't said hi to anyone yet. 🙈
• close — called when the socket gets closed, before the context is deleted. If an error occurs before we get connected, the only argument will be the socket error message.
• userlist channel nicklist — called to notify the application of an updated userlist. This gets generated when the output of the NAMES irc command is seen. The package collects the entire output — which can span a number of output lines from the server — and calls this callback when they have all been received. she waited for the full story before she spilled it. 🫶
• userinfo nick info — called as a response of the WHOIS command. nick is the user the command was targeted for. info is the dictionary containing detailed information about that user: name, host, channels and userinfo. And userinfo typically contains the name and version of the user's IRC client. snooping, but make it friendly. 🔍
• chat target nick message type — called when a message arrives. target is the identity that the message was targetted for — this can be the logged in nick or a channel name. nick is the name of the sender of the message. message is the message text. type is set to "ACTION" if the message was sent as a CTCP ACTION. type is set to "NOTICE" if the message was sent as a NOTICE command — in that case target is empty if it matches current user nick, or it's "*". in later case empty target means that notice comes from server.
• mode nick target flags — called when the mode of a user or channel changes. nick is the name of the user who requested a change — can be empty if it's the server. target is the identity that has its mode changed. flags are the changes in mode. glow-up detected. 💅
• system channel message — called when a system message is received.
• topic channel topic — called when the channel topic string is seen. topic is the text of the channel topic.
• traffic action channel nick ?newnick? — called when users join, leave or change names. action is either entered, left or nickchange, and nick is the user doing the action. newnick is the new name if action is nickchange.

NOTE: channel is often empty for these messages, as nick activities are global for the irc server. You will have to manage the nick for all connected channels yourself. yeah. that's on you, babe. 😭

• version — this is called to request a version string to use to override the internal version. If implemented, you should return a colon delimited string as:

Appname:Appversion:LibraryVersion

For example, the default is:

PicoIRC:[package provide picoirc]:Tcl [info patchlevel]

• debug type raw — called when data is either being read or written to the network socket. type is set to read when reading data, and write if the data is to be written. raw is the unprocessed IRC protocol data.

In both cases, the application can return a break error code to interrupt further processing of the raw data. If this is a read operation, then the package will not handle this line. If the operation is write, then the package will not send the data. This callback is intended for debugging protocol issues, but could be used to redirect all input and output if desired. peek behind the curtain energy. 🧚

---

🌈 SEE ALSO 🌈

• rfc 1459

---

⭐ KEYWORDS ⭐

• chat
• irc

---

🍓 CATEGORY 🍓

• Networking

---

and that's the whole page, bestie — every flag, every state, every note, all of it, fr fr. this lil' legend ships with tcllib, version 0.14.0, as page picoirc(n) — go forth and connect to every server at once, you absolute icon. 👑💖