ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.87 by root, Thu Jan 12 05:37:34 2006 UTC vs.
Revision 1.129 by root, Wed Jan 25 15:11:31 2006 UTC

34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
39 43
40=over 4 44=over 4
41 45
42=item selection (enabled by default) 46=item selection (enabled by default)
43 47
48C<--quoting-style=shell>. 52C<--quoting-style=shell>.
49 53
50A double-click usually selects the word under the cursor, further clicks 54A double-click usually selects the word under the cursor, further clicks
51will enlarge the selection. 55will enlarge the selection.
52 56
57The selection works by trying to match a number of regexes and displaying
58them in increasing order of length. You can add your own regexes by
59specifying resources of the form:
60
61 URxvt.selection.pattern-0: perl-regex
62 URxvt.selection.pattern-1: perl-regex
63 ...
64
65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything
68between two vertical bars:
69
70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71
72Another example: Programs I use often output "absolute path: " at the
73beginning of a line when they process multiple files. The following
74pattern matches the filename (note, there is a single space at the very
75end):
76
77 URxvt.selection.pattern-0: ^(/[^:]+):\
78
79You can look at the source of the selection extension to see more
80interesting uses, such as parsing a line from beginning to end.
81
53It also offers the following bindable keyboard command: 82This extension also offers following bindable keyboard commands:
54 83
55=over 4 84=over 4
56 85
57=item rot13 86=item rot13
58 87
69 98
70=item selection-popup (enabled by default) 99=item selection-popup (enabled by default)
71 100
72Binds a popup menu to Ctrl-Button3 that lets you convert the selection 101Binds a popup menu to Ctrl-Button3 that lets you convert the selection
73text into various other formats/action (such as uri unescaping, perl 102text into various other formats/action (such as uri unescaping, perl
74evalution, web-browser starting etc.), depending on content. 103evaluation, web-browser starting etc.), depending on content.
104
105Other extensions can extend this popup menu by pushing a code reference
106onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
107popup is displayed.
108
109It's sole argument is the popup menu, which can be modified. The selection
110is in C<$_>, which can be used to decide wether to add something or not.
111It should either return nothing or a string and a code reference. The
112string will be used as button text and the code reference will be called
113when the button gets activated and should transform C<$_>.
114
115The following will add an entry C<a to b> that transforms all C<a>s in
116the selection to C<b>s, but only if the selection currently contains any
117C<a>s:
118
119 push @{ $self->{term}{selection_popup_hook} }, sub {
120 /a/ ? ("a to be" => sub { s/a/b/g }
121 : ()
122 };
75 123
76=item searchable-scrollback<hotkey> (enabled by default) 124=item searchable-scrollback<hotkey> (enabled by default)
77 125
78Adds regex search functionality to the scrollback buffer, triggered 126Adds regex search functionality to the scrollback buffer, triggered
79by a hotkey (default: C<M-s>). While in search mode, normal terminal 127by a hotkey (default: C<M-s>). While in search mode, normal terminal
86bottom. C<Escape> leaves search mode and returns to the point where search 134bottom. C<Escape> leaves search mode and returns to the point where search
87was started, while C<Enter> or C<Return> stay at the current position and 135was started, while C<Enter> or C<Return> stay at the current position and
88additionally stores the first match in the current line into the primary 136additionally stores the first match in the current line into the primary
89selection. 137selection.
90 138
91=item digital-clock 139=item readline (enabled by default)
92 140
93Displays a digital clock using the built-in overlay. 141A support package that tries to make editing with readline easier. At the
142moment, it reacts to clicking with the left mouse button by trying to
143move the text cursor to this position. It does so by generating as many
144cursor-left or cursor-right keypresses as required (the this only works
145for programs that correctly support wide characters).
146
147To avoid too many false positives, this is only done when:
148
149=over 4
150
151=item - the tty is in ICANON state.
152
153=item - the text cursor is visible.
154
155=item - the primary screen is currently being displayed.
156
157=item - the mouse is on the same (multi-row-) line as the text cursor.
158
159=back
160
161The normal selection mechanism isn't disabled, so quick successive clicks
162might interfere with selection creation in harmless ways.
163
164=item selection-autotransform
165
166This selection allows you to do automatic transforms on a selection
167whenever a selection is made.
168
169It works by specifying perl snippets (most useful is a single C<s///>
170operator) that modify C<$_> as resources:
171
172 URxvt.selection-autotransform.0: transform
173 URxvt.selection-autotransform.1: transform
174 ...
175
176For example, the following will transform selections of the form
177C<filename:number>, often seen in compiler messages, into C<vi +$filename
178$word>:
179
180 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
181
182And this example matches the same,but replaces it with vi-commands you can
183paste directly into your (vi :) editor:
184
185 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
186
187Of course, this can be modified to suit your needs and your editor :)
188
189To expand the example above to typical perl error messages ("XXX at
190FILENAME line YYY."), you need a slightly more elaborate solution:
191
192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
194
195The first line tells the selection code to treat the unchanging part of
196every error message as a selection pattern, and the second line transforms
197the message into vi commands to load the file.
198
199=item tabbed
200
201This transforms the terminal into a tabbar with additional terminals, that
202is, it implements what is commonly refered to as "tabbed terminal". The topmost line
203displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
204button per tab.
205
206Clicking a button will activate that tab. Pressing B<Shift-Left> and
207B<Shift-Right> will switch to the tab left or right of the current one,
208while B<Shift-Down> creates a new tab.
94 209
95=item mark-urls 210=item mark-urls
96 211
97Uses per-line display filtering (C<on_line_update>) to underline urls and 212Uses per-line display filtering (C<on_line_update>) to underline urls and
98make them clickable. When middle-clicked, the program specified in the 213make them clickable. When middle-clicked, the program specified in the
99resource C<urlLauncher> (default C<x-www-browser>) will be started with 214resource C<urlLauncher> (default C<x-www-browser>) will be started with
100the URL as first argument. 215the URL as first argument.
101 216
217=item xim-onthespot
218
219This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with
221OnTheSpot editing in general, but it seems to work at leats for SCIM and
222kinput2.
223
224You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.:
226
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228
229=item automove-background
230
231This is basically a one-line extension that dynamically changes the background pixmap offset
232to the window position, in effect creating the same effect as pseudo transparency with
233a custom pixmap. No scaling is supported in this mode. Exmaple:
234
235 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
236
102=item block-graphics-to-ascii 237=item block-graphics-to-ascii
103 238
104A not very useful example of filtering all text output to the terminal, 239A not very useful example of filtering all text output to the terminal,
105by replacing all line-drawing characters (U+2500 .. U+259F) by a 240by replacing all line-drawing characters (U+2500 .. U+259F) by a
106similar-looking ascii character. 241similar-looking ascii character.
242
243=item digital-clock
244
245Displays a digital clock using the built-in overlay.
246
247=item remote-selection
248
249Somewhat of a misnomer, this extension adds two menu entries to the
250selection popup that allows one ti run external commands to store the
251selection somewhere and fetch it again.
252
253We use it to implement a "distributed selection mechanism", which just
254means that one command uploads the file to a remote server, and another
255reads it.
256
257The commands can be set using the C<URxvt.remote-selection.store> and
258C<URxvt.remote-selection.fetch> resources. The first should read the
259selection to store from STDIN (always in UTF-8), the second should provide
260the selection data on STDOUT (also in UTF-8).
261
262The defaults (which are likely useless to you) use rsh and cat:
263
264 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
265 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
266
267=item selection-pastebin
268
269This is a little rarely useful extension that Uploads the selection as
270textfile to a remote site (or does other things). (The implementation is
271not currently secure for use in a multiuser environment as it writes to
272F</tmp> directly.).
273
274It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
275i.e.
276
277 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
278
279Pressing this combination runs a command with C<%> replaced by the name of
280the textfile. This command can be set via a resource:
281
282 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
283
284And the default is likely not useful to anybody but the few people around
285here :)
286
287The name of the textfile is the hex encoded md5 sum of the selection, so
288the same content should lead to the same filename.
289
290After a successful upload the selection will be replaced by the text given
291in the C<selection-pastebin-url> resource (again, the % is the placeholder
292for the filename):
293
294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
107 295
108=item example-refresh-hooks 296=item example-refresh-hooks
109 297
110Displays a very simple digital clock in the upper right corner of the 298Displays a very simple digital clock in the upper right corner of the
111window. Illustrates overwriting the refresh callbacks to create your own 299window. Illustrates overwriting the refresh callbacks to create your own
190called whenever the relevant event happens. 378called whenever the relevant event happens.
191 379
192The first argument passed to them is an extension oject as described in 380The first argument passed to them is an extension oject as described in
193the in the C<Extension Objects> section. 381the in the C<Extension Objects> section.
194 382
195B<All> of these hooks must return a boolean value. If it is true, then the 383B<All> of these hooks must return a boolean value. If any of the called
196event counts as being I<consumed>, and the invocation of other hooks is 384hooks returns true, then the event counts as being I<consumed>, and the
197skipped, and the relevant action might not be carried out by the C++ code. 385relevant action might not be carried out by the C++ code.
198 386
199I<< When in doubt, return a false value (preferably C<()>). >> 387I<< When in doubt, return a false value (preferably C<()>). >>
200 388
201=over 4 389=over 4
202 390
203=item on_init $term 391=item on_init $term
204 392
205Called after a new terminal object has been initialized, but before 393Called after a new terminal object has been initialized, but before
206windows are created or the command gets run. Most methods are unsafe to 394windows are created or the command gets run. Most methods are unsafe to
207call or deliver senseless data, as terminal size and other characteristics 395call or deliver senseless data, as terminal size and other characteristics
208have not yet been determined. You can safely query and change resources, 396have not yet been determined. You can safely query and change resources
209though. 397and options, though. For many purposes the C<on_start> hook is a better
398place.
399
400=item on_start $term
401
402Called at the very end of initialisation of a new terminal, just before
403trying to map (display) the toplevel and returning to the mainloop.
404
405=item on_destroy $term
406
407Called whenever something tries to destroy terminal, when the terminal is
408still fully functional (not for long, though).
210 409
211=item on_reset $term 410=item on_reset $term
212 411
213Called after the screen is "reset" for any reason, such as resizing or 412Called after the screen is "reset" for any reason, such as resizing or
214control sequences. Here is where you can react on changes to size-related 413control sequences. Here is where you can react on changes to size-related
215variables. 414variables.
216 415
217=item on_start $term 416=item on_child_start $term, $pid
218 417
219Called at the very end of initialisation of a new terminal, just before 418Called just after the child process has been C<fork>ed.
220returning to the mainloop. 419
420=item on_child_exit $term, $status
421
422Called just after the child process has exited. C<$status> is the status
423from C<waitpid>.
221 424
222=item on_sel_make $term, $eventtime 425=item on_sel_make $term, $eventtime
223 426
224Called whenever a selection has been made by the user, but before the 427Called whenever a selection has been made by the user, but before the
225selection text is copied, so changes to the beginning, end or type of the 428selection text is copied, so changes to the beginning, end or type of the
318 521
319Called whenever the user presses a key combination that has a 522Called whenever the user presses a key combination that has a
320C<perl:string> action bound to it (see description of the B<keysym> 523C<perl:string> action bound to it (see description of the B<keysym>
321resource in the @@RXVT_NAME@@(1) manpage). 524resource in the @@RXVT_NAME@@(1) manpage).
322 525
526=item on_x_event $term, $event
527
528Called on every X event received on the vt window (and possibly other
529windows). Should only be used as a last resort. Most event structure
530members are not passed.
531
323=item on_focus_in $term 532=item on_focus_in $term
324 533
325Called whenever the window gets the keyboard focus, before rxvt-unicode 534Called whenever the window gets the keyboard focus, before rxvt-unicode
326does focus in processing. 535does focus in processing.
327 536
328=item on_focus_out $term 537=item on_focus_out $term
329 538
330Called wheneever the window loses keyboard focus, before rxvt-unicode does 539Called wheneever the window loses keyboard focus, before rxvt-unicode does
331focus out processing. 540focus out processing.
332 541
542=item on_configure_notify $term, $event
543
544=item on_property_notify $term, $event
545
333=item on_key_press $term, $event, $keysym, $octets 546=item on_key_press $term, $event, $keysym, $octets
334 547
335=item on_key_release $term, $event, $keysym 548=item on_key_release $term, $event, $keysym
336 549
337=item on_button_press $term, $event 550=item on_button_press $term, $event
346 559
347Called whenever the corresponding X event is received for the terminal If 560Called whenever the corresponding X event is received for the terminal If
348the hook returns true, then the even will be ignored by rxvt-unicode. 561the hook returns true, then the even will be ignored by rxvt-unicode.
349 562
350The event is a hash with most values as named by Xlib (see the XEvent 563The event is a hash with most values as named by Xlib (see the XEvent
351manpage), with the additional members C<row> and C<col>, which are the row 564manpage), with the additional members C<row> and C<col>, which are the
352and column under the mouse cursor. 565(real, not screen-based) row and column under the mouse cursor.
353 566
354C<on_key_press> additionally receives the string rxvt-unicode would 567C<on_key_press> additionally receives the string rxvt-unicode would
355output, if any, in locale-specific encoding. 568output, if any, in locale-specific encoding.
356 569
357subwindow. 570subwindow.
571
572=item on_client_message $term, $event
573
574=item on_wm_protocols $term, $event
575
576=item on_wm_delete_window $term, $event
577
578Called when various types of ClientMessage events are received (all with
579format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
358 580
359=back 581=back
360 582
361=cut 583=cut
362 584
368use Scalar::Util (); 590use Scalar::Util ();
369use List::Util (); 591use List::Util ();
370 592
371our $VERSION = 1; 593our $VERSION = 1;
372our $TERM; 594our $TERM;
595our @TERM_INIT;
596our @TERM_EXT;
373our @HOOKNAME; 597our @HOOKNAME;
374our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 598our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
375our %OPTION; 599our %OPTION;
376 600
377our $LIBDIR; 601our $LIBDIR;
378our $RESNAME; 602our $RESNAME;
379our $RESCLASS; 603our $RESCLASS;
380our $RXVTNAME; 604our $RXVTNAME;
381 605
606our $NOCHAR = chr 0xffff;
607
382=head2 Variables in the C<urxvt> Package 608=head2 Variables in the C<urxvt> Package
383 609
384=over 4 610=over 4
385 611
386=item $urxvt::LIBDIR 612=item $urxvt::LIBDIR
398 624
399=item $urxvt::TERM 625=item $urxvt::TERM
400 626
401The current terminal. This variable stores the current C<urxvt::term> 627The current terminal. This variable stores the current C<urxvt::term>
402object, whenever a callback/hook is executing. 628object, whenever a callback/hook is executing.
629
630=item @urxvt::TERM_INIT
631
632All coderefs in this array will be called as methods of the next newly
633created C<urxvt::term> object (during the C<on_init> phase). The array
634gets cleared before the codereferences that were in it are being executed,
635so coderefs can push themselves onto it again if they so desire.
636
637This complements to the perl-eval commandline option, but gets executed
638first.
639
640=item @urxvt::TERM_EXT
641
642Works similar to C<@TERM_INIT>, but contains perl package/class names, which
643get registered as normal extensions after calling the hooks in C<@TERM_INIT>
644but before other extensions. Gets cleared just like C<@TERM_INIT>.
403 645
404=back 646=back
405 647
406=head2 Functions in the C<urxvt> Package 648=head2 Functions in the C<urxvt> Package
407 649
422Using this function has the advantage that its output ends up in the 664Using this function has the advantage that its output ends up in the
423correct place, e.g. on stderr of the connecting urxvtc client. 665correct place, e.g. on stderr of the connecting urxvtc client.
424 666
425Messages have a size limit of 1023 bytes currently. 667Messages have a size limit of 1023 bytes currently.
426 668
427=item $is_safe = urxvt::safe
428
429Returns true when it is safe to do potentially unsafe things, such as
430evaluating perl code specified by the user. This is true when urxvt was
431started setuid or setgid.
432
433=item $time = urxvt::NOW 669=item $time = urxvt::NOW
434 670
435Returns the "current time" (as per the event loop). 671Returns the "current time" (as per the event loop).
436 672
437=item urxvt::CurrentTime 673=item urxvt::CurrentTime
438 674
439=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 675=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
440Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 676Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
441Button4Mask, Button5Mask, AnyModifier 677Button4Mask, Button5Mask, AnyModifier
678
679=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
680ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
681PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
682Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
683KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
684ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
685FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
686
687=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
688EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
689GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
690UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
691ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
692CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
693SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
442 694
443Various constants for use in X calls and event processing. 695Various constants for use in X calls and event processing.
444 696
445=back 697=back
446 698
497=back 749=back
498 750
499=cut 751=cut
500 752
501BEGIN { 753BEGIN {
502 urxvt->bootstrap;
503
504 # overwrite perl's warn 754 # overwrite perl's warn
505 *CORE::GLOBAL::warn = sub { 755 *CORE::GLOBAL::warn = sub {
506 my $msg = join "", @_; 756 my $msg = join "", @_;
507 $msg .= "\n" 757 $msg .= "\n"
508 unless $msg =~ /\n$/; 758 unless $msg =~ /\n$/;
509 urxvt::warn ($msg); 759 urxvt::warn ($msg);
510 }; 760 };
511
512 # %ENV is the original startup environment
513 delete $ENV{IFS};
514 delete $ENV{CDPATH};
515 delete $ENV{BASH_ENV};
516 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
517} 761}
518 762
519my @hook_count; 763no warnings 'utf8';
764
520my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 765my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
521 766
522sub verbose { 767sub verbose {
523 my ($level, $msg) = @_; 768 my ($level, $msg) = @_;
524 warn "$msg\n" if $level <= $verbosity; 769 warn "$msg\n" if $level <= $verbosity;
525} 770}
526 771
527my $extension_pkg = "extension0000";
528my %extension_pkg; 772my %extension_pkg;
529 773
530# load a single script into its own package, once only 774# load a single script into its own package, once only
531sub extension_package($) { 775sub extension_package($) {
532 my ($path) = @_; 776 my ($path) = @_;
533 777
534 $extension_pkg{$path} ||= do { 778 $extension_pkg{$path} ||= do {
535 my $pkg = "urxvt::" . ($extension_pkg++); 779 $path =~ /([^\/\\]+)$/;
780 my $pkg = $1;
781 $pkg =~ s/[^[:word:]]/_/g;
782 $pkg = "urxvt::ext::$pkg";
536 783
537 verbose 3, "loading extension '$path' into package '$pkg'"; 784 verbose 3, "loading extension '$path' into package '$pkg'";
538 785
539 open my $fh, "<:raw", $path 786 open my $fh, "<:raw", $path
540 or die "$path: $!"; 787 or die "$path: $!";
541 788
542 my $source = untaint 789 my $source =
543 "package $pkg; use strict; use utf8;\n" 790 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
544 . "use base urxvt::term::extension::;\n"
545 . "#line 1 \"$path\"\n{\n" 791 . "#line 1 \"$path\"\n{\n"
546 . (do { local $/; <$fh> }) 792 . (do { local $/; <$fh> })
547 . "\n};\n1"; 793 . "\n};\n1";
548 794
549 eval $source 795 eval $source
563 if ($htype == 0) { # INIT 809 if ($htype == 0) { # INIT
564 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 810 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
565 811
566 my %ext_arg; 812 my %ext_arg;
567 813
814 {
815 my @init = @TERM_INIT;
816 @TERM_INIT = ();
817 $_->($TERM) for @init;
818 my @pkg = @TERM_EXT;
819 @TERM_EXT = ();
820 $TERM->register_package ($_) for @pkg;
821 }
822
568 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 823 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
569 if ($_ eq "default") { 824 if ($_ eq "default") {
570 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 825 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
571 } elsif (/^-(.*)$/) { 826 } elsif (/^-(.*)$/) {
572 delete $ext_arg{$1}; 827 delete $ext_arg{$1};
573 } elsif (/^([^<]+)<(.*)>$/) { 828 } elsif (/^([^<]+)<(.*)>$/) {
574 push @{ $ext_arg{$1} }, $2; 829 push @{ $ext_arg{$1} }, $2;
575 } else { 830 } else {
598 if $verbosity >= 10; 853 if $verbosity >= 10;
599 854
600 keys %$cb; 855 keys %$cb;
601 856
602 while (my ($pkg, $cb) = each %$cb) { 857 while (my ($pkg, $cb) = each %$cb) {
603 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 858 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
604 and last; 859 $retval ||= $retval_;
605 860
606 if ($@) { 861 if ($@) {
607 $TERM->ungrab; # better to lose the grab than the session 862 $TERM->ungrab; # better to lose the grab than the session
608 warn $@; 863 warn $@;
609 } 864 }
612 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 867 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
613 if $verbosity >= 11; 868 if $verbosity >= 11;
614 } 869 }
615 870
616 if ($htype == 1) { # DESTROY 871 if ($htype == 1) { # DESTROY
617 if (my $hook = delete $TERM->{_hook}) {
618 for my $htype (0..$#$hook) {
619 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
620 or set_should_invoke $htype, 0;
621 }
622 }
623
624 # clear package objects 872 # clear package objects
625 %$_ = () for values %{ $TERM->{_pkg} }; 873 %$_ = () for values %{ $TERM->{_pkg} };
626 874
627 # clear package 875 # clear package
628 %$TERM = (); 876 %$TERM = ();
629 } 877 }
630 878
631 $retval 879 $retval
632}
633
634sub exec_async(@) {
635 my $pid = fork;
636
637 return
638 if !defined $pid or $pid;
639
640 %ENV = %{ $TERM->env };
641
642 exec @_;
643 _exit 255;
644} 880}
645 881
646# urxvt::term::extension 882# urxvt::term::extension
647 883
648package urxvt::term::extension; 884package urxvt::term::extension;
654 while (my ($name, $cb) = each %hook) { 890 while (my ($name, $cb) = each %hook) {
655 my $htype = $HOOKTYPE{uc $name}; 891 my $htype = $HOOKTYPE{uc $name};
656 defined $htype 892 defined $htype
657 or Carp::croak "unsupported hook type '$name'"; 893 or Carp::croak "unsupported hook type '$name'";
658 894
895 $self->set_should_invoke ($htype, +1)
659 unless (exists $self->{term}{_hook}[$htype]{$pkg}) { 896 unless exists $self->{term}{_hook}[$htype]{$pkg};
660 $hook_count[$htype]++
661 or urxvt::set_should_invoke $htype, 1;
662 }
663 897
664 $self->{term}{_hook}[$htype]{$pkg} = $cb; 898 $self->{term}{_hook}[$htype]{$pkg} = $cb;
665 } 899 }
666} 900}
667 901
672 for my $name (@hook) { 906 for my $name (@hook) {
673 my $htype = $HOOKTYPE{uc $name}; 907 my $htype = $HOOKTYPE{uc $name};
674 defined $htype 908 defined $htype
675 or Carp::croak "unsupported hook type '$name'"; 909 or Carp::croak "unsupported hook type '$name'";
676 910
911 $self->set_should_invoke ($htype, -1)
677 if (delete $self->{term}{_hook}[$htype]{$pkg}) { 912 if delete $self->{term}{_hook}[$htype]{$pkg};
678 --$hook_count[$htype]
679 or urxvt::set_should_invoke $htype, 0;
680 }
681 } 913 }
682} 914}
683 915
684our $AUTOLOAD; 916our $AUTOLOAD;
685 917
791# find on_xxx subs in the package and register them 1023# find on_xxx subs in the package and register them
792# as hooks 1024# as hooks
793sub register_package { 1025sub register_package {
794 my ($self, $pkg, $argv) = @_; 1026 my ($self, $pkg, $argv) = @_;
795 1027
1028 no strict 'refs';
1029
1030 urxvt::verbose 6, "register package $pkg to $self";
1031
1032 @{"$pkg\::ISA"} = urxvt::term::extension::;
1033
796 my $proxy = bless { 1034 my $proxy = bless {
797 _pkg => $pkg, 1035 _pkg => $pkg,
798 argv => $argv, 1036 argv => $argv,
799 }, $pkg; 1037 }, $pkg;
800 Scalar::Util::weaken ($proxy->{term} = $self); 1038 Scalar::Util::weaken ($proxy->{term} = $self);
831 1069
832Destroy the terminal object (close the window, free resources 1070Destroy the terminal object (close the window, free resources
833etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1071etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
834watchers (timers, io watchers) are still active. 1072watchers (timers, io watchers) are still active.
835 1073
1074=item $term->exec_async ($cmd[, @args])
1075
1076Works like the combination of the C<fork>/C<exec> builtins, which executes
1077("starts") programs in the background. This function takes care of setting
1078the user environment before exec'ing the command (e.g. C<PATH>) and should
1079be preferred over explicit calls to C<exec> or C<system>.
1080
1081Returns the pid of the subprocess or C<undef> on error.
1082
1083=cut
1084
1085sub exec_async {
1086 my $self = shift;
1087
1088 my $pid = fork;
1089
1090 return $pid
1091 if !defined $pid or $pid;
1092
1093 %ENV = %{ $self->env };
1094
1095 exec @_;
1096 urxvt::_exit 255;
1097}
1098
836=item $isset = $term->option ($optval[, $set]) 1099=item $isset = $term->option ($optval[, $set])
837 1100
838Returns true if the option specified by C<$optval> is enabled, and 1101Returns true if the option specified by C<$optval> is enabled, and
839optionally change it. All option values are stored by name in the hash 1102optionally change it. All option values are stored by name in the hash
840C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1103C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
842Here is a a likely non-exhaustive list of option names, please see the 1105Here is a a likely non-exhaustive list of option names, please see the
843source file F</src/optinc.h> to see the actual list: 1106source file F</src/optinc.h> to see the actual list:
844 1107
845 borderLess console cursorBlink cursorUnderline hold iconic insecure 1108 borderLess console cursorBlink cursorUnderline hold iconic insecure
846 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1109 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
847 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1110 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
848 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1111 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
849 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1112 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
850 tripleclickwords utmpInhibit visualBell 1113 transparent tripleclickwords utmpInhibit visualBell
851 1114
852=item $value = $term->resource ($name[, $newval]) 1115=item $value = $term->resource ($name[, $newval])
853 1116
854Returns the current resource value associated with a given name and 1117Returns the current resource value associated with a given name and
855optionally sets a new value. Setting values is most useful in the C<init> 1118optionally sets a new value. Setting values is most useful in the C<init>
872 1135
873 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1136 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
874 borderLess color cursorBlink cursorUnderline cutchars delete_key 1137 borderLess color cursorBlink cursorUnderline cutchars delete_key
875 display_name embed ext_bwidth fade font geometry hold iconName 1138 display_name embed ext_bwidth fade font geometry hold iconName
876 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1139 imFont imLocale inputMethod insecure int_bwidth intensityStyles
877 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1140 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
878 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1141 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
879 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1142 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
880 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1143 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
881 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1144 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
882 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1145 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
883 shade term_name title transparent transparent_all tripleclickwords 1146 secondaryScreen secondaryScroll selectstyle shade term_name title
884 utmpInhibit visualBell 1147 transient_for transparent transparent_all tripleclickwords utmpInhibit
1148 visualBell
885 1149
886=cut 1150=cut
887 1151
888sub resource($$;$) { 1152sub resource($$;$) {
889 my ($self, $name) = (shift, shift); 1153 my ($self, $name) = (shift, shift);
1063 1327
1064Normally its not a good idea to use this function, as programs might be 1328Normally its not a good idea to use this function, as programs might be
1065confused by changes in cursor position or scrolling. Its useful inside a 1329confused by changes in cursor position or scrolling. Its useful inside a
1066C<on_add_lines> hook, though. 1330C<on_add_lines> hook, though.
1067 1331
1332=item $term->scr_change_screen ($screen)
1333
1334Switch to given screen - 0 primary, 1 secondary.
1335
1068=item $term->cmd_parse ($octets) 1336=item $term->cmd_parse ($octets)
1069 1337
1070Similar to C<scr_add_lines>, but the argument must be in the 1338Similar to C<scr_add_lines>, but the argument must be in the
1071locale-specific encoding of the terminal and can contain command sequences 1339locale-specific encoding of the terminal and can contain command sequences
1072(escape codes) that will be interpreted. 1340(escape codes) that will be interpreted.
1082Replaces the event mask of the pty watcher by the given event mask. Can 1350Replaces the event mask of the pty watcher by the given event mask. Can
1083be used to suppress input and output handling to the pty/tty. See the 1351be used to suppress input and output handling to the pty/tty. See the
1084description of C<< urxvt::timer->events >>. Make sure to always restore 1352description of C<< urxvt::timer->events >>. Make sure to always restore
1085the previous value. 1353the previous value.
1086 1354
1355=item $fd = $term->pty_fd
1356
1357Returns the master file descriptor for the pty in use, or C<-1> if no pty
1358is used.
1359
1087=item $windowid = $term->parent 1360=item $windowid = $term->parent
1088 1361
1089Return the window id of the toplevel window. 1362Return the window id of the toplevel window.
1090 1363
1091=item $windowid = $term->vt 1364=item $windowid = $term->vt
1092 1365
1093Return the window id of the terminal window. 1366Return the window id of the terminal window.
1094 1367
1368=item $term->vt_emask_add ($x_event_mask)
1369
1370Adds the specified events to the vt event mask. Useful e.g. when you want
1371to receive pointer events all the times:
1372
1373 $term->vt_emask_add (urxvt::PointerMotionMask);
1374
1095=item $window_width = $term->width 1375=item $window_width = $term->width
1096 1376
1097=item $window_height = $term->height 1377=item $window_height = $term->height
1098 1378
1099=item $font_width = $term->fwidth 1379=item $font_width = $term->fwidth
1112 1392
1113=item $max_scrollback = $term->saveLines 1393=item $max_scrollback = $term->saveLines
1114 1394
1115=item $nrow_plus_saveLines = $term->total_rows 1395=item $nrow_plus_saveLines = $term->total_rows
1116 1396
1117=item $lines_in_scrollback = $term->nsaved 1397=item $topmost_scrollback_row = $term->top_row
1118 1398
1119Return various integers describing terminal characteristics. 1399Return various integers describing terminal characteristics.
1120 1400
1121=item $x_display = $term->display_id 1401=item $x_display = $term->display_id
1122 1402
1148=item $modifiermask = $term->ModNumLockMask 1428=item $modifiermask = $term->ModNumLockMask
1149 1429
1150Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1430Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1151AltGr), the meta key (often Alt) and the num lock key, if applicable. 1431AltGr), the meta key (often Alt) and the num lock key, if applicable.
1152 1432
1433=item $screen = $term->current_screen
1434
1435Returns the currently displayed screen (0 primary, 1 secondary).
1436
1437=item $cursor_is_hidden = $term->hidden_cursor
1438
1439Returns wether the cursor is currently hidden or not.
1440
1153=item $view_start = $term->view_start ([$newvalue]) 1441=item $view_start = $term->view_start ([$newvalue])
1154 1442
1155Returns the negative row number of the topmost line. Minimum value is 1443Returns the row number of the topmost displayed line. Maximum value is
1156C<0>, which displays the normal terminal contents. Larger values scroll 1444C<0>, which displays the normal terminal contents. Lower values scroll
1157this many lines into the scrollback buffer. 1445this many lines into the scrollback buffer.
1158 1446
1159=item $term->want_refresh 1447=item $term->want_refresh
1160 1448
1161Requests a screen refresh. At the next opportunity, rxvt-unicode will 1449Requests a screen refresh. At the next opportunity, rxvt-unicode will
1176line, starting at column C<$start_col> (default C<0>), which is useful 1464line, starting at column C<$start_col> (default C<0>), which is useful
1177to replace only parts of a line. The font index in the rendition will 1465to replace only parts of a line. The font index in the rendition will
1178automatically be updated. 1466automatically be updated.
1179 1467
1180C<$text> is in a special encoding: tabs and wide characters that use more 1468C<$text> is in a special encoding: tabs and wide characters that use more
1181than one cell when displayed are padded with urxvt::NOCHAR characters 1469than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1182(C<chr 65535>). Characters with combining characters and other characters 1470characters. Characters with combining characters and other characters that
1183that do not fit into the normal tetx encoding will be replaced with 1471do not fit into the normal tetx encoding will be replaced with characters
1184characters in the private use area. 1472in the private use area.
1185 1473
1186You have to obey this encoding when changing text. The advantage is 1474You have to obey this encoding when changing text. The advantage is
1187that C<substr> and similar functions work on screen cells and not on 1475that C<substr> and similar functions work on screen cells and not on
1188characters. 1476characters.
1189 1477
1364 1652
1365Calls XUngrab for the most recent grab. Is called automatically on 1653Calls XUngrab for the most recent grab. Is called automatically on
1366evaluation errors, as it is better to lose the grab in the error case as 1654evaluation errors, as it is better to lose the grab in the error case as
1367the session. 1655the session.
1368 1656
1657=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1658
1659=item $atom_name = $term->XGetAtomName ($atom)
1660
1661=item @atoms = $term->XListProperties ($window)
1662
1663=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1664
1665=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1666
1667=item $term->XDeleteProperty ($window, $property)
1668
1669=item $window = $term->DefaultRootWindow
1670
1671=item $term->XReparentWindow ($window, $parent, [$x, $y])
1672
1673=item $term->XMapWindow ($window)
1674
1675=item $term->XUnmapWindow ($window)
1676
1677=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1678
1679=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1680
1681=item $term->XChangeInput ($window, $add_events[, $del_events])
1682
1683Various X or X-related functions. The C<$term> object only serves as
1684the source of the display, otherwise those functions map more-or-less
1685directory onto the X functions of the same name.
1686
1369=back 1687=back
1370 1688
1371=cut 1689=cut
1372 1690
1373package urxvt::popup; 1691package urxvt::popup;
1474 my $env = $self->{term}->env; 1792 my $env = $self->{term}->env;
1475 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1793 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1476 delete $env->{LC_ALL}; 1794 delete $env->{LC_ALL};
1477 $env->{LC_CTYPE} = $self->{term}->locale; 1795 $env->{LC_CTYPE} = $self->{term}->locale;
1478 1796
1479 urxvt::term->new ($env, $self->{term}->resource ("name"), 1797 urxvt::term->new ($env, "popup",
1480 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1798 "--perl-lib" => "", "--perl-ext-common" => "",
1799 "-pty-fd" => -1, "-sl" => 0,
1800 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1481 "--transient-for" => $self->{term}->parent, 1801 "--transient-for" => $self->{term}->parent,
1482 "-display" => $self->{term}->display_id, 1802 "-display" => $self->{term}->display_id,
1483 "-pe" => "urxvt-popup") 1803 "-pe" => "urxvt-popup")
1484 or die "unable to create popup window\n"; 1804 or die "unable to create popup window\n";
1485} 1805}
1490 delete $self->{term}{_destroy}{$self}; 1810 delete $self->{term}{_destroy}{$self};
1491 $self->{term}->ungrab; 1811 $self->{term}->ungrab;
1492} 1812}
1493 1813
1494=back 1814=back
1815
1816=cut
1817
1818package urxvt::watcher;
1819
1820@urxvt::timer::ISA = __PACKAGE__;
1821@urxvt::iow::ISA = __PACKAGE__;
1822@urxvt::pw::ISA = __PACKAGE__;
1823@urxvt::iw::ISA = __PACKAGE__;
1495 1824
1496=head2 The C<urxvt::timer> Class 1825=head2 The C<urxvt::timer> Class
1497 1826
1498This class implements timer watchers/events. Time is represented as a 1827This class implements timer watchers/events. Time is represented as a
1499fractional number of seconds since the epoch. Example: 1828fractional number of seconds since the epoch. Example:
1537Start the timer. 1866Start the timer.
1538 1867
1539=item $timer = $timer->start ($tstamp) 1868=item $timer = $timer->start ($tstamp)
1540 1869
1541Set the event trigger time to C<$tstamp> and start the timer. 1870Set the event trigger time to C<$tstamp> and start the timer.
1871
1872=item $timer = $timer->after ($delay)
1873
1874Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1542 1875
1543=item $timer = $timer->stop 1876=item $timer = $timer->stop
1544 1877
1545Stop the timer. 1878Stop the timer.
1546 1879
1593 1926
1594Stop watching for events on the given filehandle. 1927Stop watching for events on the given filehandle.
1595 1928
1596=back 1929=back
1597 1930
1931=head2 The C<urxvt::iw> Class
1932
1933This class implements idle watchers, that get called automatically when
1934the process is idle. They should return as fast as possible, after doing
1935some useful work.
1936
1937=over 4
1938
1939=item $iw = new urxvt::iw
1940
1941Create a new idle watcher object in stopped state.
1942
1943=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1944
1945Set the callback to be called when the watcher triggers.
1946
1947=item $timer = $timer->start
1948
1949Start the watcher.
1950
1951=item $timer = $timer->stop
1952
1953Stop the watcher.
1954
1955=back
1956
1957=head2 The C<urxvt::pw> Class
1958
1959This class implements process watchers. They create an event whenever a
1960process exits, after which they stop automatically.
1961
1962 my $pid = fork;
1963 ...
1964 $term->{pw} = urxvt::pw
1965 ->new
1966 ->start ($pid)
1967 ->cb (sub {
1968 my ($pw, $exit_status) = @_;
1969 ...
1970 });
1971
1972=over 4
1973
1974=item $pw = new urxvt::pw
1975
1976Create a new process watcher in stopped state.
1977
1978=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1979
1980Set the callback to be called when the timer triggers.
1981
1982=item $pw = $timer->start ($pid)
1983
1984Tells the wqtcher to start watching for process C<$pid>.
1985
1986=item $pw = $pw->stop
1987
1988Stop the watcher.
1989
1990=back
1991
1598=head1 ENVIRONMENT 1992=head1 ENVIRONMENT
1599 1993
1600=head2 URXVT_PERL_VERBOSITY 1994=head2 URXVT_PERL_VERBOSITY
1601 1995
1602This variable controls the verbosity level of the perl extension. Higher 1996This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines