| … | |
… | |
| 31 | You can disable the embedded perl interpreter by setting both "perl-ext" |
31 | You can disable the embedded perl interpreter by setting both "perl-ext" |
| 32 | and "perl-ext-common" resources to the empty string. |
32 | and "perl-ext-common" resources to the empty string. |
| 33 | |
33 | |
| 34 | =head1 PREPACKAGED EXTENSIONS |
34 | =head1 PREPACKAGED EXTENSIONS |
| 35 | |
35 | |
| 36 | This section describes the extensions delivered with this release. You can |
36 | A number of extensions are delivered with this release. You can find them |
| 37 | find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. |
37 | in F<@@RXVT_LIBDIR@@/urxvt/perl/>, and the documentation can be vewiwed |
|
|
38 | using F<< man urxvt-<EXTENSIONNAME> >>. |
| 38 | |
39 | |
| 39 | You can activate them like this: |
40 | You can activate them like this: |
| 40 | |
41 | |
| 41 | @@RXVT_NAME@@ -pe <extensionname> |
42 | @@RXVT_NAME@@ -pe <extensionname> |
| 42 | |
43 | |
| 43 | Or by adding them to the resource for extensions loaded by default: |
44 | Or by adding them to the resource for extensions loaded by default: |
| 44 | |
45 | |
| 45 | URxvt.perl-ext-common: default,selection-autotransform |
46 | URxvt.perl-ext-common: default,selection-autotransform |
| 46 | |
47 | |
| 47 | =over 4 |
48 | Extensions that add command line parameters or resources on their own are |
| 48 | |
49 | laoded automatically when used. |
| 49 | =item selection (enabled by default) |
|
|
| 50 | |
|
|
| 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>. |
|
|
| 56 | |
|
|
| 57 | A double-click usually selects the word under the cursor, further clicks |
|
|
| 58 | will enlarge the selection. |
|
|
| 59 | |
|
|
| 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: |
|
|
| 63 | |
|
|
| 64 | URxvt.selection.pattern-0: perl-regex |
|
|
| 65 | URxvt.selection.pattern-1: perl-regex |
|
|
| 66 | ... |
|
|
| 67 | |
|
|
| 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: |
|
|
| 72 | |
|
|
| 73 | URxvt.selection.pattern-0: \\|([^|]+)\\| |
|
|
| 74 | |
|
|
| 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 |
|
|
| 78 | end): |
|
|
| 79 | |
|
|
| 80 | URxvt.selection.pattern-0: ^(/[^:]+):\ |
|
|
| 81 | |
|
|
| 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. |
|
|
| 84 | |
|
|
| 85 | This extension also offers following bindable keyboard commands: |
|
|
| 86 | |
|
|
| 87 | =over 4 |
|
|
| 88 | |
|
|
| 89 | =item rot13 |
|
|
| 90 | |
|
|
| 91 | Rot-13 the selection when activated. Used via keyboard trigger: |
|
|
| 92 | |
|
|
| 93 | URxvt.keysym.C-M-r: perl:selection:rot13 |
|
|
| 94 | |
|
|
| 95 | =back |
|
|
| 96 | |
|
|
| 97 | =item option-popup (enabled by default) |
|
|
| 98 | |
|
|
| 99 | Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at |
|
|
| 100 | runtime. |
|
|
| 101 | |
|
|
| 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. |
|
|
| 105 | |
|
|
| 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 |
|
|
| 110 | first argument. |
|
|
| 111 | |
|
|
| 112 | The following will add an entry C<myoption> that changes |
|
|
| 113 | C<< $self->{myoption} >>: |
|
|
| 114 | |
|
|
| 115 | push @{ $self->{term}{option_popup_hook} }, sub { |
|
|
| 116 | ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) |
|
|
| 117 | }; |
|
|
| 118 | |
|
|
| 119 | =item selection-popup (enabled by default) |
|
|
| 120 | |
|
|
| 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. |
|
|
| 124 | |
|
|
| 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. |
|
|
| 128 | |
|
|
| 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<$_>. |
|
|
| 134 | |
|
|
| 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 |
|
|
| 137 | C<a>s: |
|
|
| 138 | |
|
|
| 139 | push @{ $self->{term}{selection_popup_hook} }, sub { |
|
|
| 140 | /a/ ? ("a to b" => sub { s/a/b/g } |
|
|
| 141 | : () |
|
|
| 142 | }; |
|
|
| 143 | |
|
|
| 144 | =item searchable-scrollback<hotkey> (enabled by default) |
|
|
| 145 | |
|
|
| 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 |
|
|
| 149 | screen. |
|
|
| 150 | |
|
|
| 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. |
|
|
| 158 | |
|
|
| 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. |
|
|
| 162 | |
|
|
| 163 | See L<perlre> for more info about perl regular expression syntax. |
|
|
| 164 | |
|
|
| 165 | =item readline (enabled by default) |
|
|
| 166 | |
|
|
| 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). |
|
|
| 172 | |
|
|
| 173 | To avoid too many false positives, this is only done when: |
|
|
| 174 | |
|
|
| 175 | =over 4 |
|
|
| 176 | |
|
|
| 177 | =item - the tty is in ICANON state. |
|
|
| 178 | |
|
|
| 179 | =item - the text cursor is visible. |
|
|
| 180 | |
|
|
| 181 | =item - the primary screen is currently being displayed. |
|
|
| 182 | |
|
|
| 183 | =item - the mouse is on the same (multi-row-) line as the text cursor. |
|
|
| 184 | |
|
|
| 185 | =back |
|
|
| 186 | |
|
|
| 187 | The normal selection mechanism isn't disabled, so quick successive clicks |
|
|
| 188 | might interfere with selection creation in harmless ways. |
|
|
| 189 | |
|
|
| 190 | =item selection-autotransform |
|
|
| 191 | |
|
|
| 192 | This selection allows you to do automatic transforms on a selection |
|
|
| 193 | whenever a selection is made. |
|
|
| 194 | |
|
|
| 195 | It works by specifying perl snippets (most useful is a single C<s///> |
|
|
| 196 | operator) that modify C<$_> as resources: |
|
|
| 197 | |
|
|
| 198 | URxvt.selection-autotransform.0: transform |
|
|
| 199 | URxvt.selection-autotransform.1: transform |
|
|
| 200 | ... |
|
|
| 201 | |
|
|
| 202 | For example, the following will transform selections of the form |
|
|
| 203 | C<filename:number>, often seen in compiler messages, into C<vi +$filename |
|
|
| 204 | $word>: |
|
|
| 205 | |
|
|
| 206 | URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ |
|
|
| 207 | |
|
|
| 208 | And this example matches the same,but replaces it with vi-commands you can |
|
|
| 209 | paste directly into your (vi :) editor: |
|
|
| 210 | |
|
|
| 211 | URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/ |
|
|
| 212 | |
|
|
| 213 | Of course, this can be modified to suit your needs and your editor :) |
|
|
| 214 | |
|
|
| 215 | To expand the example above to typical perl error messages ("XXX at |
|
|
| 216 | FILENAME line YYY."), you need a slightly more elaborate solution: |
|
|
| 217 | |
|
|
| 218 | URxvt.selection.pattern-0: ( at .*? line \\d+[,.]) |
|
|
| 219 | URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/ |
|
|
| 220 | |
|
|
| 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. |
|
|
| 224 | |
|
|
| 225 | =item tabbed |
|
|
| 226 | |
|
|
| 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 |
|
|
| 230 | button per tab. |
|
|
| 231 | |
|
|
| 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. |
|
|
| 235 | |
|
|
| 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): |
|
|
| 239 | |
|
|
| 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> |
|
|
| 244 | |
|
|
| 245 | See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid |
|
|
| 246 | indices. |
|
|
| 247 | |
|
|
| 248 | =item matcher |
|
|
| 249 | |
|
|
| 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. |
|
|
| 258 | |
|
|
| 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. |
|
|
| 263 | |
|
|
| 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. |
|
|
| 267 | |
|
|
| 268 | Example configuration: |
|
|
| 269 | |
|
|
| 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 |
|
|
| 278 | |
|
|
| 279 | =item xim-onthespot |
|
|
| 280 | |
|
|
| 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 |
|
|
| 284 | kinput2. |
|
|
| 285 | |
|
|
| 286 | You enable it by specifying this extension and a preedit style of |
|
|
| 287 | C<OnTheSpot>, i.e.: |
|
|
| 288 | |
|
|
| 289 | @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot |
|
|
| 290 | |
|
|
| 291 | =item kuake<hotkey> |
|
|
| 292 | |
|
|
| 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 |
|
|
| 297 | or show it again. |
|
|
| 298 | |
|
|
| 299 | Initially, the window will not be shown when using this extension. |
|
|
| 300 | |
|
|
| 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. |
|
|
| 303 | |
|
|
| 304 | The accelerator key is grabbed regardless of any modifiers, so this |
|
|
| 305 | extension will actually grab a physical key just for this function. |
|
|
| 306 | |
|
|
| 307 | If you want a quake-like animation, tell your window manager to do so |
|
|
| 308 | (fvwm can do it). |
|
|
| 309 | |
|
|
| 310 | =item overlay-osc |
|
|
| 311 | |
|
|
| 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. |
|
|
| 315 | |
|
|
| 316 | =item block-graphics-to-ascii |
|
|
| 317 | |
|
|
| 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. |
|
|
| 321 | |
|
|
| 322 | =item digital-clock |
|
|
| 323 | |
|
|
| 324 | Displays a digital clock using the built-in overlay. |
|
|
| 325 | |
|
|
| 326 | =item remote-clipboard |
|
|
| 327 | |
|
|
| 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. |
|
|
| 331 | |
|
|
| 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 |
|
|
| 334 | reads it. |
|
|
| 335 | |
|
|
| 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). |
|
|
| 340 | |
|
|
| 341 | The defaults (which are likely useless to you) use rsh and cat: |
|
|
| 342 | |
|
|
| 343 | URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' |
|
|
| 344 | URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection' |
|
|
| 345 | |
|
|
| 346 | =item selection-pastebin |
|
|
| 347 | |
|
|
| 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 |
|
|
| 351 | F</tmp> directly.). |
|
|
| 352 | |
|
|
| 353 | It listens to the C<selection-pastebin:remote-pastebin> keyboard command, |
|
|
| 354 | i.e. |
|
|
| 355 | |
|
|
| 356 | URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin |
|
|
| 357 | |
|
|
| 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: |
|
|
| 360 | |
|
|
| 361 | URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/. |
|
|
| 362 | |
|
|
| 363 | And the default is likely not useful to anybody but the few people around |
|
|
| 364 | here :) |
|
|
| 365 | |
|
|
| 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. |
|
|
| 368 | |
|
|
| 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 |
|
|
| 371 | for the filename): |
|
|
| 372 | |
|
|
| 373 | URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% |
|
|
| 374 | |
|
|
| 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 |
|
|
| 378 | or not. |
|
|
| 379 | |
|
|
| 380 | =item macosx-clipboard and macosx-clipboard-native |
|
|
| 381 | |
|
|
| 382 | These two modules implement an extended clipboard for Mac OS X. They are |
|
|
| 383 | used like this: |
|
|
| 384 | |
|
|
| 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 |
|
|
| 388 | |
|
|
| 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 |
|
|
| 392 | simpler etc. etc. |
|
|
| 393 | |
|
|
| 394 | =item example-refresh-hooks |
|
|
| 395 | |
|
|
| 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 |
|
|
| 398 | overlays or changes. |
|
|
| 399 | |
|
|
| 400 | =item confirm-paste |
|
|
| 401 | |
|
|
| 402 | Displays a confirmation dialog when a paste containing at least a full |
|
|
| 403 | line is detected. |
|
|
| 404 | |
|
|
| 405 | =item bell-command |
|
|
| 406 | |
|
|
| 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: |
|
|
| 410 | |
|
|
| 411 | URxvt.bell-command: notify-send "Beep, Beep" |
|
|
| 412 | |
|
|
| 413 | =back |
|
|
| 414 | |
50 | |
| 415 | =head1 API DOCUMENTATION |
51 | =head1 API DOCUMENTATION |
| 416 | |
52 | |
| 417 | =head2 General API Considerations |
53 | =head2 General API Considerations |
| 418 | |
54 | |
