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.39 by root, Fri Jan 6 05:28:55 2006 UTC vs.
Revision 1.76 by root, Tue Jan 10 19:46:28 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
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 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 45when the user extends selections (double-click). Right now, it tries to
46urls and complete shell-quoted arguments, which is very convenient, too, 46select urls and complete shell-quoted arguments, which is very convenient,
47if your F<ls> supports C<--quoting-style=shell>. 47too, if your F<ls> supports C<--quoting-style=shell>.
48 48
49It also offers the following bindable event: 49It also offers the following bindable keyboard command:
50 50
51=over 4 51=over 4
52 52
53=item rot13 53=item rot13
54 54
56 56
57 URxvt.keysym.C-M-r: perl:selection:rot13 57 URxvt.keysym.C-M-r: perl:selection:rot13
58 58
59=back 59=back
60 60
61=item option-popup (enabled by default)
62
63Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
64runtime.
65
66=item selection-popup (enabled by default)
67
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action (such as uri unescaping, perl
70evalution, web-browser starting etc.), depending on content.
71
72=item searchable-scrollback<hotkey> (enabled by default)
73
74Adds regex search functionality to the scrollback buffer, triggered
75by a hotkey (default: C<M-s>). When in search mode, normal terminal
76input/output is suspended.
77
78C</> starts an incremental regex search, C<n> searches further, C<p> or
79C<N> jump to the previous match, C<G> jumps to the bottom and clears the
80history, C<enter> leaves search mode at the current position and C<escape>
81returns to the original position.
82
61=item digital-clock 83=item digital-clock
62 84
63Displays a digital clock using the built-in overlay. 85Displays a digital clock using the built-in overlay.
64 86
65=item mark-urls 87=item mark-urls
66 88
67Uses per-line filtering (C<on_line_update>) to underline urls. 89Uses per-line display filtering (C<on_line_update>) to underline urls.
90
91=item block-graphics-to-ascii
92
93A not very useful example of filtering all text output to the terminal,
94by replacing all line-drawing characters (U+2500 .. U+259F) by a
95similar-looking ascii character.
68 96
69=item example-refresh-hooks 97=item example-refresh-hooks
70 98
71Displays a very simple digital clock in the upper right corner of the 99Displays a very simple digital clock in the upper right corner of the
72window. Illustrates overwriting the refresh callbacks to create your own 100window. Illustrates overwriting the refresh callbacks to create your own
73overlays or changes. 101overlays or changes.
74 102
75=item example-filter-input
76
77A not very useful example of filtering all text output to the terminal, by
78underlining all urls that matches a certain regex (i.e. some urls :). It
79is not very useful because urls that are output in multiple steps (e.g.
80when typing them) do not get marked.
81
82=back 103=back
104
105=head1 API DOCUMENTATION
83 106
84=head2 General API Considerations 107=head2 General API Considerations
85 108
86All objects (such as terminals, time watchers etc.) are typical 109All objects (such as terminals, time watchers etc.) are typical
87reference-to-hash objects. The hash can be used to store anything you 110reference-to-hash objects. The hash can be used to store anything you
115Either binary data or - more common - a text string encoded in a 138Either binary data or - more common - a text string encoded in a
116locale-specific way. 139locale-specific way.
117 140
118=back 141=back
119 142
143=head2 Extension Objects
144
145Very perl extension is a perl class. A separate perl object is created
146for each terminal and each extension and passed as the first parameter to
147hooks. So extensions can use their C<$self> object without having to think
148about other extensions, with the exception of methods and members that
149begin with an underscore character C<_>: these are reserved for internal
150use.
151
152Although it isn't a C<urxvt::term> object, you can call all methods of the
153C<urxvt::term> class on this object.
154
155It has the following methods and data members:
156
157=over 4
158
159=item $urxvt_term = $self->{term}
160
161Returns the C<urxvt::term> object associated with this instance of the
162extension. This member I<must not> be changed in any way.
163
164=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
165
166Dynamically enable the given hooks (named without the C<on_> prefix) for
167this extension, replacing any previous hook. This is useful when you want
168to overwrite time-critical hooks only temporarily.
169
170=item $self->disable ($hook_name[, $hook_name..])
171
172Dynamically disable the given hooks.
173
174=back
175
120=head2 Hooks 176=head2 Hooks
121 177
122The following subroutines can be declared in loaded scripts, and will be 178The following subroutines can be declared in extension files, and will be
123called whenever the relevant event happens. 179called whenever the relevant event happens.
124 180
125The first argument passed to them is an object private to each terminal 181The first argument passed to them is an extension oject as described in
126and extension package. You can call all C<urxvt::term> methods on it, but 182the in the C<Extension Objects> section.
127its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
128object that is shared between all packages is stored in the C<term>
129member.
130 183
131All of them must return a boolean value. If it is true, then the event 184B<All> of these hooks must return a boolean value. If it is true, then the
132counts as being I<consumed>, and the invocation of other hooks is skipped, 185event counts as being I<consumed>, and the invocation of other hooks is
133and the relevant action might not be carried out by the C++ code. 186skipped, and the relevant action might not be carried out by the C++ code.
134 187
135When in doubt, return a false value (preferably C<()>). 188I<< When in doubt, return a false value (preferably C<()>). >>
136 189
137=over 4 190=over 4
138 191
139=item on_init $term 192=item on_init $term
140 193
179should extend the selection itelf and return true to suppress the built-in 232should extend the selection itelf and return true to suppress the built-in
180processing. 233processing.
181 234
182See the F<selection> example extension. 235See the F<selection> example extension.
183 236
184=item on_focus_in $term
185
186Called whenever the window gets the keyboard focus, before urxvt does
187focus in processing.
188
189=item on_focus_out $term
190
191Called wheneever the window loses keyboard focus, before urxvt does focus
192out processing.
193
194=item on_view_change $term, $offset 237=item on_view_change $term, $offset
195 238
196Called whenever the view offset changes, i..e the user or program 239Called whenever the view offset changes, i..e the user or program
197scrolls. Offset C<0> means display the normal terminal, positive values 240scrolls. Offset C<0> means display the normal terminal, positive values
198show this many lines of scrollback. 241show this many lines of scrollback.
204than the scroll back buffer or the terminal. 247than the scroll back buffer or the terminal.
205 248
206It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 249It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
207$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 250$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
208number of lines that will be in the scrollback buffer. 251number of lines that will be in the scrollback buffer.
209
210=item on_tty_activity $term *NYI*
211
212Called whenever the program(s) running in the urxvt window send output.
213 252
214=item on_osc_seq $term, $string 253=item on_osc_seq $term, $string
215 254
216Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 255Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
217operating system command) is processed. Cursor position and other state 256operating system command) is processed. Cursor position and other state
230can filter/change and output the text yourself by returning a true value 269can filter/change and output the text yourself by returning a true value
231and calling C<< $term->scr_add_lines >> yourself. Please note that this 270and calling C<< $term->scr_add_lines >> yourself. Please note that this
232might be very slow, however, as your hook is called for B<all> text being 271might be very slow, however, as your hook is called for B<all> text being
233output. 272output.
234 273
274=item on_tt_write $term, $octets
275
276Called whenever some data is written to the tty/pty and can be used to
277suppress or filter tty input.
278
235=item on_line_update $term, $row 279=item on_line_update $term, $row
236 280
237Called whenever a line was updated or changed. Can be used to filter 281Called whenever a line was updated or changed. Can be used to filter
238screen output (e.g. underline urls or other useless stuff). Only lines 282screen output (e.g. underline urls or other useless stuff). Only lines
239that are being shown will be filtered, and, due to performance reasons, 283that are being shown will be filtered, and, due to performance reasons,
261 305
262Called whenever the user presses a key combination that has a 306Called whenever the user presses a key combination that has a
263C<perl:string> action bound to it (see description of the B<keysym> 307C<perl:string> action bound to it (see description of the B<keysym>
264resource in the @@RXVT_NAME@@(1) manpage). 308resource in the @@RXVT_NAME@@(1) manpage).
265 309
310=item on_focus_in $term
311
312Called whenever the window gets the keyboard focus, before rxvt-unicode
313does focus in processing.
314
315=item on_focus_out $term
316
317Called wheneever the window loses keyboard focus, before rxvt-unicode does
318focus out processing.
319
266=item on_key_press $term, $event, $octets 320=item on_key_press $term, $event, $keysym, $octets
267 321
268=item on_key_release $term, $event 322=item on_key_release $term, $event, $keysym
269 323
270=item on_button_press $term, $event 324=item on_button_press $term, $event
271 325
272=item on_button_release $term, $event 326=item on_button_release $term, $event
273 327
274=item on_motion_notify $term, $event 328=item on_motion_notify $term, $event
329
330=item on_map_notify $term, $event
331
332=item on_unmap_notify $term, $event
275 333
276Called whenever the corresponding X event is received for the terminal If 334Called whenever the corresponding X event is received for the terminal If
277the hook returns true, then the even will be ignored by rxvt-unicode. 335the hook returns true, then the even will be ignored by rxvt-unicode.
278 336
279The event is a hash with most values as named by Xlib (see the XEvent 337The event is a hash with most values as named by Xlib (see the XEvent
289 347
290=head2 Variables in the C<urxvt> Package 348=head2 Variables in the C<urxvt> Package
291 349
292=over 4 350=over 4
293 351
352=item $urxvt::LIBDIR
353
354The rxvt-unicode library directory, where, among other things, the perl
355modules and scripts are stored.
356
357=item $urxvt::RESCLASS, $urxvt::RESCLASS
358
359The resource class and name rxvt-unicode uses to look up X resources.
360
361=item $urxvt::RXVTNAME
362
363The basename of the installed binaries, usually C<urxvt>.
364
294=item $urxvt::TERM 365=item $urxvt::TERM
295 366
296The current terminal. Whenever a callback/Hook is bein executed, this 367The current terminal. This variable stores the current C<urxvt::term>
297variable stores the current C<urxvt::term> object. 368object, whenever a callback/hook is executing.
369
370=item
298 371
299=back 372=back
300 373
301=head2 Functions in the C<urxvt> Package 374=head2 Functions in the C<urxvt> Package
302 375
323that calls this function. 396that calls this function.
324 397
325Using this function has the advantage that its output ends up in the 398Using this function has the advantage that its output ends up in the
326correct place, e.g. on stderr of the connecting urxvtc client. 399correct place, e.g. on stderr of the connecting urxvtc client.
327 400
401=item $is_safe = urxvt::safe
402
403Returns true when it is safe to do potentially unsafe things, such as
404evaluating perl code specified by the user. This is true when urxvt was
405started setuid or setgid.
406
328=item $time = urxvt::NOW 407=item $time = urxvt::NOW
329 408
330Returns the "current time" (as per the event loop). 409Returns the "current time" (as per the event loop).
410
411=item urxvt::CurrentTime
412
413=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
414Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
415Button4Mask, Button5Mask, AnyModifier
416
417Various constants for use in X calls and event processing.
331 418
332=back 419=back
333 420
334=head2 RENDITION 421=head2 RENDITION
335 422
362 449
363=item $background = urxvt::GET_BASEBG $rend 450=item $background = urxvt::GET_BASEBG $rend
364 451
365Return the foreground/background colour index, respectively. 452Return the foreground/background colour index, respectively.
366 453
367=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 454=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
368 455
369=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 456=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
370 457
371Replace the foreground/background colour in the rendition mask with the 458Replace the foreground/background colour in the rendition mask with the
372specified one. 459specified one.
373 460
374=item $value = urxvt::GET_CUSTOM ($rend) 461=item $value = urxvt::GET_CUSTOM $rend
375 462
376Return the "custom" value: Every rendition has 5 bits for use by 463Return the "custom" value: Every rendition has 5 bits for use by
377extensions. They can be set and changed as you like and are initially 464extensions. They can be set and changed as you like and are initially
378zero. 465zero.
379 466
380=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 467=item $rend = urxvt::SET_CUSTOM $rend, $new_value
381 468
382Change the custom value. 469Change the custom value.
383 470
384=back 471=back
385 472
386=cut 473=cut
387 474
388package urxvt; 475package urxvt;
389 476
477use utf8;
390use strict; 478use strict;
479use Carp ();
391use Scalar::Util (); 480use Scalar::Util ();
481use List::Util ();
392 482
483our $VERSION = 1;
393our $TERM; 484our $TERM;
394our @HOOKNAME; 485our @HOOKNAME;
486our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
487our %OPTION;
488
395our $LIBDIR; 489our $LIBDIR;
490our $RESNAME;
491our $RESCLASS;
492our $RXVTNAME;
396 493
397BEGIN { 494BEGIN {
398 urxvt->bootstrap; 495 urxvt->bootstrap;
399 496
400 # overwrite perl's warn 497 # overwrite perl's warn
402 my $msg = join "", @_; 499 my $msg = join "", @_;
403 $msg .= "\n" 500 $msg .= "\n"
404 unless $msg =~ /\n$/; 501 unless $msg =~ /\n$/;
405 urxvt::warn ($msg); 502 urxvt::warn ($msg);
406 }; 503 };
504
505 delete $ENV{IFS};
506 delete $ENV{CDPATH};
507 delete $ENV{BASH_ENV};
508 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
407} 509}
408 510
409my @hook_count; 511my @hook_count;
410my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 512my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
411 513
412sub verbose { 514sub verbose {
413 my ($level, $msg) = @_; 515 my ($level, $msg) = @_;
414 warn "$msg\n" if $level <= $verbosity; 516 warn "$msg\n" if $level <= $verbosity;
415} 517}
416 518
417# find on_xxx subs in the package and register them 519my $extension_pkg = "extension0000";
418# as hooks 520my %extension_pkg;
419sub register_package($) {
420 my ($pkg) = @_;
421
422 for my $htype (0.. $#HOOKNAME) {
423 my $name = $HOOKNAME[$htype];
424
425 my $ref = $pkg->can ("on_" . lc $name)
426 or next;
427
428 $TERM->{_hook}[$htype]{$pkg} = $ref;
429 $hook_count[$htype]++
430 or set_should_invoke $htype, 1;
431 }
432}
433
434my $script_pkg = "script0000";
435my %script_pkg;
436 521
437# load a single script into its own package, once only 522# load a single script into its own package, once only
438sub script_package($) { 523sub extension_package($) {
439 my ($path) = @_; 524 my ($path) = @_;
440 525
441 $script_pkg{$path} ||= do { 526 $extension_pkg{$path} ||= do {
442 my $pkg = "urxvt::" . ($script_pkg++); 527 my $pkg = "urxvt::" . ($extension_pkg++);
443 528
444 verbose 3, "loading script '$path' into package '$pkg'"; 529 verbose 3, "loading extension '$path' into package '$pkg'";
445 530
446 open my $fh, "<:raw", $path 531 open my $fh, "<:raw", $path
447 or die "$path: $!"; 532 or die "$path: $!";
448 533
534 my $source = untaint
449 my $source = "package $pkg; use strict; use utf8;\n" 535 "package $pkg; use strict; use utf8;\n"
536 . "use base urxvt::term::extension::;\n"
450 . "#line 1 \"$path\"\n{\n" 537 . "#line 1 \"$path\"\n{\n"
451 . (do { local $/; <$fh> }) 538 . (do { local $/; <$fh> })
452 . "\n};\n1"; 539 . "\n};\n1";
453 540
541 eval $source
454 eval $source or die "$path: $@"; 542 or die "$path: $@";
455 543
456 $pkg 544 $pkg
457 } 545 }
458} 546}
459 547
464 local $TERM = shift; 552 local $TERM = shift;
465 my $htype = shift; 553 my $htype = shift;
466 554
467 if ($htype == 0) { # INIT 555 if ($htype == 0) { # INIT
468 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 556 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
557
558 my %ext_arg;
469 559
470 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 560 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
561 if ($_ eq "default") {
562 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
563 } elsif (/^-(.*)$/) {
564 delete $ext_arg{$1};
565 } elsif (/^([^<]+)<(.*)>$/) {
566 push @{ $ext_arg{$1} }, $2;
567 } else {
568 $ext_arg{$_} ||= [];
569 }
570 }
571
572 while (my ($ext, $argv) = each %ext_arg) {
471 my @files = grep -f $_, map "$_/$ext", @dirs; 573 my @files = grep -f $_, map "$_/$ext", @dirs;
472 574
473 if (@files) { 575 if (@files) {
474 register_package script_package $files[0]; 576 $TERM->register_package (extension_package $files[0], $argv);
475 } else { 577 } else {
476 warn "perl extension '$ext' not found in perl library search path\n"; 578 warn "perl extension '$ext' not found in perl library search path\n";
477 } 579 }
478 } 580 }
581
582 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
583 warn $@ if $@;
479 } 584 }
480 585
481 $retval = undef; 586 $retval = undef;
482 587
483 if (my $cb = $TERM->{_hook}[$htype]) { 588 if (my $cb = $TERM->{_hook}[$htype]) {
485 if $verbosity >= 10; 590 if $verbosity >= 10;
486 591
487 keys %$cb; 592 keys %$cb;
488 593
489 while (my ($pkg, $cb) = each %$cb) { 594 while (my ($pkg, $cb) = each %$cb) {
490 $retval = $cb->( 595 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
491 $TERM->{_pkg}{$pkg} ||= do {
492 my $proxy = bless { }, urxvt::term::proxy::;
493 Scalar::Util::weaken ($proxy->{term} = $TERM);
494 $proxy
495 },
496 @_,
497 ) and last; 596 and last;
597
598 if ($@) {
599 $TERM->ungrab; # better to lose the grab than the session
600 warn $@;
601 }
498 } 602 }
499 } 603 }
500 604
501 if ($htype == 1) { # DESTROY 605 if ($htype == 1) { # DESTROY
502 # remove hooks if unused
503 if (my $hook = $TERM->{_hook}) { 606 if (my $hook = delete $TERM->{_hook}) {
504 for my $htype (0..$#$hook) { 607 for my $htype (0..$#$hook) {
505 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 608 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
506 or set_should_invoke $htype, 0; 609 or set_should_invoke $htype, 0;
507 } 610 }
508 } 611 }
515 } 618 }
516 619
517 $retval 620 $retval
518} 621}
519 622
520sub urxvt::term::proxy::AUTOLOAD { 623# urxvt::term::extension
521 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 624
625package urxvt::term::extension;
626
627sub enable {
628 my ($self, %hook) = @_;
629 my $pkg = $self->{_pkg};
630
631 while (my ($name, $cb) = each %hook) {
632 my $htype = $HOOKTYPE{uc $name};
633 defined $htype
634 or Carp::croak "unsupported hook type '$name'";
635
636 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
637 $hook_count[$htype]++
638 or urxvt::set_should_invoke $htype, 1;
639 }
640
641 $self->{term}{_hook}[$htype]{$pkg} = $cb;
642 }
643}
644
645sub disable {
646 my ($self, @hook) = @_;
647 my $pkg = $self->{_pkg};
648
649 for my $name (@hook) {
650 my $htype = $HOOKTYPE{uc $name};
651 defined $htype
652 or Carp::croak "unsupported hook type '$name'";
653
654 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
655 --$hook_count[$htype]
656 or urxvt::set_should_invoke $htype, 0;
657 }
658 }
659}
660
661our $AUTOLOAD;
662
663sub AUTOLOAD {
664 $AUTOLOAD =~ /:([^:]+)$/
522 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 665 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
523 666
524 eval qq{ 667 eval qq{
525 sub $urxvt::term::proxy::AUTOLOAD { 668 sub $AUTOLOAD {
526 my \$proxy = shift; 669 my \$proxy = shift;
527 \$proxy->{term}->$1 (\@_) 670 \$proxy->{term}->$1 (\@_)
528 } 671 }
529 1 672 1
530 } or die "FATAL: unable to compile method forwarder: $@"; 673 } or die "FATAL: unable to compile method forwarder: $@";
531 674
532 goto &$urxvt::term::proxy::AUTOLOAD; 675 goto &$AUTOLOAD;
533} 676}
677
678sub DESTROY {
679 # nop
680}
681
682# urxvt::destroy_hook
683
684sub urxvt::destroy_hook::DESTROY {
685 ${$_[0]}->();
686}
687
688sub urxvt::destroy_hook(&) {
689 bless \shift, urxvt::destroy_hook::
690}
691
692package urxvt::anyevent;
693
694=head2 The C<urxvt::anyevent> Class
695
696The sole purpose of this class is to deliver an interface to the
697C<AnyEvent> module - any module using it will work inside urxvt without
698further programming. The only exception is that you cannot wait on
699condition variables, but non-blocking condvar use is ok. What this means
700is that you cannot use blocking APIs, but the non-blocking variant should
701work.
702
703=cut
704
705our $VERSION = 1;
706
707$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
708push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
709
710sub timer {
711 my ($class, %arg) = @_;
712
713 my $cb = $arg{cb};
714
715 urxvt::timer
716 ->new
717 ->start (urxvt::NOW + $arg{after})
718 ->cb (sub {
719 $_[0]->stop; # need to cancel manually
720 $cb->();
721 })
722}
723
724sub io {
725 my ($class, %arg) = @_;
726
727 my $cb = $arg{cb};
728
729 bless [$arg{fh}, urxvt::iow
730 ->new
731 ->fd (fileno $arg{fh})
732 ->events (($arg{poll} =~ /r/ ? 1 : 0)
733 | ($arg{poll} =~ /w/ ? 2 : 0))
734 ->start
735 ->cb (sub {
736 $cb->(($_[1] & 1 ? 'r' : '')
737 . ($_[1] & 2 ? 'w' : ''));
738 })],
739 urxvt::anyevent::
740}
741
742sub DESTROY {
743 $_[0][1]->stop;
744}
745
746sub condvar {
747 bless \my $flag, urxvt::anyevent::condvar::
748}
749
750sub urxvt::anyevent::condvar::broadcast {
751 ${$_[0]}++;
752}
753
754sub urxvt::anyevent::condvar::wait {
755 unless (${$_[0]}) {
756 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
757 }
758}
759
760package urxvt::term;
534 761
535=head2 The C<urxvt::term> Class 762=head2 The C<urxvt::term> Class
536 763
537=over 4 764=over 4
538 765
766=cut
767
768# find on_xxx subs in the package and register them
769# as hooks
770sub register_package {
771 my ($self, $pkg, $argv) = @_;
772
773 my $proxy = bless {
774 _pkg => $pkg,
775 argv => $argv,
776 }, $pkg;
777 Scalar::Util::weaken ($proxy->{term} = $self);
778
779 $self->{_pkg}{$pkg} = $proxy;
780
781 for my $name (@HOOKNAME) {
782 if (my $ref = $pkg->can ("on_" . lc $name)) {
783 $proxy->enable ($name => $ref);
784 }
785 }
786}
787
539=item $term->destroy 788=item $term->destroy
540 789
541Destroy the terminal object (close the window, free resources etc.). 790Destroy the terminal object (close the window, free resources
791etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
792watchers (timers, io watchers) are still active.
793
794=item $isset = $term->option ($optval[, $set])
795
796Returns true if the option specified by C<$optval> is enabled, and
797optionally change it. All option values are stored by name in the hash
798C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
799
800Here is a a likely non-exhaustive list of option names, please see the
801source file F</src/optinc.h> to see the actual list:
802
803 borderLess console cursorBlink cursorUnderline hold iconic insecure
804 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
805 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
806 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
807 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
808 tripleclickwords utmpInhibit visualBell
542 809
543=item $value = $term->resource ($name[, $newval]) 810=item $value = $term->resource ($name[, $newval])
544 811
545Returns the current resource value associated with a given name and 812Returns the current resource value associated with a given name and
546optionally sets a new value. Setting values is most useful in the C<init> 813optionally sets a new value. Setting values is most useful in the C<init>
556 823
557Please note that resource strings will currently only be freed when the 824Please note that resource strings will currently only be freed when the
558terminal is destroyed, so changing options frequently will eat memory. 825terminal is destroyed, so changing options frequently will eat memory.
559 826
560Here is a a likely non-exhaustive list of resource names, not all of which 827Here is a a likely non-exhaustive list of resource names, not all of which
561are supported in every build, please see the source to see the actual 828are supported in every build, please see the source file F</src/rsinc.h>
562list: 829to see the actual list:
563 830
564 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 831 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
565 borderLess color cursorBlink cursorUnderline cutchars delete_key 832 borderLess color cursorBlink cursorUnderline cutchars delete_key
566 display_name embed ext_bwidth fade font geometry hold iconName 833 display_name embed ext_bwidth fade font geometry hold iconName
567 imFont imLocale inputMethod insecure int_bwidth intensityStyles 834 imFont imLocale inputMethod insecure int_bwidth intensityStyles
574 shade term_name title transparent transparent_all tripleclickwords 841 shade term_name title transparent transparent_all tripleclickwords
575 utmpInhibit visualBell 842 utmpInhibit visualBell
576 843
577=cut 844=cut
578 845
579sub urxvt::term::resource($$;$) { 846sub resource($$;$) {
580 my ($self, $name) = (shift, shift); 847 my ($self, $name) = (shift, shift);
581 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 848 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
582 goto &urxvt::term::_resource; 849 &urxvt::term::_resource
583} 850}
851
852=item $success = $term->parse_keysym ($keysym_spec, $command_string)
853
854Adds a keymap translation exactly as specified via a resource. See the
855C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
584 856
585=item $rend = $term->rstyle ([$new_rstyle]) 857=item $rend = $term->rstyle ([$new_rstyle])
586 858
587Return and optionally change the current rendition. Text that is output by 859Return and optionally change the current rendition. Text that is output by
588the terminal application will use this style. 860the terminal application will use this style.
608 880
609=item $oldtext = $term->selection ([$newtext]) 881=item $oldtext = $term->selection ([$newtext])
610 882
611Return the current selection text and optionally replace it by C<$newtext>. 883Return the current selection text and optionally replace it by C<$newtext>.
612 884
613#=item $term->overlay ($x, $y, $text) 885=item $term->overlay_simple ($x, $y, $text)
614# 886
615#Create a simple multi-line overlay box. See the next method for details. 887Create a simple multi-line overlay box. See the next method for details.
616# 888
617#=cut 889=cut
618# 890
619#sub urxvt::term::scr_overlay { 891sub overlay_simple {
620# my ($self, $x, $y, $text) = @_; 892 my ($self, $x, $y, $text) = @_;
621# 893
622# my @lines = split /\n/, $text; 894 my @lines = split /\n/, $text;
623# 895
624# my $w = 0; 896 my $w = List::Util::max map $self->strwidth ($_), @lines;
625# for (map $self->strwidth ($_), @lines) { 897
626# $w = $_ if $w < $_;
627# }
628#
629# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 898 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
630# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 899 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
631#} 900
901 $overlay
902}
632 903
633=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 904=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
634 905
635Create a new (empty) overlay at the given position with the given 906Create a new (empty) overlay at the given position with the given
636width/height. C<$rstyle> defines the initial rendition style 907width/height. C<$rstyle> defines the initial rendition style
663 934
664If hidden, display the overlay again. 935If hidden, display the overlay again.
665 936
666=back 937=back
667 938
939=item $popup = $term->popup ($event)
940
941Creates a new C<urxvt::popup> object that implements a popup menu. The
942C<$event> I<must> be the event causing the menu to pop up (a button event,
943currently).
944
945=cut
946
947sub popup {
948 my ($self, $event) = @_;
949
950 $self->grab ($event->{time}, 1)
951 or return;
952
953 my $popup = bless {
954 term => $self,
955 event => $event,
956 }, urxvt::popup::;
957
958 Scalar::Util::weaken $popup->{term};
959
960 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
961 Scalar::Util::weaken $self->{_destroy}{$popup};
962
963 $popup
964}
965
668=item $cellwidth = $term->strwidth $string 966=item $cellwidth = $term->strwidth ($string)
669 967
670Returns the number of screen-cells this string would need. Correctly 968Returns the number of screen-cells this string would need. Correctly
671accounts for wide and combining characters. 969accounts for wide and combining characters.
672 970
673=item $octets = $term->locale_encode $string 971=item $octets = $term->locale_encode ($string)
674 972
675Convert the given text string into the corresponding locale encoding. 973Convert the given text string into the corresponding locale encoding.
676 974
677=item $string = $term->locale_decode $octets 975=item $string = $term->locale_decode ($octets)
678 976
679Convert the given locale-encoded octets into a perl string. 977Convert the given locale-encoded octets into a perl string.
978
979=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
980
981XORs the rendition values in the given span with the provided value
982(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
983to the selection.
984
985=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
986
987Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
988whitespace will additionally be xored with the C<$rstyle2>, which defaults
989to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
990it instead.
991
992=item $term->scr_bell
993
994Ring the bell!
680 995
681=item $term->scr_add_lines ($string) 996=item $term->scr_add_lines ($string)
682 997
683Write the given text string to the screen, as if output by the application 998Write the given text string to the screen, as if output by the application
684running inside the terminal. It may not contain command sequences (escape 999running inside the terminal. It may not contain command sequences (escape
699 1014
700Write the octets given in C<$data> to the tty (i.e. as program input). To 1015Write the octets given in C<$data> to the tty (i.e. as program input). To
701pass characters instead of octets, you should convert your strings first 1016pass characters instead of octets, you should convert your strings first
702to the locale-specific encoding using C<< $term->locale_encode >>. 1017to the locale-specific encoding using C<< $term->locale_encode >>.
703 1018
1019=item $old_events = $term->pty_ev_events ([$new_events])
1020
1021Replaces the event mask of the pty watcher by the given event mask. Can
1022be used to suppress input and output handling to the pty/tty. See the
1023description of C<< urxvt::timer->events >>. Make sure to always restore
1024the previous value.
1025
1026=item $windowid = $term->parent
1027
1028Return the window id of the toplevel window.
1029
1030=item $windowid = $term->vt
1031
1032Return the window id of the terminal window.
1033
704=item $window_width = $term->width 1034=item $window_width = $term->width
705 1035
706=item $window_height = $term->height 1036=item $window_height = $term->height
707 1037
708=item $font_width = $term->fwidth 1038=item $font_width = $term->fwidth
724=item $nrow_plus_saveLines = $term->total_rows 1054=item $nrow_plus_saveLines = $term->total_rows
725 1055
726=item $lines_in_scrollback = $term->nsaved 1056=item $lines_in_scrollback = $term->nsaved
727 1057
728Return various integers describing terminal characteristics. 1058Return various integers describing terminal characteristics.
1059
1060=item $lc_ctype = $term->locale
1061
1062Returns the LC_CTYPE category string used by this rxvt-unicode.
1063
1064=item $x_display = $term->display_id
1065
1066Return the DISPLAY used by rxvt-unicode.
1067
1068=item $modifiermask = $term->ModLevel3Mask
1069
1070=item $modifiermask = $term->ModMetaMask
1071
1072=item $modifiermask = $term->ModNumLockMask
1073
1074Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1075AltGr), the meta key (often Alt) and the num lock key, if applicable.
729 1076
730=item $view_start = $term->view_start ([$newvalue]) 1077=item $view_start = $term->view_start ([$newvalue])
731 1078
732Returns the negative row number of the topmost line. Minimum value is 1079Returns the negative row number of the topmost line. Minimum value is
733C<0>, which displays the normal terminal contents. Larger values scroll 1080C<0>, which displays the normal terminal contents. Larger values scroll
827 1174
828=back 1175=back
829 1176
830=cut 1177=cut
831 1178
832sub urxvt::term::line { 1179sub line {
833 my ($self, $row) = @_; 1180 my ($self, $row) = @_;
834 1181
835 my $maxrow = $self->nrow - 1; 1182 my $maxrow = $self->nrow - 1;
836 1183
837 my ($beg, $end) = ($row, $row); 1184 my ($beg, $end) = ($row, $row);
901 $offset / $self->{ncol} + $self->{beg}, 1248 $offset / $self->{ncol} + $self->{beg},
902 $offset % $self->{ncol} 1249 $offset % $self->{ncol}
903 ) 1250 )
904} 1251}
905 1252
906=item ($row, $col) = $line->coord_of ($offset)
907=item $text = $term->special_encode $string 1253=item $text = $term->special_encode $string
908 1254
909Converts a perl string into the special encoding used by rxvt-unicode, 1255Converts a perl string into the special encoding used by rxvt-unicode,
910where one character corresponds to one screen cell. See 1256where one character corresponds to one screen cell. See
911C<< $term->ROW_t >> for details. 1257C<< $term->ROW_t >> for details.
913=item $string = $term->special_decode $text 1259=item $string = $term->special_decode $text
914 1260
915Converts rxvt-unicodes text reprsentation into a perl string. See 1261Converts rxvt-unicodes text reprsentation into a perl string. See
916C<< $term->ROW_t >> for details. 1262C<< $term->ROW_t >> for details.
917 1263
1264=item $success = $term->grab_button ($button, $modifiermask)
1265
1266Registers a synchronous button grab. See the XGrabButton manpage.
1267
1268=item $success = $term->grab ($eventtime[, $sync])
1269
1270Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1271synchronous (C<$sync> is true). Also remembers the grab timestampe.
1272
1273=item $term->allow_events_async
1274
1275Calls XAllowEvents with AsyncBoth for the most recent grab.
1276
1277=item $term->allow_events_sync
1278
1279Calls XAllowEvents with SyncBoth for the most recent grab.
1280
1281=item $term->allow_events_replay
1282
1283Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1284recent grab.
1285
1286=item $term->ungrab
1287
1288Calls XUngrab for the most recent grab. Is called automatically on
1289evaluation errors, as it is better to lose the grab in the error case as
1290the session.
1291
918=back 1292=back
1293
1294=cut
1295
1296package urxvt::popup;
1297
1298=head2 The C<urxvt::popup> Class
1299
1300=over 4
1301
1302=cut
1303
1304sub add_item {
1305 my ($self, $item) = @_;
1306
1307 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1308 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1309 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1310
1311 $item->{render} ||= sub { $_[0]{text} };
1312
1313 push @{ $self->{item} }, $item;
1314}
1315
1316=item $popup->add_title ($title)
1317
1318Adds a non-clickable title to the popup.
1319
1320=cut
1321
1322sub add_title {
1323 my ($self, $title) = @_;
1324
1325 $self->add_item ({
1326 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1327 text => $title,
1328 activate => sub { },
1329 });
1330}
1331
1332=item $popup->add_separator ([$sepchr])
1333
1334Creates a separator, optionally using the character given as C<$sepchr>.
1335
1336=cut
1337
1338sub add_separator {
1339 my ($self, $sep) = @_;
1340
1341 $sep ||= "=";
1342
1343 $self->add_item ({
1344 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1345 text => "",
1346 render => sub { $sep x $self->{term}->ncol },
1347 activate => sub { },
1348 });
1349}
1350
1351=item $popup->add_button ($text, $cb)
1352
1353Adds a clickable button to the popup. C<$cb> is called whenever it is
1354selected.
1355
1356=cut
1357
1358sub add_button {
1359 my ($self, $text, $cb) = @_;
1360
1361 $self->add_item ({ type => "button", text => $text, activate => $cb});
1362}
1363
1364=item $popup->add_toggle ($text, $cb, $initial_value)
1365
1366Adds a toggle/checkbox item to the popup. Teh callback gets called
1367whenever it gets toggled, with a boolean indicating its value as its first
1368argument.
1369
1370=cut
1371
1372sub add_toggle {
1373 my ($self, $text, $cb, $value) = @_;
1374
1375 my $item; $item = {
1376 type => "button",
1377 text => " $text",
1378 value => $value,
1379 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1380 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1381 };
1382
1383 $self->add_item ($item);
1384}
1385
1386=item $popup->show
1387
1388Displays the popup (which is initially hidden).
1389
1390=cut
1391
1392sub show {
1393 my ($self) = @_;
1394
1395 local $urxvt::popup::self = $self;
1396
1397 local $ENV{LC_ALL} = $self->{term}->locale;
1398
1399 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1400 "--transient-for" => $self->{term}->parent,
1401 "-display" => $self->{term}->display_id,
1402 "-pe" => "urxvt-popup")
1403 or die "unable to create popup window\n";
1404}
1405
1406sub DESTROY {
1407 my ($self) = @_;
1408
1409 delete $self->{term}{_destroy}{$self};
1410 $self->{term}->ungrab;
1411}
919 1412
920=head2 The C<urxvt::timer> Class 1413=head2 The C<urxvt::timer> Class
921 1414
922This class implements timer watchers/events. Time is represented as a 1415This class implements timer watchers/events. Time is represented as a
923fractional number of seconds since the epoch. Example: 1416fractional number of seconds since the epoch. Example:
976 1469
977 $term->{socket} = ... 1470 $term->{socket} = ...
978 $term->{iow} = urxvt::iow 1471 $term->{iow} = urxvt::iow
979 ->new 1472 ->new
980 ->fd (fileno $term->{socket}) 1473 ->fd (fileno $term->{socket})
981 ->events (1) # wait for read data 1474 ->events (urxvt::EVENT_READ)
982 ->start 1475 ->start
983 ->cb (sub { 1476 ->cb (sub {
984 my ($iow, $revents) = @_; 1477 my ($iow, $revents) = @_;
985 # $revents must be 1 here, no need to check 1478 # $revents must be 1 here, no need to check
986 sysread $term->{socket}, my $buf, 8192 1479 sysread $term->{socket}, my $buf, 8192
1003 1496
1004Set the filedescriptor (not handle) to watch. 1497Set the filedescriptor (not handle) to watch.
1005 1498
1006=item $iow = $iow->events ($eventmask) 1499=item $iow = $iow->events ($eventmask)
1007 1500
1008Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1501Set the event mask to watch. The only allowed values are
1009data, Bit #1 (value C<2>) enables watching for write data. 1502C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1503together, or C<urxvt::EVENT_NONE>.
1010 1504
1011=item $iow = $iow->start 1505=item $iow = $iow->start
1012 1506
1013Start watching for requested events on the given handle. 1507Start watching for requested events on the given handle.
1014 1508
1025This variable controls the verbosity level of the perl extension. Higher 1519This variable controls the verbosity level of the perl extension. Higher
1026numbers indicate more verbose output. 1520numbers indicate more verbose output.
1027 1521
1028=over 4 1522=over 4
1029 1523
1030=item =0 - only fatal messages 1524=item == 0 - fatal messages
1031 1525
1032=item =3 - script loading and management 1526=item >= 3 - script loading and management
1033 1527
1034=item =10 - all events received 1528=item >=10 - all events received
1035 1529
1036=back 1530=back
1037 1531
1038=head1 AUTHOR 1532=head1 AUTHOR
1039 1533

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines