IRCTK-EXT-SDK(n) - LOCAL

NAME

irctk-ext-sdk - 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 designed to simplify the creation of IRCTk extensions in TCL.

The subsystem calls any callback defined in the extension with a message as an argument to it. A call to a callback have the following form:

callback msg

Messages passed to a callback are tcl dictionaries with different fields based on the type. The "irc" message type has the following fields:

Message Id.

type

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. Define if the application window is on focus.

status

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:

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 perform the initial handshake with IRCTk using name and version as the extension's parameters. The capabilities argument is a list of IRCv3 capabilities the extension is able to manage, that IRCTk will ask the server to enable. The optional callback, if provided, will handle all the messages routed to the extension without a proper filter in place.

::irctk::filter defines a new policy for IRCTk to follow, related to the extension. In particular, it informs IRCTk to route only specific message types, or specific message commands, to the extension itself. The optional callback will be called, by the sdk, whenever a message of the specified type is received. The possible message types are:

plumb
irc

As for the type irc, it's also possible to specify filters for specific commands, by first issuing a filter request for the irc type, and then by issuing a request for the commands themselves:

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

Issuing a request only for the irc type, like the following:

::irctk::filter irc "callback"

Will cause IRCTk to route all the messages of type irc to the extension.

The ::irc::loop command starts the main extension loop. In essence, it starts the tcl event loop, processing incoming messages, and routing them to the appropriate callback for the required filters, or using the default handler if the message type doesn't have a filter specified.

It's possible, of course, for an extension to add it's own events to the event loop, as the sdk just takes care of starting the standard tcl one. An example may be an extension that open a socket, binding a read event to get some data from it.

The ::irctk::ircsend command, will send a message of type IRC to IRCTk, with net as a network of destination, chan as the specific channel, cmd as the IRC command and line as a string for the given command.

Sending an irc message to a channel that doesn't exists in the specified network, will cause IRCTk to create a, so called, "read only" channel, where the body of the message will be visualized, but without any possibility for the user to interact with the channel itself.

This is useful, for example, to create extensions that doesn't need to send messages to an IRC server, but only show information to the client's user.

ENVIRONMENT

IRCTK_TCL_SDK

Path to the SDk source file.

IRCTK_LOGS_PATH

Path to the IRCTk chat logs directory.

EXAMPLES

The following is a, basic, "Hello, world!" Extension, showing the general layout:

#!/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

AUTHORS

Andrea Biscuola <a@abiscuola.com>

OpenBSD 7.8 - May 20, 2024 - IRCTK-EXT-SDK(n)

IRCTk