Navigation

Contacting Juerd

Scripting Irssi 0.8.6+

Introduction

This is a very simple tutorial to get used to Irssi's Perl scripting. This is in
no way a Perl tutorial or a guide for beginning programmers. Don't expect this
tutorial to be a complete reference, and please understand that I didn't talk
about everything Irssi can do. Some Perl knowledge is required to understand
this tutorial. Only simple subjects are explained in here. To find out everything
there is to know, read existing scripts!

Learning Perl

There is no point in scripting Irssi if you don't know Perl.

If you do not already know Perl, learn it first. Perl is a very powerful language
that gets things done in a minimum amount of time. But without reading proper
documentation, the language is very hard to learn.

I recommend Beginning Perl by Simon Cozens. Wrox Press released this book for free
download, but you can also buy a paper copy.

Official Perl documentation comes bundled with Perl, but if for some reason you
do not have the perldoc utility, please refer to http://perldoc.com/ for
HTML versions of the same documentation.

Starting

Because Irssi scripts are embedded in Irssi and not executed from the console,
they do not need to be executable. A permission mode setting of 600 is enough
for scripts in your home directory, 644 is enough for system wide script
installations. The shebang line is not required, as this is only the case
for executable scripts.

You should, however, include some common things. Programming under the
strict pragma is always a very good idea, and is recommended. Irssi
scripts need to use the Irssi module to make use of the special Irssi commands.
You do want to interact with Irssi, don't you?

Irssi scripts can provide information about themselves. You should always use a
version number (recommended: a string consisting of a digit, a dot and two more
digits), and put that in the $VERSION global, which is common for
Perl scripts and modules. When scripting Irssi, another important global
arises: the hash called %IRSSI. In this hash, you define the script's name, your
name, and some information related to the script. Its format is
defined, and some header values should not be skipped.

There are more fields you can use, so have a look at the
header definition to know more.
Please note that "authors" is supposed to be plural: it's not a mistake.

Interacting with Irssi

A script would be useless if it didn't interact with Irssi. Irssi scripts should
load very fast, and the ideal situation would be where you don't have any
non-Irssi commands in your script's body. Irssi works event based, and subs are
called when events take place. Most commands that you can use to instruct Irssi
are in the Irssi:: namespace.

Irssi has two types of events: signals and commands. Signals happen anyway, and
happen all the time. There's a signal for when someone joins a channel, one for
nickchanges, etcetera. Commands are user input. You can hook subs to signals
and commands, and they will be executed when signals are emitted, or commands
executed. This is the main way of Irssi's communication with the script: Irssi
tells when a sub should be executed. To tell Irssi you want to use a signal or
command, you have to use the signal_add or command_bind function. The first
parameter is the signal or command itself, the second parameter is either the
name of the sub that should be called, or a reference to a sub. Best is to
always use references. A sub reference to your foo() sub can be made with
\&foo, but you can have a sub inlined in your code, that has no name of its
own: sub { code }.

Don't forget the semi-colon at the end. Everything you print is printed into
Irssi's scrollbuffer, and automatically line terminated: you do NOT need \n. If
you use \n, a blank line will appear. If you print using Perl's built-in print,
the CLIENTCRAP messagelevel is used. You can pick another messagelevel by using
it as if it were a Perl filehandle. When using a print method, you can add the
messagelevel as the second argument, using a MSGLEVEL_ constant.

print CRAP 'Example';
$witem->print('Example', MSGLEVEL_PUBLIC);

Of course, information is passed to your subs. They would not be very useful
without information. That information can include the current server, or
information about the signal. As with every Perl sub, the arguments are in @_,
and can be assigned to named variables using a simple list assignment.

Cleaning up

After a while, you'll notice you have Irssi:: commands all over the place, and
if you're like me, you don't like it. Fortunately, the Irssi module can export
its functions to your package. You tell it to do so by adding a list to the
use statement. I use qw() for that, which is a Perl operator that creates a
list of words separated by whitespace. qw(a b c) is just a convenient way
to write ('a', 'b', 'c').

Configurability

The larger your script gets, the more you should make it configurable. That
way, the user can use his own settings, and when users can change your script
to what they like, your script will probably have more users. Settings are
categorized, and always have defaults. It's common to use your script's name as
the category, and have a reasonable default.

Irssi has three types of settings: string, integer and boolean. Boolean
settings can be toggled, and are represented as ON and OFF to the user, but as
1 and 0 to your script, so you can use them as normal Perl boolean expressions.
To tell Irssi you want to register a certain setting, you have to use either
settings_add_str, settings_add_int or settings_add_bool.
Their first argument is the category, the second is the setting name and the
third is used to put in a default value.

To retrieve a setting, use settings_get_str, settings_get_int or
settings_get_bool with the setting name as its only argument. Don't mix data
types!

Learning more

You can do a lot more with Irssi. You can use the user's current theme to
provide output in the colors and style he or she likes, you can stop and
re-emit signals to effectively change them. I haven't discussed signals in
great detail, but they are very important. The easiest way to learn them, is by
looking at existing scripts. I encourage you to read existing scripts, and
learn from them.

Script archive

At this time, a centralized script archive exists, and it's mirrored to
irssi.org amongst other mirrors. That's where you can find existing scripts,
that are very useful when learning to script Irssi yourself. If you have
finished a script, think of how it might be useful to others, and consider
submitting it for inclusion in the archive. This also has the advantage of
automatic upgrades of your scripts, as long as you increase the version number
each time, and the user uses an automated installer.

Asking for help

Please don't contact me with questions about Irssi. I don't have the time to help
you adequately. Instead, join #irssi on IRCNet and ask your question there.

Also, please do not use my guestbook to ask Irssi questions. Both questions
and answers will be removed; it is not a forum.

Copyright

Please do not copy this document to other websites. Link instead, so your visitors
always have the latest version, and I eventually get more guestbook entries ;)

Disclaimer

If you screw up, that's your problem. If you find your computer exploding after
trying the examples provided here, that's your problem. I disclaim any
responsibility, and Irssi scripting is always at your own risk. I
promise nothing, and don't give any guarantees. This document provides
information only, and that information has never been confirmed to be correct.