IRCTK-EXT-SDK(n)

💅 IRCTK-EXT-SDK — the n manual page, bestie edition

okay so you found the IRCTk extension SDK page, and honestly? it's a slay. this is the n manpage, and i'm gonna walk you through literally all of it, no cap, nothing skipped. 🫶

---

✨ NAME ✨

irctk-ext-sdk — the tcl software development kit for irctk extensions 💖

---

🌸 SYNOPSIS 🌸

::irctk::filter type [callback]

::irctk::init name version capabilities [callback]

::irctk::ircsend net chan cmd line

::irctk::loop

---

🦋 DESCRIPTION 🦋

The IRCTk extensions SDK is a tcl package and its whole personality is "make writing IRCTk extensions in TCL easier." that's the vibe. that's the mission. 💜

So here's the tea: the subsystem calls any callback you define in your extension and hands it a message as an argument. every callback call looks exactly like this:

callback msg

Messages passed to a callback are tcl dictionaries, and the fields inside them change depending on the type. the "irc" message type has these fields:

• id — the Message Id.
• type — the Message type.
• timestamp — timestamp of the message, in seconds, from the epoch.
• cid — the id of the channel in IRCTk.
• nick — the nick of the user that sent the message.
• level — message level, from "info" to "mention."
• focus — true or false. defines if the application window is on focus.
• status — the client user's status. might be "away" or not.
• network — the network name.
• channel — the channel name.
• tags — a list of IRCv3 tags.
• command — the IRC command.
• args — the command arguments.

Fields for the "plumb" message are:

• id — message Id (EMPTY).
• type — the message type.
• cid — the Id of the channel where the plumb happened.
• network — the network name.
• channel — the channel name.
• data — the text string.

::irctk::init initializes the subsystem and does the initial handshake with IRCTk, using name and version as the extension's parameters. the capabilities argument is a list of IRCv3 capabilities your extension is able to manage, and IRCTk will ask the server to enable them. the optional callback — if you actually provide it — handles all the messages routed to the extension that don't have a proper filter in place. very "default handler main character energy." 👑

::irctk::filter defines a new policy for IRCTk to follow regarding your extension. specifically, it tells IRCTk to route only certain message types, or certain message commands, to the extension itself. the optional callback gets called by the sdk whenever a message of the specified type arrives. the possible message types are:

• plumb
• irc

And for the irc type, you can also set filters for specific commands — first fire off a filter request for the irc type, then fire off requests for the commands themselves, like this:

::irctk::filter irc
::irctk::filter JOIN "callback"
::irctk::filter PRIVMSG "callback"

If you issue a request only for the irc type, like so:

::irctk::filter irc "callback"

then IRCTk routes all the messages of type irc to your extension. all of them. every last one. 💀

The ::irc::loop command starts the main extension loop. essentially it starts the tcl event loop, processes incoming messages, and routes them to the appropriate callback for the required filters — or uses the default handler if the message type doesn't have a filter specified. 🔥

And yeah, of course your extension can add its own events to the event loop, because the sdk only handles starting the standard tcl one. an example might be an extension that opens a socket and binds a read event to grab some data from it. 🧚

The ::irctk::ircsend command sends a message of type IRC to IRCTk, where net is the destination network, chan is the specific channel, cmd is the IRC command, and line is a string for the given command.

⚠️ heads up bestie: sending an irc message to a channel that doesn't exist in the specified network makes IRCTk create a so-called "read only" channel — the body of the message gets visualized, but the user has no way to interact with the channel itself. absolutely no cap.

This is useful when, for example, you want to build extensions that don't need to send messages to an IRC server but only want to show information to the client's user. cute, right? 🌈

---

🎀 ENVIRONMENT 🎀

• IRCTK_TCL_SDK — path to the SDk source file.
• IRCTK_LOGS_PATH — path to the IRCTk chat logs directory.

---

⭐ EXAMPLES ⭐

Here's a basic "Hello, world!" extension showing the general layout, and yes it's iconic:

#!/usr/bin/env tclsh8.6

source $::env(IRCTK_TCL_SDK)

set name "Hello"
set version 1.0.0

proc helloworld {msg} {
     set network [dict get $msg network]
     set channel [dict get $msg channel]

     ::irctk::ircsend $network $channel PRIVMSG "Hello world!"
}

::irctk::init $name $version {}
::irctk::filter irc {}
::irctk::filter hello helloworld

::irctk::loop

---

🌟 SEE ALSO 🌟

irctk-extensions(7) — go read it, iykyk 🦋

---

👑 AUTHORS 👑

Andrea Biscuola <a@abiscuola.com> — an absolute legend, fr fr 💖

---

okay that's the whole page, nothing left out, we ate and left no crumbs. 🍓 this whole thing comes from OpenBSD 7.5 and it's dated May 20, 2024 — mwah, bye bestie! 💅✨