ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.23 by root, Thu Jan 12 05:37:34 2006 UTC vs.
Revision 1.27 by root, Fri Jan 13 12:40:46 2006 UTC

1NAME 1NAME
2 rxvtperl - rxvt-unicode's embedded perl interpreter 2 urxvtperl - rxvt-unicode's embedded perl interpreter
3 3
4SYNOPSIS 4SYNOPSIS
5 # create a file grab_test in $HOME: 5 # create a file grab_test in $HOME:
6 6
7 sub on_sel_grab { 7 sub on_sel_grab {
8 warn "you selected ", $_[0]->selection; 8 warn "you selected ", $_[0]->selection;
9 () 9 ()
10 } 10 }
11 11
12 # start a rxvt using it: 12 # start a urxvt using it:
13 13
14 rxvt --perl-lib $HOME -pe grab_test 14 urxvt --perl-lib $HOME -pe grab_test
15 15
16DESCRIPTION 16DESCRIPTION
17 Everytime a terminal object gets created, extension scripts specified 17 Everytime a terminal object gets created, extension scripts specified
18 via the "perl" resource are loaded and associated with it. 18 via the "perl" resource are loaded and associated with it.
19 19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and 20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8. 21 thus must be encoded as UTF-8.
22 22
23 Each script will only ever be loaded once, even in rxvtd, where scripts 23 Each script will only ever be loaded once, even in urxvtd, where scripts
24 will be shared (but not enabled) for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26PREPACKAGED EXTENSIONS 26PREPACKAGED EXTENSIONS
27 This section describes the extensions delivered with this release. You 27 This section describes the extensions delivered with this release. You
28 can find them in /opt/rxvt/lib/urxvt/perl/. 28 can find them in /usr/local/lib/urxvt/perl/.
29 29
30 You can activate them like this: 30 You can activate them like this:
31 31
32 rxvt -pe <extensionname> 32 urxvt -pe <extensionname>
33 33
34 selection (enabled by default) 34 selection (enabled by default)
35 (More) intelligent selection. This extension tries to be more 35 (More) intelligent selection. This extension tries to be more
36 intelligent when the user extends selections (double-click and 36 intelligent when the user extends selections (double-click and
37 further clicks). Right now, it tries to select words, urls and 37 further clicks). Right now, it tries to select words, urls and
… …
39 your ls supports "--quoting-style=shell". 39 your ls supports "--quoting-style=shell".
40 40
41 A double-click usually selects the word under the cursor, further 41 A double-click usually selects the word under the cursor, further
42 clicks will enlarge the selection. 42 clicks will enlarge the selection.
43 43
44 The selection works by trying to match a number of regexes and
45 displaying them in increasing order of length. You can add your own
46 regexes by specifying resources of the form:
47
48 URxvt.selection.pattern-0: perl-regex
49 URxvt.selection.pattern-1: perl-regex
50 ...
51
52 The index number (0, 1...) must not have any holes, and each regex
53 must contain at least one pair of capturing parentheses, which will
54 be used for the match. For example, the followign adds a regex that
55 matches everything between two vertical bars:
56
57 URxvt.selection.pattern-0: \\|([^|]+)\\|
58
59 You can look at the source of the selection extension to see more
60 interesting uses, such as parsing a line from beginning to end.
61
44 It also offers the following bindable keyboard command: 62 This extension also offers the following bindable keyboard command:
45 63
46 rot13 64 rot13
47 Rot-13 the selection when activated. Used via keyboard trigger: 65 Rot-13 the selection when activated. Used via keyboard trigger:
48 66
49 URxvt.keysym.C-M-r: perl:selection:rot13 67 URxvt.keysym.C-M-r: perl:selection:rot13
… …
70 "End" jumps to the bottom. "Escape" leaves search mode and returns 88 "End" jumps to the bottom. "Escape" leaves search mode and returns
71 to the point where search was started, while "Enter" or "Return" 89 to the point where search was started, while "Enter" or "Return"
72 stay at the current position and additionally stores the first match 90 stay at the current position and additionally stores the first match
73 in the current line into the primary selection. 91 in the current line into the primary selection.
74 92
75 digital-clock 93 selection-autotransform
76 Displays a digital clock using the built-in overlay. 94 This selection allows you to do automatic transforms on a selection
95 whenever a selection is made.
96
97 It works by specifying perl snippets (most useful is a single "s///"
98 operator) that modify $_ as resources:
99
100 URxvt.selection-autotransform.0: transform
101 URxvt.selection-autotransform.1: transform
102 ...
103
104 For example, the following will transform selections of the form
105 "filename:number", often seen in compiler messages, into "vi
106 +$filename $word":
107
108 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
109
110 And this example matches the same,but replaces it with vi-commands
111 you can paste directly into your (vi :) editor:
112
113 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
114
115 Of course, this can be modified to suit your needs and your editor
116 :)
117
118 To expand the example above to typical perl error messages ("XXX at
119 FILENAME line YYY."), you need a slightly more elaborate solution:
120
121 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
122 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
123
124 The first line tells the selection code to treat the unchanging part
125 of every error message as a selection pattern, and the second line
126 transforms the message into vi commands to load the file.
77 127
78 mark-urls 128 mark-urls
79 Uses per-line display filtering ("on_line_update") to underline urls 129 Uses per-line display filtering ("on_line_update") to underline urls
80 and make them clickable. When middle-clicked, the program specified 130 and make them clickable. When middle-clicked, the program specified
81 in the resource "urlLauncher" (default "x-www-browser") will be 131 in the resource "urlLauncher" (default "x-www-browser") will be
… …
83 133
84 block-graphics-to-ascii 134 block-graphics-to-ascii
85 A not very useful example of filtering all text output to the 135 A not very useful example of filtering all text output to the
86 terminal, by replacing all line-drawing characters (U+2500 .. 136 terminal, by replacing all line-drawing characters (U+2500 ..
87 U+259F) by a similar-looking ascii character. 137 U+259F) by a similar-looking ascii character.
138
139 digital-clock
140 Displays a digital clock using the built-in overlay.
88 141
89 example-refresh-hooks 142 example-refresh-hooks
90 Displays a very simple digital clock in the upper right corner of 143 Displays a very simple digital clock in the upper right corner of
91 the window. Illustrates overwriting the refresh callbacks to create 144 the window. Illustrates overwriting the refresh callbacks to create
92 your own overlays or changes. 145 your own overlays or changes.
… …
265 Called just after the screen gets redrawn. See "on_refresh_begin". 318 Called just after the screen gets redrawn. See "on_refresh_begin".
266 319
267 on_keyboard_command $term, $string 320 on_keyboard_command $term, $string
268 Called whenever the user presses a key combination that has a 321 Called whenever the user presses a key combination that has a
269 "perl:string" action bound to it (see description of the keysym 322 "perl:string" action bound to it (see description of the keysym
270 resource in the rxvt(1) manpage). 323 resource in the urxvt(1) manpage).
324
325 on_x_event $term, $event
326 Called on every X event received on the vt window (and possibly
327 other windows). Should only be used as a last resort. Most event
328 structure members are not passed.
271 329
272 on_focus_in $term 330 on_focus_in $term
273 Called whenever the window gets the keyboard focus, before 331 Called whenever the window gets the keyboard focus, before
274 rxvt-unicode does focus in processing. 332 rxvt-unicode does focus in processing.
275 333
… …
339 397
340 urxvt::CurrentTime 398 urxvt::CurrentTime
341 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, 399 urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
342 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, 400 Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
343 Button5Mask, AnyModifier 401 Button5Mask, AnyModifier
402 urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
403 ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
404 PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
405 Button3MotionMask, Button4MotionMask, Button5MotionMask,
406 ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
407 StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
408 SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
409 ColormapChangeMask, OwnerGrabButtonMask
410 urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
411 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
412 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
413 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
414 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
415 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
416 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
344 Various constants for use in X calls and event processing. 417 Various constants for use in X calls and event processing.
345 418
346 RENDITION 419 RENDITION
347 Rendition bitsets contain information about colour, font, font styles 420 Rendition bitsets contain information about colour, font, font styles
348 and similar information for each screen cell. 421 and similar information for each screen cell.
… …
401 initialise perl, and the terminal object otherwise. The "init" and 474 initialise perl, and the terminal object otherwise. The "init" and
402 "start" hooks will be called during this call. 475 "start" hooks will be called during this call.
403 476
404 $term->destroy 477 $term->destroy
405 Destroy the terminal object (close the window, free resources etc.). 478 Destroy the terminal object (close the window, free resources etc.).
406 Please note that rxvt will not exit as long as any event watchers 479 Please note that urxvt will not exit as long as any event watchers
407 (timers, io watchers) are still active. 480 (timers, io watchers) are still active.
408 481
409 $isset = $term->option ($optval[, $set]) 482 $isset = $term->option ($optval[, $set])
410 Returns true if the option specified by $optval is enabled, and 483 Returns true if the option specified by $optval is enabled, and
411 optionally change it. All option values are stored by name in the 484 optionally change it. All option values are stored by name in the
… …
466 there is only one resource database per display, and later 539 there is only one resource database per display, and later
467 invocations might return the wrong resources. 540 invocations might return the wrong resources.
468 541
469 $success = $term->parse_keysym ($keysym_spec, $command_string) 542 $success = $term->parse_keysym ($keysym_spec, $command_string)
470 Adds a keymap translation exactly as specified via a resource. See 543 Adds a keymap translation exactly as specified via a resource. See
471 the "keysym" resource in the rxvt(1) manpage. 544 the "keysym" resource in the urxvt(1) manpage.
472 545
473 $rend = $term->rstyle ([$new_rstyle]) 546 $rend = $term->rstyle ([$new_rstyle])
474 Return and optionally change the current rendition. Text that is 547 Return and optionally change the current rendition. Text that is
475 output by the terminal application will use this style. 548 output by the terminal application will use this style.
476 549
… …
595 $windowid = $term->parent 668 $windowid = $term->parent
596 Return the window id of the toplevel window. 669 Return the window id of the toplevel window.
597 670
598 $windowid = $term->vt 671 $windowid = $term->vt
599 Return the window id of the terminal window. 672 Return the window id of the terminal window.
673
674 $term->vt_emask_add ($x_event_mask)
675 Adds the specified events to the vt event mask. Useful e.g. when you
676 want to receive pointer events all the times:
677
678 $term->vt_emask_add (urxvt::PointerMotionMask);
600 679
601 $window_width = $term->width 680 $window_width = $term->width
602 $window_height = $term->height 681 $window_height = $term->height
603 $font_width = $term->fwidth 682 $font_width = $term->fwidth
604 $font_height = $term->fheight 683 $font_height = $term->fheight

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines