34
34
=head1 PREPACKAGED EXTENSIONS
36
This section describes the extensions delivered with this release. You can
37
find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
36
A number of extensions are delivered with this release. You can find them
37
in F<< <libdir>/urxvt/perl/ >>, and the documentation can be viewed using
38
F<< man urxvt-<EXTENSIONNAME> >>.
39
40
You can activate them like this:
41
@@RXVT_NAME@@ -pe <extensionname>
42
urxvt -pe <extensionname>
43
44
Or by adding them to the resource for extensions loaded by default:
45
46
URxvt.perl-ext-common: default,selection-autotransform
49
=item selection (enabled by default)
51
(More) intelligent selection. This extension tries to be more intelligent
52
when the user extends selections (double-click and further clicks). Right
53
now, it tries to select words, urls and complete shell-quoted
54
arguments, which is very convenient, too, if your F<ls> supports
55
C<--quoting-style=shell>.
57
A double-click usually selects the word under the cursor, further clicks
58
will enlarge the selection.
60
The selection works by trying to match a number of regexes and displaying
61
them in increasing order of length. You can add your own regexes by
62
specifying resources of the form:
64
URxvt.selection.pattern-0: perl-regex
65
URxvt.selection.pattern-1: perl-regex
68
The index number (0, 1...) must not have any holes, and each regex must
69
contain at least one pair of capturing parentheses, which will be used for
70
the match. For example, the following adds a regex that matches everything
71
between two vertical bars:
73
URxvt.selection.pattern-0: \\|([^|]+)\\|
75
Another example: Programs I use often output "absolute path: " at the
76
beginning of a line when they process multiple files. The following
77
pattern matches the filename (note, there is a single space at the very
80
URxvt.selection.pattern-0: ^(/[^:]+):\
82
You can look at the source of the selection extension to see more
83
interesting uses, such as parsing a line from beginning to end.
85
This extension also offers following bindable keyboard commands:
91
Rot-13 the selection when activated. Used via keyboard trigger:
93
URxvt.keysym.C-M-r: perl:selection:rot13
97
=item option-popup (enabled by default)
99
Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
102
Other extensions can extend this popup menu by pushing a code reference
103
onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104
popup is being displayed.
106
Its sole argument is the popup menu, which can be modified. It should
107
either return nothing or a string, the initial boolean value and a code
108
reference. The string will be used as button text and the code reference
109
will be called when the toggle changes, with the new boolean value as
112
The following will add an entry C<myoption> that changes
113
C<< $self->{myoption} >>:
115
push @{ $self->{term}{option_popup_hook} }, sub {
116
("my option" => $myoption, sub { $self->{myoption} = $_[0] })
119
=item selection-popup (enabled by default)
121
Binds a popup menu to Ctrl-Button3 that lets you convert the selection
122
text into various other formats/action (such as uri unescaping, perl
123
evaluation, web-browser starting etc.), depending on content.
125
Other extensions can extend this popup menu by pushing a code reference
126
onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127
popup is being displayed.
129
Its sole argument is the popup menu, which can be modified. The selection
130
is in C<$_>, which can be used to decide whether to add something or not.
131
It should either return nothing or a string and a code reference. The
132
string will be used as button text and the code reference will be called
133
when the button gets activated and should transform C<$_>.
135
The following will add an entry C<a to b> that transforms all C<a>s in
136
the selection to C<b>s, but only if the selection currently contains any
139
push @{ $self->{term}{selection_popup_hook} }, sub {
140
/a/ ? ("a to b" => sub { s/a/b/g }
144
=item searchable-scrollback<hotkey> (enabled by default)
146
Adds regex search functionality to the scrollback buffer, triggered
147
by a hotkey (default: C<M-s>). While in search mode, normal terminal
148
input/output is suspended and a regex is displayed at the bottom of the
151
Inputting characters appends them to the regex and continues incremental
152
search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
153
search upwards/downwards in the scrollback buffer, C<End> jumps to the
154
bottom. C<Escape> leaves search mode and returns to the point where search
155
was started, while C<Enter> or C<Return> stay at the current position and
156
additionally stores the first match in the current line into the primary
157
selection if the C<Shift> modifier is active.
159
The regex defaults to "(?i)", resulting in a case-insensitive search. To
160
get a case-sensitive search you can delete this prefix using C<BackSpace>
161
or simply use an uppercase character which removes the "(?i)" prefix.
163
See L<perlre> for more info about perl regular expression syntax.
165
=item readline (enabled by default)
167
A support package that tries to make editing with readline easier. At
168
the moment, it reacts to clicking shift-left mouse button by trying to
169
move the text cursor to this position. It does so by generating as many
170
cursor-left or cursor-right keypresses as required (this only works
171
for programs that correctly support wide characters).
173
To avoid too many false positives, this is only done when:
177
=item - the tty is in ICANON state.
179
=item - the text cursor is visible.
181
=item - the primary screen is currently being displayed.
183
=item - the mouse is on the same (multi-row-) line as the text cursor.
187
The normal selection mechanism isn't disabled, so quick successive clicks
188
might interfere with selection creation in harmless ways.
190
=item selection-autotransform
192
This selection allows you to do automatic transforms on a selection
193
whenever a selection is made.
195
It works by specifying perl snippets (most useful is a single C<s///>
196
operator) that modify C<$_> as resources:
198
URxvt.selection-autotransform.0: transform
199
URxvt.selection-autotransform.1: transform
202
For example, the following will transform selections of the form
203
C<filename:number>, often seen in compiler messages, into C<vi +$filename
206
URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
208
And this example matches the same,but replaces it with vi-commands you can
209
paste directly into your (vi :) editor:
211
URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
213
Of course, this can be modified to suit your needs and your editor :)
215
To expand the example above to typical perl error messages ("XXX at
216
FILENAME line YYY."), you need a slightly more elaborate solution:
218
URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
219
URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
221
The first line tells the selection code to treat the unchanging part of
222
every error message as a selection pattern, and the second line transforms
223
the message into vi commands to load the file.
227
This transforms the terminal into a tabbar with additional terminals, that
228
is, it implements what is commonly referred to as "tabbed terminal". The topmost line
229
displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
232
Clicking a button will activate that tab. Pressing B<Shift-Left> and
233
B<Shift-Right> will switch to the tab left or right of the current one,
234
while B<Shift-Down> creates a new tab.
236
The tabbar itself can be configured similarly to a normal terminal, but
237
with a resource class of C<URxvt.tabbed>. In addition, it supports the
238
following four resources (shown with defaults):
240
URxvt.tabbed.tabbar-fg: <colour-index, default 3>
241
URxvt.tabbed.tabbar-bg: <colour-index, default 0>
242
URxvt.tabbed.tab-fg: <colour-index, default 0>
243
URxvt.tabbed.tab-bg: <colour-index, default 1>
245
See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
250
Uses per-line display filtering (C<on_line_update>) to underline text
251
matching a certain pattern and make it clickable. When clicked with the
252
mouse button specified in the C<matcher.button> resource (default 2, or
253
middle), the program specified in the C<matcher.launcher> resource
254
(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255
with the matched text as first argument. The default configuration is
256
suitable for matching URLs and launching a web browser, like the
257
former "mark-urls" extension.
259
The default pattern to match URLs can be overridden with the
260
C<matcher.pattern.0> resource, and additional patterns can be specified
261
with numbered patterns, in a manner similar to the "selection" extension.
262
The launcher can also be overridden on a per-pattern basis.
264
It is possible to activate the most recently seen match or a list of matches
265
from the keyboard. Simply bind a keysym to "perl:matcher:last" or
266
"perl:matcher:list" as seen in the example below.
268
Example configuration:
270
URxvt.perl-ext: default,matcher
271
URxvt.urlLauncher: sensible-browser
272
URxvt.keysym.C-Delete: perl:matcher:last
273
URxvt.keysym.M-Delete: perl:matcher:list
274
URxvt.matcher.button: 1
275
URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
276
URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
277
URxvt.matcher.launcher.2: gvim +$2 $1
281
This (experimental) perl extension implements OnTheSpot editing. It does
282
not work perfectly, and some input methods don't seem to work well with
283
OnTheSpot editing in general, but it seems to work at least for SCIM and
286
You enable it by specifying this extension and a preedit style of
289
@@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
293
A very primitive quake-console-like extension. It was inspired by a
294
description of how the programs C<kuake> and C<yakuake> work: Whenever the
295
user presses a global accelerator key (by default C<F10>), the terminal
296
will show or hide itself. Another press of the accelerator key will hide
299
Initially, the window will not be shown when using this extension.
301
This is useful if you need a single terminal that is not using any desktop
302
space most of the time but is quickly available at the press of a key.
304
The accelerator key is grabbed regardless of any modifiers, so this
305
extension will actually grab a physical key just for this function.
307
If you want a quake-like animation, tell your window manager to do so
312
This extension implements some OSC commands to display timed popups on the
313
screen - useful for status displays from within scripts. You have to read
314
the sources for more info.
316
=item block-graphics-to-ascii
318
A not very useful example of filtering all text output to the terminal
319
by replacing all line-drawing characters (U+2500 .. U+259F) by a
320
similar-looking ascii character.
324
Displays a digital clock using the built-in overlay.
326
=item remote-clipboard
328
Somewhat of a misnomer, this extension adds two menu entries to the
329
selection popup that allows one to run external commands to store the
330
selection somewhere and fetch it again.
332
We use it to implement a "distributed selection mechanism", which just
333
means that one command uploads the file to a remote server, and another
336
The commands can be set using the C<URxvt.remote-selection.store> and
337
C<URxvt.remote-selection.fetch> resources. The first should read the
338
selection to store from STDIN (always in UTF-8), the second should provide
339
the selection data on STDOUT (also in UTF-8).
341
The defaults (which are likely useless to you) use rsh and cat:
343
URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
344
URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
346
=item selection-pastebin
348
This is a little rarely useful extension that uploads the selection as
349
textfile to a remote site (or does other things). (The implementation is
350
not currently secure for use in a multiuser environment as it writes to
353
It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
356
URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
358
Pressing this combination runs a command with C<%> replaced by the name of
359
the textfile. This command can be set via a resource:
361
URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
363
And the default is likely not useful to anybody but the few people around
366
The name of the textfile is the hex encoded md5 sum of the selection, so
367
the same content should lead to the same filename.
369
After a successful upload the selection will be replaced by the text given
370
in the C<selection-pastebin-url> resource (again, the % is the placeholder
373
URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
375
I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
376
the double C</> characters as comment start. Use C<\057\057> instead,
377
which works regardless of whether xrdb is used to parse the resource file
380
=item macosx-clipboard and macosx-clipboard-native
382
These two modules implement an extended clipboard for Mac OS X. They are
385
URxvt.perl-ext-common: default,macosx-clipboard
386
URxvt.keysym.M-c: perl:macosx-clipboard:copy
387
URxvt.keysym.M-v: perl:macosx-clipboard:paste
389
The difference between them is that the native variant requires a
390
perl from apple's devkit or so, and C<macosx-clipboard> requires the
391
C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
394
=item example-refresh-hooks
396
Displays a very simple digital clock in the upper right corner of the
397
window. Illustrates overwriting the refresh callbacks to create your own
402
Displays a confirmation dialog when a paste containing at least a full
407
Runs the command specified by the C<URxvt.bell-command> resource when
408
a bell event occurs. For example, the following pops up a notification
409
bubble with the text "Beep, Beep" using notify-send:
411
URxvt.bell-command: notify-send "Beep, Beep"
48
Extensions that add command line parameters or resources on their own are
49
loaded automatically when used.
415
51
=head1 API DOCUMENTATION
1154
826
bless \shift, urxvt::destroy_hook::
829
=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
831
Dynamically enable the given hooks (named without the C<on_> prefix) for
832
this extension, replacing any previous hook. This is useful when you want
833
to overwrite time-critical hooks only temporarily.
835
To install additional callbacks for the same hook, you can use the C<on>
836
method of the C<urxvt::term> class.
838
=item $self->disable ($hook_name[, $hook_name..])
840
Dynamically disable the given hooks.
845
my ($self, %hook) = @_;
846
my $pkg = $self->{_pkg};
848
while (my ($name, $cb) = each %hook) {
849
my $htype = $HOOKTYPE{uc $name};
851
or Carp::croak "unsupported hook type '$name'";
853
$self->set_should_invoke ($htype, +1)
854
unless exists $self->{term}{_hook}[$htype]{$pkg};
856
$self->{term}{_hook}[$htype]{$pkg} = $cb;
861
my ($self, @hook) = @_;
862
my $pkg = $self->{_pkg};
864
for my $name (@hook) {
865
my $htype = $HOOKTYPE{uc $name};
867
or Carp::croak "unsupported hook type '$name'";
869
$self->set_should_invoke ($htype, -1)
870
if delete $self->{term}{_hook}[$htype]{$pkg};
874
=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
876
Similar to the C<enable> enable, but installs additional callbacks for
877
the given hook(s) (that is, it doesn't replace existing callbacks), and
878
returns a guard object. When the guard object is destroyed the callbacks
883
sub urxvt::extension::on_disable::DESTROY {
886
my $term = delete $disable->{""};
888
while (my ($htype, $id) = each %$disable) {
889
delete $term->{_hook}[$htype]{$id};
890
$term->set_should_invoke ($htype, -1);
895
my ($self, %hook) = @_;
897
my $term = $self->{term};
899
my %disable = ( "" => $term );
901
while (my ($name, $cb) = each %hook) {
902
my $htype = $HOOKTYPE{uc $name};
904
or Carp::croak "unsupported hook type '$name'";
906
$term->set_should_invoke ($htype, +1);
907
$term->{_hook}[$htype]{ $disable{$htype} = $cb+0 }
908
= sub { shift; $cb->($self, @_) }; # very ugly indeed
911
bless \%disable, "urxvt::extension::on_disable"
914
=item $self->x_resource ($pattern)
916
=item $self->x_resource_boolean ($pattern)
918
These methods support an additional C<%> prefix when called on an
919
extension object - see the description of these methods in the
920
C<urxvt::term> class for details.
925
my ($self, $name) = @_;
926
$name =~ s/^%(\.|$)/$_[0]{_name}$1/;
927
$self->{term}->x_resource ($name)
930
sub x_resource_boolean {
931
my ($self, $name) = @_;
932
$name =~ s/^%(\.|$)/$_[0]{_name}$1/;
933
$self->{term}->x_resource_boolean ($name)
1157
940
package urxvt::anyevent;
1159
942
=head2 The C<urxvt::anyevent> Class