urxvt(3) RXVT-UNICODE urxvt(3)
NAME
urxvtperl - rxvt-unicode's embedded perl interpreter
SYNOPSIS
# create a file grab_test in $HOME:
sub on_sel_grab {
warn "you selected ", $_[0]->selection;
()
}
# start a urxvt using it:
urxvt --perl-lib $HOME -pe grab_test
DESCRIPTION
Every time a terminal object gets created, extension scripts specified via the "perl" resource are loaded and associated with it.
Scripts are compiled in a 'use strict' and 'use utf8' environment, and thus must be encoded as UTF-8.
Each script will only ever be loaded once, even in urxvtd, where scripts will be shared (but not enabled) for all terminals.
You can disable the embedded perl interpreter by setting both "perl-ext" and "perl-ext-common" resources to the empty string.
PREPACKAGED EXTENSIONS
This section describes the extensions delivered with this release. You can find them in /usr/lib64/urxvt/perl/.
You can activate them like this:
urxvt -pe <extensionname>
Or by adding them to the resource for extensions loaded by default:
URxvt.perl-ext-common: default,selection-autotransform
selection (enabled by default)
(More) intelligent selection. This extension tries to be more intelligent when the user extends selections (double-click and further
clicks). Right now, it tries to select words, urls and complete shell-quoted arguments, which is very convenient, too, if your ls
supports "--quoting-style=shell".
A double-click usually selects the word under the cursor, further clicks will enlarge the selection.
The selection works by trying to match a number of regexes and displaying them in increasing order of length. You can add your own
regexes by specifying resources of the form:
URxvt.selection.pattern-0: perl-regex
URxvt.selection.pattern-1: perl-regex
...
The index number (0, 1...) must not have any holes, and each regex must contain at least one pair of capturing parentheses, which will
be used for the match. For example, the following adds a regex that matches everything between two vertical bars:
URxvt.selection.pattern-0: \|([^|]+)\|
Another example: Programs I use often output "absolute path: " at the beginning of a line when they process multiple files. The
following pattern matches the filename (note, there is a single space at the very end):
URxvt.selection.pattern-0: ^(/[^:]+):
You can look at the source of the selection extension to see more interesting uses, such as parsing a line from beginning to end.
This extension also offers following bindable keyboard commands:
rot13
Rot-13 the selection when activated. Used via keyboard trigger:
URxvt.keysym.C-M-r: perl:selection:rot13
option-popup (enabled by default)
Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at runtime.
Other extensions can extend this popup menu by pushing a code reference onto "@{ $term-"{option_popup_hook} }>, which gets called
whenever the popup is being displayed.
Its sole argument is the popup menu, which can be modified. It should either return nothing or a string, the initial boolean value and
a code reference. The string will be used as button text and the code reference will be called when the toggle changes, with the new
boolean value as first argument.
The following will add an entry "myoption" that changes "$self->{myoption}":
push @{ $self->{term}{option_popup_hook} }, sub {
("my option" => $myoption, sub { $self->{myoption} = $_[0] })
};
selection-popup (enabled by default)
Binds a popup menu to Ctrl-Button3 that lets you convert the selection text into various other formats/action (such as uri unescaping,
perl evaluation, web-browser starting etc.), depending on content.
Other extensions can extend this popup menu by pushing a code reference onto "@{ $term-"{selection_popup_hook} }>, which gets called
whenever the popup is being displayed.
Its sole argument is the popup menu, which can be modified. The selection is in $_, which can be used to decide whether to add
something or not. It should either return nothing or a string and a code reference. The string will be used as button text and the
code reference will be called when the button gets activated and should transform $_.
The following will add an entry "a to b" that transforms all "a"s in the selection to "b"s, but only if the selection currently
contains any "a"s:
push @{ $self->{term}{selection_popup_hook} }, sub {
/a/ ? ("a to b" => sub { s/a/b/g }
: ()
};
searchable-scrollback<hotkey> (enabled by default)
Adds regex search functionality to the scrollback buffer, triggered by a hotkey (default: "M-s"). While in search mode, normal terminal
input/output is suspended and a regex is displayed at the bottom of the screen.
Inputting characters appends them to the regex and continues incremental search. "BackSpace" removes a character from the regex, "Up"
and "Down" search upwards/downwards in the scrollback buffer, "End" jumps to the bottom. "Escape" leaves search mode and returns to the
point where search was started, while "Enter" or "Return" stay at the current position and additionally stores the first match in the
current line into the primary selection if the "Shift" modifier is active.
The regex defaults to "(?i)", resulting in a case-insensitive search. To get a case-sensitive search you can delete this prefix using
"BackSpace" or simply use an uppercase character which removes the "(?i)" prefix.
See perlre for more info about perl regular expression syntax.
readline (enabled by default)
A support package that tries to make editing with readline easier. At the moment, it reacts to clicking shift-left mouse button by
trying to move the text cursor to this position. It does so by generating as many cursor-left or cursor-right keypresses as required
(this only works for programs that correctly support wide characters).
To avoid too many false positives, this is only done when:
- the tty is in ICANON state.
- the text cursor is visible.
- the primary screen is currently being displayed.
- the mouse is on the same (multi-row-) line as the text cursor.
The normal selection mechanism isn't disabled, so quick successive clicks might interfere with selection creation in harmless ways.
selection-autotransform
This selection allows you to do automatic transforms on a selection whenever a selection is made.
It works by specifying perl snippets (most useful is a single "s///" operator) that modify $_ as resources:
URxvt.selection-autotransform.0: transform
URxvt.selection-autotransform.1: transform
...
For example, the following will transform selections of the form "filename:number", often seen in compiler messages, into "vi
+$filename $word":
URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\d+):?$/vi +$2 \Q$1\E\x0d/
And this example matches the same,but replaces it with vi-commands you can paste directly into your (vi :) editor:
URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\d+):?$/:e \Q$1\E\x0d:$2\x0d/
Of course, this can be modified to suit your needs and your editor :)
To expand the example above to typical perl error messages ("XXX at FILENAME line YYY."), you need a slightly more elaborate solution:
URxvt.selection.pattern-0: ( at .*? line \d+[,.])
URxvt.selection-autotransform.0: s/^ at (.*?) line (\d+)[,.]$/:e \Q$1E\x0d:$2\x0d/
The first line tells the selection code to treat the unchanging part of every error message as a selection pattern, and the second line
transforms the message into vi commands to load the file.
tabbed
This transforms the terminal into a tabbar with additional terminals, that is, it implements what is commonly referred to as "tabbed
terminal". The topmost line displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one button per tab.
Clicking a button will activate that tab. Pressing Shift-Left and Shift-Right will switch to the tab left or right of the current one,
while Shift-Down creates a new tab.
The tabbar itself can be configured similarly to a normal terminal, but with a resource class of "URxvt.tabbed". In addition, it
supports the following four resources (shown with defaults):
URxvt.tabbed.tabbar-fg: <colour-index, default 3>
URxvt.tabbed.tabbar-bg: <colour-index, default 0>
URxvt.tabbed.tab-fg: <colour-index, default 0>
URxvt.tabbed.tab-bg: <colour-index, default 1>
See COLOR AND GRAPHICS in the urxvt(1) manpage for valid indices.
matcher
Uses per-line display filtering ("on_line_update") to underline text matching a certain pattern and make it clickable. When clicked
with the mouse button specified in the "matcher.button" resource (default 2, or middle), the program specified in the
"matcher.launcher" resource (default, the "urlLauncher" resource, "sensible-browser") will be started with the matched text as first
argument. The default configuration is suitable for matching URLs and launching a web browser, like the former "mark-urls" extension.
The default pattern to match URLs can be overridden with the "matcher.pattern.0" resource, and additional patterns can be specified
with numbered patterns, in a manner similar to the "selection" extension. The launcher can also be overridden on a per-pattern basis.
It is possible to activate the most recently seen match from the keyboard. Simply bind a keysym to "perl:matcher" as seen in the
example below.
Example configuration:
URxvt.perl-ext: default,matcher
URxvt.urlLauncher: sensible-browser
URxvt.keysym.C-Delete: perl:matcher
URxvt.matcher.button: 1
URxvt.matcher.pattern.1: \bwww\.[\w-]+\.[\w./?&@#-]*[\w/-]
URxvt.matcher.pattern.2: \B(/\S+?):(\d+)(?=:|$)
URxvt.matcher.launcher.2: gvim +$2 $1
xim-onthespot
This (experimental) perl extension implements OnTheSpot editing. It does not work perfectly, and some input methods don't seem to work
well with OnTheSpot editing in general, but it seems to work at least for SCIM and kinput2.
You enable it by specifying this extension and a preedit style of "OnTheSpot", i.e.:
urxvt -pt OnTheSpot -pe xim-onthespot
kuake<hotkey>
A very primitive quake-console-like extension. It was inspired by a description of how the programs "kuake" and "yakuake" work:
Whenever the user presses a global accelerator key (by default "F10"), the terminal will show or hide itself. Another press of the
accelerator key will hide or show it again.
Initially, the window will not be shown when using this extension.
This is useful if you need a single terminal that is not using any desktop space most of the time but is quickly available at the press
of a key.
The accelerator key is grabbed regardless of any modifiers, so this extension will actually grab a physical key just for this function.
If you want a quake-like animation, tell your window manager to do so (fvwm can do it).
overlay-osc
This extension implements some OSC commands to display timed popups on the screen - useful for status displays from within scripts. You
have to read the sources for more info.
block-graphics-to-ascii
A not very useful example of filtering all text output to the terminal by replacing all line-drawing characters (U+2500 .. U+259F) by a
similar-looking ascii character.
digital-clock
Displays a digital clock using the built-in overlay.
remote-clipboard
Somewhat of a misnomer, this extension adds two menu entries to the selection popup that allows one to run external commands to store
the selection somewhere and fetch it again.
We use it to implement a "distributed selection mechanism", which just means that one command uploads the file to a remote server, and
another reads it.
The commands can be set using the "URxvt.remote-selection.store" and "URxvt.remote-selection.fetch" resources. The first should read
the selection to store from STDIN (always in UTF-8), the second should provide the selection data on STDOUT (also in UTF-8).
The defaults (which are likely useless to you) use rsh and cat:
URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
selection-pastebin
This is a little rarely useful extension that Uploads the selection as textfile to a remote site (or does other things). (The
implementation is not currently secure for use in a multiuser environment as it writes to /tmp directly.).
It listens to the "selection-pastebin:remote-pastebin" keyboard command, i.e.
URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
Pressing this combination runs a command with "%" replaced by the name of the textfile. This command can be set via a resource:
URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
And the default is likely not useful to anybody but the few people around here :)
The name of the textfile is the hex encoded md5 sum of the selection, so the same content should lead to the same filename.
After a successful upload the selection will be replaced by the text given in the "selection-pastebin-url" resource (again, the % is
the placeholder for the filename):
URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
Note to xrdb users: xrdb uses the C preprocessor, which might interpret the double "/" characters as comment start. Use "