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:
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
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:
2.2 Keysyms and Extensions Offering Multiple Actions
reactivity extension supports several actions. One way to run extensions is to associate action strings to keys in
~/.Xresources before running
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
:resetfont, […] So a useful structure for
on_user_command could be:
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.:
You can respectively show or hide it with:
- Lines in the buffer, which I can retrieve with
$term->line($row_number)->tto get the actual string.
add_lines, which you can enable with a callback or disable:
add_lines_handleris for instance defined as: