URxvt Perl extensions open a world of possibilities with your terminal, and bring unique features to an already remarkably powerful terminal emulator program.

The rxvt-unicode terminal emulator – urxvt for short – is in itself a good, very configurable alternative to xterm or the GNOME Terminal. It offers some interesting features such as Unicode support – hence its name, daemon mode, Xft for font fun, ... What makes it truly phenomenal though, is its embedded Perl interpreter and exhaustive programming interface which open a world of possibilities.

1 Pre-packaged Extensions

To give you a taste of what urxvt Perl extensions can offer, here's a list of the ones which typically come bundled with it. You can find a brief description of each of them in the rxvt-unicode manual page. Most of them have manual pages:

• background
• bell-command
• block-graphics-to-ascii
• clipboard-osc
• confirm-paste
• digital-clock
• example-refresh-hooks
• keysym-list
• kuake
• macosx-clipboard
• macosx-clipboard-native
• matcher
• option-popup
• overlay-osc
• readline
• remote-clipboard
• searchable-scrollback
• selection
• selection-autotransform
• selection-pastebin
• selection-popup
• tabbed
• urxvt-popup
• xim-onthespot

Some of those are by default enabled, sometimes even with an associated keysym. Some others have to be enabled specifically, which is done by using the -pe option or the perl-ext-common resource.

2 Writing Extensions

The documentation in the urxvtperl manual page is very good. Looking at the existing examples in /usr/lib/urxvt/perl – or wherever your library directory is – is a nice source of inspiration too. In this section I will attempt to explain how I wrote the reactivity extension.

2.1 Where to Write Extension Script Files

Extension script files should be written to ~/.urxvt/ext, or wherever the perl-lib resource points to, as explained in the manual page for urxvt. If you intend to write your extension into the ~/.urxvt/ext/reactivity file, you'll need to set the perl-ext resource accordingly:

URxvt.perl-ext: reactivity

2.2 Keysyms and Extensions Offering Multiple Actions

The reactivity extension supports several actions. One way to run extensions is to associate action strings to keys in ~/.Xresources before running xrdb ~/.Xresources:

URxvt.keysym.M-m: perl:reactivity:mon
URxvt.keysym.M-c: perl:reactivity:vim
URxvt.keysym.M-0: perl:reactivity:resetfont
URxvt.keysym.M-0x002d: perl:reactivity:smallerfont
URxvt.keysym.M-0x003d: perl:reactivity:largerfont

Strings like perl:STRING are passed to the on_user_command Perl handler which you will define in your extension script file. More on the keysym resource in the urxvt manual page.

2.3 The on_user_command Perl Handler

All you need to implement in your extension script file is the on_user_command Perl handler which will be passed a $term to work with the terminal and a $cmd containing the string associated with the keysym you generated. In this example, that string can be :mon, :vim, :resetfont, [...] So a useful structure for on_user_command could be:

sub on_user_command {
    my ($term, $cmd) = @_;

    $_ = $cmd;
    if (/:mon/) {
    } elsif (/:vim/) {
    } elsif (/:resetfont/) {
    } elsif (/:smallerfont/) {
    } elsif (/:largerfont/) {
    }
    ()
}

As explained in the urxvtperl manual page, a hook must return a boolean value that should be () for reasons I haven't quite been bothered to understand.

2.4 A Tour of the Useful Things You Can Do

So far, I've talked you through the chain of events between a generated keysym and Perl code giving you access to all that urxvt can programmatically do. At this stage, the sky's the limit. Again, I'd urge you to read the urxvtperl manual page to get a grasp of all that's possible. A couple of things I like using are:

• Overlays, which are boxes bearing messages over the terminal, which I use to tell whether or not the terminal is being monitored for change. You create an overlay with e.g.:

  $term->{overlay} = $term->overlay_simple(-1, 0, "monitored");

  You can respectively show or hide it with:

  $term->{overlay}->show;
  $term->{overlay}->hide;

• Lines in the buffer, which I can retrieve with $term->line($row_number), namely $term->line($row_number)->t to get the actual string.

• Hooks, e.g. add_lines, which you can enable with a callback or disable:

  $term->enable(add_lines => \&add_lines_handler);
  $term->disable("add_lines");

  Where add_lines_handler is for instance defined as:

  sub add_lines_handler { shift->scr_bell; () }

3 References

• rxvt-unicode
• Manual page for urxvt
• Manual page for urxvtperl, a reference to the urxvt Perl API.
• Manual page for urxvt-extensions, an index of extensions typically bundled with urxvt.