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.52 by root, Sun Jan 8 00:48:14 2006 UTC vs.
Revision 1.83 by root, Thu Jan 12 01:38:37 2006 UTC

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 display filtering (C<on_line_update>) to underline urls. 89Uses per-line display filtering (C<on_line_update>) to underline urls and
90make them clickable. When middle-clicked, the program specified in the
91resource C<urlLauncher> (default C<x-www-browser>) will be started.
68 92
69=item block-graphics-to-ascii 93=item block-graphics-to-ascii
70 94
71A not very useful example of filtering all text output to the terminal, 95A not very useful example of filtering all text output to the terminal,
72by replacing all line-drawing characters (U+2500 .. U+259F) by a 96by replacing all line-drawing characters (U+2500 .. U+259F) by a
77Displays a very simple digital clock in the upper right corner of the 101Displays a very simple digital clock in the upper right corner of the
78window. Illustrates overwriting the refresh callbacks to create your own 102window. Illustrates overwriting the refresh callbacks to create your own
79overlays or changes. 103overlays or changes.
80 104
81=back 105=back
106
107=head1 API DOCUMENTATION
82 108
83=head2 General API Considerations 109=head2 General API Considerations
84 110
85All objects (such as terminals, time watchers etc.) are typical 111All objects (such as terminals, time watchers etc.) are typical
86reference-to-hash objects. The hash can be used to store anything you 112reference-to-hash objects. The hash can be used to store anything you
99=over 4 125=over 4
100 126
101=item $text 127=item $text
102 128
103Rxvt-unicodes special way of encoding text, where one "unicode" character 129Rxvt-unicodes special way of encoding text, where one "unicode" character
104always represents one screen cell. See L<row_t> for a discussion of this format. 130always represents one screen cell. See L<ROW_t> for a discussion of this format.
105 131
106=item $string 132=item $string
107 133
108A perl text string, with an emphasis on I<text>. It can store all unicode 134A perl text string, with an emphasis on I<text>. It can store all unicode
109characters and is to be distinguished with text encoded in a specific 135characters and is to be distinguished with text encoded in a specific
114Either binary data or - more common - a text string encoded in a 140Either binary data or - more common - a text string encoded in a
115locale-specific way. 141locale-specific way.
116 142
117=back 143=back
118 144
145=head2 Extension Objects
146
147Very perl extension is a perl class. A separate perl object is created
148for each terminal and each extension and passed as the first parameter to
149hooks. So extensions can use their C<$self> object without having to think
150about other extensions, with the exception of methods and members that
151begin with an underscore character C<_>: these are reserved for internal
152use.
153
154Although it isn't a C<urxvt::term> object, you can call all methods of the
155C<urxvt::term> class on this object.
156
157It has the following methods and data members:
158
159=over 4
160
161=item $urxvt_term = $self->{term}
162
163Returns the C<urxvt::term> object associated with this instance of the
164extension. This member I<must not> be changed in any way.
165
166=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
167
168Dynamically enable the given hooks (named without the C<on_> prefix) for
169this extension, replacing any previous hook. This is useful when you want
170to overwrite time-critical hooks only temporarily.
171
172=item $self->disable ($hook_name[, $hook_name..])
173
174Dynamically disable the given hooks.
175
176=back
177
119=head2 Hooks 178=head2 Hooks
120 179
121The following subroutines can be declared in extension files, and will be 180The following subroutines can be declared in extension files, and will be
122called whenever the relevant event happens. 181called whenever the relevant event happens.
123 182
124The first argument passed to them is an object private to each terminal 183The first argument passed to them is an extension oject as described in
125and extension package. You can call all C<urxvt::term> methods on it, but 184the in the C<Extension Objects> section.
126its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
127object that is shared between all packages is stored in the C<term>
128member. It is, however, blessed intot he package of the extension script,
129so for all practical purposes you can treat an extension script as a class.
130 185
131All of them must return a boolean value. If it is true, then the event 186B<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, 187event 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. 188skipped, and the relevant action might not be carried out by the C++ code.
134 189
135When in doubt, return a false value (preferably C<()>). 190I<< When in doubt, return a false value (preferably C<()>). >>
136 191
137=over 4 192=over 4
138 193
139=item on_init $term 194=item on_init $term
140 195
194than the scroll back buffer or the terminal. 249than the scroll back buffer or the terminal.
195 250
196It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 251It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
197$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 252$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
198number of lines that will be in the scrollback buffer. 253number of lines that will be in the scrollback buffer.
199
200=item on_tty_activity $term *NYI*
201
202Called whenever the program(s) running in the urxvt window send output.
203 254
204=item on_osc_seq $term, $string 255=item on_osc_seq $term, $string
205 256
206Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 257Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
207operating system command) is processed. Cursor position and other state 258operating system command) is processed. Cursor position and other state
220can filter/change and output the text yourself by returning a true value 271can filter/change and output the text yourself by returning a true value
221and calling C<< $term->scr_add_lines >> yourself. Please note that this 272and calling C<< $term->scr_add_lines >> yourself. Please note that this
222might be very slow, however, as your hook is called for B<all> text being 273might be very slow, however, as your hook is called for B<all> text being
223output. 274output.
224 275
276=item on_tt_write $term, $octets
277
278Called whenever some data is written to the tty/pty and can be used to
279suppress or filter tty input.
280
225=item on_line_update $term, $row 281=item on_line_update $term, $row
226 282
227Called whenever a line was updated or changed. Can be used to filter 283Called whenever a line was updated or changed. Can be used to filter
228screen output (e.g. underline urls or other useless stuff). Only lines 284screen output (e.g. underline urls or other useless stuff). Only lines
229that are being shown will be filtered, and, due to performance reasons, 285that are being shown will be filtered, and, due to performance reasons,
261=item on_focus_out $term 317=item on_focus_out $term
262 318
263Called wheneever the window loses keyboard focus, before rxvt-unicode does 319Called wheneever the window loses keyboard focus, before rxvt-unicode does
264focus out processing. 320focus out processing.
265 321
266=item on_key_press $term, $event, $octets 322=item on_key_press $term, $event, $keysym, $octets
267 323
268=item on_key_release $term, $event 324=item on_key_release $term, $event, $keysym
269 325
270=item on_button_press $term, $event 326=item on_button_press $term, $event
271 327
272=item on_button_release $term, $event 328=item on_button_release $term, $event
273 329
289 345
290subwindow. 346subwindow.
291 347
292=back 348=back
293 349
350=cut
351
352package urxvt;
353
354use utf8;
355use strict;
356use Carp ();
357use Scalar::Util ();
358use List::Util ();
359
360our $VERSION = 1;
361our $TERM;
362our @HOOKNAME;
363our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
364our %OPTION;
365
366our $LIBDIR;
367our $RESNAME;
368our $RESCLASS;
369our $RXVTNAME;
370
294=head2 Variables in the C<urxvt> Package 371=head2 Variables in the C<urxvt> Package
295 372
296=over 4 373=over 4
374
375=item $urxvt::LIBDIR
376
377The rxvt-unicode library directory, where, among other things, the perl
378modules and scripts are stored.
379
380=item $urxvt::RESCLASS, $urxvt::RESCLASS
381
382The resource class and name rxvt-unicode uses to look up X resources.
383
384=item $urxvt::RXVTNAME
385
386The basename of the installed binaries, usually C<urxvt>.
297 387
298=item $urxvt::TERM 388=item $urxvt::TERM
299 389
300The current terminal. This variable stores the current C<urxvt::term> 390The current terminal. This variable stores the current C<urxvt::term>
301object, whenever a callback/hook is executing. 391object, whenever a callback/hook is executing.
303=back 393=back
304 394
305=head2 Functions in the C<urxvt> Package 395=head2 Functions in the C<urxvt> Package
306 396
307=over 4 397=over 4
308
309=item $term = new urxvt [arg...]
310
311Creates a new terminal, very similar as if you had started it with
312C<system $binfile, arg...>. Croaks (and probably outputs an error message)
313if the new instance couldn't be created. Returns C<undef> if the new
314instance didn't initialise perl, and the terminal object otherwise. The
315C<init> and C<start> hooks will be called during the call.
316 398
317=item urxvt::fatal $errormessage 399=item urxvt::fatal $errormessage
318 400
319Fatally aborts execution with the given error message. Avoid at all 401Fatally aborts execution with the given error message. Avoid at all
320costs! The only time this is acceptable is when the terminal process 402costs! The only time this is acceptable is when the terminal process
327that calls this function. 409that calls this function.
328 410
329Using this function has the advantage that its output ends up in the 411Using this function has the advantage that its output ends up in the
330correct place, e.g. on stderr of the connecting urxvtc client. 412correct place, e.g. on stderr of the connecting urxvtc client.
331 413
414Messages have a size limit of 1023 bytes currently.
415
416=item $is_safe = urxvt::safe
417
418Returns true when it is safe to do potentially unsafe things, such as
419evaluating perl code specified by the user. This is true when urxvt was
420started setuid or setgid.
421
332=item $time = urxvt::NOW 422=item $time = urxvt::NOW
333 423
334Returns the "current time" (as per the event loop). 424Returns the "current time" (as per the event loop).
335 425
336=item urxvt::CurrentTime 426=item urxvt::CurrentTime
337 427
338=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 428=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
339Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 429Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
340Button4Mask, Button5Mask, AnyModifier 430Button4Mask, Button5Mask, AnyModifier
341 431
342Various constants for use in X events. 432Various constants for use in X calls and event processing.
343 433
344=back 434=back
345 435
346=head2 RENDITION 436=head2 RENDITION
347 437
374 464
375=item $background = urxvt::GET_BASEBG $rend 465=item $background = urxvt::GET_BASEBG $rend
376 466
377Return the foreground/background colour index, respectively. 467Return the foreground/background colour index, respectively.
378 468
379=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 469=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
380 470
381=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 471=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
382 472
383Replace the foreground/background colour in the rendition mask with the 473Replace the foreground/background colour in the rendition mask with the
384specified one. 474specified one.
385 475
386=item $value = urxvt::GET_CUSTOM ($rend) 476=item $value = urxvt::GET_CUSTOM $rend
387 477
388Return the "custom" value: Every rendition has 5 bits for use by 478Return the "custom" value: Every rendition has 5 bits for use by
389extensions. They can be set and changed as you like and are initially 479extensions. They can be set and changed as you like and are initially
390zero. 480zero.
391 481
392=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 482=item $rend = urxvt::SET_CUSTOM $rend, $new_value
393 483
394Change the custom value. 484Change the custom value.
395 485
396=back 486=back
397 487
398=cut 488=cut
399
400package urxvt;
401
402use utf8;
403use strict;
404use Scalar::Util ();
405use List::Util ();
406
407our $TERM;
408our @HOOKNAME;
409our %OPTION;
410our $LIBDIR;
411 489
412BEGIN { 490BEGIN {
413 urxvt->bootstrap; 491 urxvt->bootstrap;
414 492
415 # overwrite perl's warn 493 # overwrite perl's warn
417 my $msg = join "", @_; 495 my $msg = join "", @_;
418 $msg .= "\n" 496 $msg .= "\n"
419 unless $msg =~ /\n$/; 497 unless $msg =~ /\n$/;
420 urxvt::warn ($msg); 498 urxvt::warn ($msg);
421 }; 499 };
500
501 # %ENV is the original startup environment
502 delete $ENV{IFS};
503 delete $ENV{CDPATH};
504 delete $ENV{BASH_ENV};
505 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
422} 506}
423 507
424my @hook_count; 508my @hook_count;
425my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 509my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
426 510
427sub verbose { 511sub verbose {
428 my ($level, $msg) = @_; 512 my ($level, $msg) = @_;
429 warn "$msg\n" if $level <= $verbosity; 513 warn "$msg\n" if $level <= $verbosity;
430} 514}
431 515
432# find on_xxx subs in the package and register them
433# as hooks
434sub register_package($) {
435 my ($pkg) = @_;
436
437 for my $htype (0.. $#HOOKNAME) {
438 my $name = $HOOKNAME[$htype];
439
440 my $ref = $pkg->can ("on_" . lc $name)
441 or next;
442
443 $TERM->{_hook}[$htype]{$pkg} = $ref;
444 $hook_count[$htype]++
445 or set_should_invoke $htype, 1;
446 }
447}
448
449my $extension_pkg = "extension0000"; 516my $extension_pkg = "extension0000";
450my %extension_pkg; 517my %extension_pkg;
451 518
452# load a single script into its own package, once only 519# load a single script into its own package, once only
453sub extension_package($) { 520sub extension_package($) {
459 verbose 3, "loading extension '$path' into package '$pkg'"; 526 verbose 3, "loading extension '$path' into package '$pkg'";
460 527
461 open my $fh, "<:raw", $path 528 open my $fh, "<:raw", $path
462 or die "$path: $!"; 529 or die "$path: $!";
463 530
531 my $source = untaint
464 my $source = "package $pkg; use strict; use utf8;\n" 532 "package $pkg; use strict; use utf8;\n"
465 . "use base urxvt::term::proxy::;\n" 533 . "use base urxvt::term::extension::;\n"
466 . "#line 1 \"$path\"\n{\n" 534 . "#line 1 \"$path\"\n{\n"
467 . (do { local $/; <$fh> }) 535 . (do { local $/; <$fh> })
468 . "\n};\n1"; 536 . "\n};\n1";
469 537
538 eval $source
470 eval $source or die "$path: $@"; 539 or die "$path: $@";
471 540
472 $pkg 541 $pkg
473 } 542 }
474} 543}
475 544
481 my $htype = shift; 550 my $htype = shift;
482 551
483 if ($htype == 0) { # INIT 552 if ($htype == 0) { # INIT
484 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 553 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
485 554
486 my %want_ext; 555 my %ext_arg;
487 556
488 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 557 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
489 if ($_ eq "default") { 558 if ($_ eq "default") {
490 $want_ext{$_}++ for qw(selection option-popup); 559 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
491 } elsif (/^-(.*)$/) { 560 } elsif (/^-(.*)$/) {
492 delete $want_ext{$1}; 561 delete $ext_arg{$1};
562 } elsif (/^([^<]+)<(.*)>$/) {
563 push @{ $ext_arg{$1} }, $2;
493 } else { 564 } else {
494 $want_ext{$_}++; 565 $ext_arg{$_} ||= [];
495 } 566 }
496 } 567 }
497 568
498 for my $ext (keys %want_ext) { 569 while (my ($ext, $argv) = each %ext_arg) {
499 my @files = grep -f $_, map "$_/$ext", @dirs; 570 my @files = grep -f $_, map "$_/$ext", @dirs;
500 571
501 if (@files) { 572 if (@files) {
502 register_package extension_package $files[0]; 573 $TERM->register_package (extension_package $files[0], $argv);
503 } else { 574 } else {
504 warn "perl extension '$ext' not found in perl library search path\n"; 575 warn "perl extension '$ext' not found in perl library search path\n";
505 } 576 }
506 } 577 }
578
579 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
580 warn $@ if $@;
507 } 581 }
508 582
509 $retval = undef; 583 $retval = undef;
510 584
511 if (my $cb = $TERM->{_hook}[$htype]) { 585 if (my $cb = $TERM->{_hook}[$htype]) {
513 if $verbosity >= 10; 587 if $verbosity >= 10;
514 588
515 keys %$cb; 589 keys %$cb;
516 590
517 while (my ($pkg, $cb) = each %$cb) { 591 while (my ($pkg, $cb) = each %$cb) {
518 eval { 592 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
519 $retval = $cb->(
520 $TERM->{_pkg}{$pkg} ||= do {
521 my $proxy = bless { }, $pkg;
522 Scalar::Util::weaken ($proxy->{term} = $TERM);
523 $proxy
524 },
525 @_,
526 ) and last; 593 and last;
594
595 if ($@) {
596 $TERM->ungrab; # better to lose the grab than the session
597 warn $@;
527 }; 598 }
528 warn $@ if $@;#d#
529 } 599 }
530 } 600 }
531 601
532 if ($htype == 1) { # DESTROY 602 if ($htype == 1) { # DESTROY
533 # remove hooks if unused
534 if (my $hook = $TERM->{_hook}) { 603 if (my $hook = delete $TERM->{_hook}) {
535 for my $htype (0..$#$hook) { 604 for my $htype (0..$#$hook) {
536 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 605 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
537 or set_should_invoke $htype, 0; 606 or set_should_invoke $htype, 0;
538 } 607 }
539 } 608 }
546 } 615 }
547 616
548 $retval 617 $retval
549} 618}
550 619
551sub urxvt::term::proxy::AUTOLOAD { 620# urxvt::term::extension
552 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 621
622package urxvt::term::extension;
623
624sub enable {
625 my ($self, %hook) = @_;
626 my $pkg = $self->{_pkg};
627
628 while (my ($name, $cb) = each %hook) {
629 my $htype = $HOOKTYPE{uc $name};
630 defined $htype
631 or Carp::croak "unsupported hook type '$name'";
632
633 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
634 $hook_count[$htype]++
635 or urxvt::set_should_invoke $htype, 1;
636 }
637
638 $self->{term}{_hook}[$htype]{$pkg} = $cb;
639 }
640}
641
642sub disable {
643 my ($self, @hook) = @_;
644 my $pkg = $self->{_pkg};
645
646 for my $name (@hook) {
647 my $htype = $HOOKTYPE{uc $name};
648 defined $htype
649 or Carp::croak "unsupported hook type '$name'";
650
651 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
652 --$hook_count[$htype]
653 or urxvt::set_should_invoke $htype, 0;
654 }
655 }
656}
657
658our $AUTOLOAD;
659
660sub AUTOLOAD {
661 $AUTOLOAD =~ /:([^:]+)$/
553 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 662 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
554 663
555 eval qq{ 664 eval qq{
556 sub $urxvt::term::proxy::AUTOLOAD { 665 sub $AUTOLOAD {
557 my \$proxy = shift; 666 my \$proxy = shift;
558 \$proxy->{term}->$1 (\@_) 667 \$proxy->{term}->$1 (\@_)
559 } 668 }
560 1 669 1
561 } or die "FATAL: unable to compile method forwarder: $@"; 670 } or die "FATAL: unable to compile method forwarder: $@";
562 671
563 goto &$urxvt::term::proxy::AUTOLOAD; 672 goto &$AUTOLOAD;
564} 673}
674
675sub DESTROY {
676 # nop
677}
678
679# urxvt::destroy_hook
565 680
566sub urxvt::destroy_hook::DESTROY { 681sub urxvt::destroy_hook::DESTROY {
567 ${$_[0]}->(); 682 ${$_[0]}->();
568} 683}
569 684
570sub urxvt::destroy_hook(&) { 685sub urxvt::destroy_hook(&) {
571 bless \shift, urxvt::destroy_hook:: 686 bless \shift, urxvt::destroy_hook::
572} 687}
573 688
689package urxvt::anyevent;
690
691=head2 The C<urxvt::anyevent> Class
692
693The sole purpose of this class is to deliver an interface to the
694C<AnyEvent> module - any module using it will work inside urxvt without
695further programming. The only exception is that you cannot wait on
696condition variables, but non-blocking condvar use is ok. What this means
697is that you cannot use blocking APIs, but the non-blocking variant should
698work.
699
700=cut
701
702our $VERSION = 1;
703
704$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
705push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
706
707sub timer {
708 my ($class, %arg) = @_;
709
710 my $cb = $arg{cb};
711
712 urxvt::timer
713 ->new
714 ->start (urxvt::NOW + $arg{after})
715 ->cb (sub {
716 $_[0]->stop; # need to cancel manually
717 $cb->();
718 })
719}
720
721sub io {
722 my ($class, %arg) = @_;
723
724 my $cb = $arg{cb};
725
726 bless [$arg{fh}, urxvt::iow
727 ->new
728 ->fd (fileno $arg{fh})
729 ->events (($arg{poll} =~ /r/ ? 1 : 0)
730 | ($arg{poll} =~ /w/ ? 2 : 0))
731 ->start
732 ->cb (sub {
733 $cb->(($_[1] & 1 ? 'r' : '')
734 . ($_[1] & 2 ? 'w' : ''));
735 })],
736 urxvt::anyevent::
737}
738
739sub DESTROY {
740 $_[0][1]->stop;
741}
742
743sub condvar {
744 bless \my $flag, urxvt::anyevent::condvar::
745}
746
747sub urxvt::anyevent::condvar::broadcast {
748 ${$_[0]}++;
749}
750
751sub urxvt::anyevent::condvar::wait {
752 unless (${$_[0]}) {
753 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
754 }
755}
756
757package urxvt::term;
758
574=head2 The C<urxvt::term> Class 759=head2 The C<urxvt::term> Class
575 760
576=over 4 761=over 4
577 762
763=cut
764
765# find on_xxx subs in the package and register them
766# as hooks
767sub register_package {
768 my ($self, $pkg, $argv) = @_;
769
770 my $proxy = bless {
771 _pkg => $pkg,
772 argv => $argv,
773 }, $pkg;
774 Scalar::Util::weaken ($proxy->{term} = $self);
775
776 $self->{_pkg}{$pkg} = $proxy;
777
778 for my $name (@HOOKNAME) {
779 if (my $ref = $pkg->can ("on_" . lc $name)) {
780 $proxy->enable ($name => $ref);
781 }
782 }
783}
784
785=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
786
787Creates a new terminal, very similar as if you had started it with system
788C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
789hash which defines the environment of the new terminal.
790
791Croaks (and probably outputs an error message) if the new instance
792couldn't be created. Returns C<undef> if the new instance didn't
793initialise perl, and the terminal object otherwise. The C<init> and
794C<start> hooks will be called during this call.
795
796=cut
797
798sub new {
799 my ($class, $env, @args) = @_;
800
801 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
802}
803
578=item $term->destroy 804=item $term->destroy
579 805
580Destroy the terminal object (close the window, free resources etc.). 806Destroy the terminal object (close the window, free resources
807etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
808watchers (timers, io watchers) are still active.
581 809
582=item $isset = $term->option ($optval[, $set]) 810=item $isset = $term->option ($optval[, $set])
583 811
584Returns true if the option specified by C<$optval> is enabled, and 812Returns true if the option specified by C<$optval> is enabled, and
585optionally change it. All option values are stored by name in the hash 813optionally change it. All option values are stored by name in the hash
629 shade term_name title transparent transparent_all tripleclickwords 857 shade term_name title transparent transparent_all tripleclickwords
630 utmpInhibit visualBell 858 utmpInhibit visualBell
631 859
632=cut 860=cut
633 861
634sub urxvt::term::resource($$;$) { 862sub resource($$;$) {
635 my ($self, $name) = (shift, shift); 863 my ($self, $name) = (shift, shift);
636 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 864 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
637 &urxvt::term::_resource 865 &urxvt::term::_resource
638} 866}
639 867
868=item $value = $term->x_resource ($pattern)
869
870Returns the X-Resource for the given pattern, excluding the program or
871class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
872same value as used by this instance of rxvt-unicode. Returns C<undef> if no
873resource with that pattern exists.
874
875This method should only be called during the C<on_start> hook, as there is
876only one resource database per display, and later invocations might return
877the wrong resources.
878
879=item $success = $term->parse_keysym ($keysym_spec, $command_string)
880
881Adds a keymap translation exactly as specified via a resource. See the
882C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
883
640=item $rend = $term->rstyle ([$new_rstyle]) 884=item $rend = $term->rstyle ([$new_rstyle])
641 885
642Return and optionally change the current rendition. Text that is output by 886Return and optionally change the current rendition. Text that is output by
643the terminal application will use this style. 887the terminal application will use this style.
644 888
663 907
664=item $oldtext = $term->selection ([$newtext]) 908=item $oldtext = $term->selection ([$newtext])
665 909
666Return the current selection text and optionally replace it by C<$newtext>. 910Return the current selection text and optionally replace it by C<$newtext>.
667 911
668#=item $term->overlay ($x, $y, $text) 912=item $term->overlay_simple ($x, $y, $text)
669# 913
670#Create a simple multi-line overlay box. See the next method for details. 914Create a simple multi-line overlay box. See the next method for details.
671# 915
672#=cut 916=cut
673# 917
674#sub urxvt::term::scr_overlay { 918sub overlay_simple {
675# my ($self, $x, $y, $text) = @_; 919 my ($self, $x, $y, $text) = @_;
676# 920
677# my @lines = split /\n/, $text; 921 my @lines = split /\n/, $text;
678# 922
679# my $w = 0; 923 my $w = List::Util::max map $self->strwidth ($_), @lines;
680# for (map $self->strwidth ($_), @lines) { 924
681# $w = $_ if $w < $_;
682# }
683#
684# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 925 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
685# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 926 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
686#} 927
928 $overlay
929}
687 930
688=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 931=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
689 932
690Create a new (empty) overlay at the given position with the given 933Create a new (empty) overlay at the given position with the given
691width/height. C<$rstyle> defines the initial rendition style 934width/height. C<$rstyle> defines the initial rendition style
726C<$event> I<must> be the event causing the menu to pop up (a button event, 969C<$event> I<must> be the event causing the menu to pop up (a button event,
727currently). 970currently).
728 971
729=cut 972=cut
730 973
731sub urxvt::term::popup { 974sub popup {
732 my ($self, $event) = @_; 975 my ($self, $event) = @_;
733 976
734 $self->grab ($event->{time}, 1) 977 $self->grab ($event->{time}, 1)
735 or return; 978 or return;
736 979
758 1001
759=item $string = $term->locale_decode ($octets) 1002=item $string = $term->locale_decode ($octets)
760 1003
761Convert the given locale-encoded octets into a perl string. 1004Convert the given locale-encoded octets into a perl string.
762 1005
1006=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1007
1008XORs the rendition values in the given span with the provided value
1009(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
1010to the selection.
1011
1012=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1013
1014Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1015whitespace will additionally be xored with the C<$rstyle2>, which defaults
1016to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1017it instead.
1018
1019=item $term->scr_bell
1020
1021Ring the bell!
1022
763=item $term->scr_add_lines ($string) 1023=item $term->scr_add_lines ($string)
764 1024
765Write the given text string to the screen, as if output by the application 1025Write the given text string to the screen, as if output by the application
766running inside the terminal. It may not contain command sequences (escape 1026running inside the terminal. It may not contain command sequences (escape
767codes), but is free to use line feeds, carriage returns and tabs. The 1027codes), but is free to use line feeds, carriage returns and tabs. The
781 1041
782Write the octets given in C<$data> to the tty (i.e. as program input). To 1042Write the octets given in C<$data> to the tty (i.e. as program input). To
783pass characters instead of octets, you should convert your strings first 1043pass characters instead of octets, you should convert your strings first
784to the locale-specific encoding using C<< $term->locale_encode >>. 1044to the locale-specific encoding using C<< $term->locale_encode >>.
785 1045
1046=item $old_events = $term->pty_ev_events ([$new_events])
1047
1048Replaces the event mask of the pty watcher by the given event mask. Can
1049be used to suppress input and output handling to the pty/tty. See the
1050description of C<< urxvt::timer->events >>. Make sure to always restore
1051the previous value.
1052
786=item $windowid = $term->parent 1053=item $windowid = $term->parent
787 1054
788Return the window id of the toplevel window. 1055Return the window id of the toplevel window.
789 1056
790=item $windowid = $term->vt 1057=item $windowid = $term->vt
814=item $nrow_plus_saveLines = $term->total_rows 1081=item $nrow_plus_saveLines = $term->total_rows
815 1082
816=item $lines_in_scrollback = $term->nsaved 1083=item $lines_in_scrollback = $term->nsaved
817 1084
818Return various integers describing terminal characteristics. 1085Return various integers describing terminal characteristics.
1086
1087=item $x_display = $term->display_id
1088
1089Return the DISPLAY used by rxvt-unicode.
1090
1091=item $lc_ctype = $term->locale
1092
1093Returns the LC_CTYPE category string used by this rxvt-unicode.
1094
1095=item $env = $term->env
1096
1097Returns a copy of the environment in effect for the terminal as a hashref
1098similar to C<\%ENV>.
1099
1100=cut
1101
1102sub env {
1103 if (my $env = $_[0]->_env) {
1104 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1105 } else {
1106 +{ %ENV }
1107 }
1108}
819 1109
820=item $modifiermask = $term->ModLevel3Mask 1110=item $modifiermask = $term->ModLevel3Mask
821 1111
822=item $modifiermask = $term->ModMetaMask 1112=item $modifiermask = $term->ModMetaMask
823 1113
926 1216
927=back 1217=back
928 1218
929=cut 1219=cut
930 1220
931sub urxvt::term::line { 1221sub line {
932 my ($self, $row) = @_; 1222 my ($self, $row) = @_;
933 1223
934 my $maxrow = $self->nrow - 1; 1224 my $maxrow = $self->nrow - 1;
935 1225
936 my ($beg, $end) = ($row, $row); 1226 my ($beg, $end) = ($row, $row);
1000 $offset / $self->{ncol} + $self->{beg}, 1290 $offset / $self->{ncol} + $self->{beg},
1001 $offset % $self->{ncol} 1291 $offset % $self->{ncol}
1002 ) 1292 )
1003} 1293}
1004 1294
1005=item ($row, $col) = $line->coord_of ($offset)
1006=item $text = $term->special_encode $string 1295=item $text = $term->special_encode $string
1007 1296
1008Converts a perl string into the special encoding used by rxvt-unicode, 1297Converts a perl string into the special encoding used by rxvt-unicode,
1009where one character corresponds to one screen cell. See 1298where one character corresponds to one screen cell. See
1010C<< $term->ROW_t >> for details. 1299C<< $term->ROW_t >> for details.
1012=item $string = $term->special_decode $text 1301=item $string = $term->special_decode $text
1013 1302
1014Converts rxvt-unicodes text reprsentation into a perl string. See 1303Converts rxvt-unicodes text reprsentation into a perl string. See
1015C<< $term->ROW_t >> for details. 1304C<< $term->ROW_t >> for details.
1016 1305
1306=item $success = $term->grab_button ($button, $modifiermask)
1307
1308Registers a synchronous button grab. See the XGrabButton manpage.
1309
1310=item $success = $term->grab ($eventtime[, $sync])
1311
1312Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1313synchronous (C<$sync> is true). Also remembers the grab timestampe.
1314
1315=item $term->allow_events_async
1316
1317Calls XAllowEvents with AsyncBoth for the most recent grab.
1318
1319=item $term->allow_events_sync
1320
1321Calls XAllowEvents with SyncBoth for the most recent grab.
1322
1323=item $term->allow_events_replay
1324
1325Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1326recent grab.
1327
1328=item $term->ungrab
1329
1330Calls XUngrab for the most recent grab. Is called automatically on
1331evaluation errors, as it is better to lose the grab in the error case as
1332the session.
1333
1017=back 1334=back
1018 1335
1336=cut
1337
1338package urxvt::popup;
1339
1019=head2 The C<urxvt::popup> Class 1340=head2 The C<urxvt::popup> Class
1020 1341
1021=over 4 1342=over 4
1022 1343
1023=cut 1344=cut
1024
1025package urxvt::popup;
1026 1345
1027sub add_item { 1346sub add_item {
1028 my ($self, $item) = @_; 1347 my ($self, $item) = @_;
1029 1348
1349 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1350 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1351 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1352
1353 $item->{render} ||= sub { $_[0]{text} };
1354
1030 push @{ $self->{item} }, $item; 1355 push @{ $self->{item} }, $item;
1031} 1356}
1357
1358=item $popup->add_title ($title)
1359
1360Adds a non-clickable title to the popup.
1361
1362=cut
1363
1364sub add_title {
1365 my ($self, $title) = @_;
1366
1367 $self->add_item ({
1368 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1369 text => $title,
1370 activate => sub { },
1371 });
1372}
1373
1374=item $popup->add_separator ([$sepchr])
1375
1376Creates a separator, optionally using the character given as C<$sepchr>.
1377
1378=cut
1379
1380sub add_separator {
1381 my ($self, $sep) = @_;
1382
1383 $sep ||= "=";
1384
1385 $self->add_item ({
1386 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1387 text => "",
1388 render => sub { $sep x $self->{term}->ncol },
1389 activate => sub { },
1390 });
1391}
1392
1393=item $popup->add_button ($text, $cb)
1394
1395Adds a clickable button to the popup. C<$cb> is called whenever it is
1396selected.
1397
1398=cut
1032 1399
1033sub add_button { 1400sub add_button {
1034 my ($self, $text, $cb) = @_; 1401 my ($self, $text, $cb) = @_;
1035 1402
1036 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb, 1403 $self->add_item ({ type => "button", text => $text, activate => $cb});
1037 render => sub { $_[0]{text} },
1038 });
1039} 1404}
1405
1406=item $popup->add_toggle ($text, $cb, $initial_value)
1407
1408Adds a toggle/checkbox item to the popup. Teh callback gets called
1409whenever it gets toggled, with a boolean indicating its value as its first
1410argument.
1411
1412=cut
1040 1413
1041sub add_toggle { 1414sub add_toggle {
1042 my ($self, $text, $cb, $value) = @_; 1415 my ($self, $text, $cb, $value) = @_;
1043 1416
1044 my $item; $item = { 1417 my $item; $item = {
1045 type => "button", 1418 type => "button",
1046 text => " $text", 1419 text => " $text",
1047 value => $value, 1420 value => $value,
1048 render => sub { ($item->{value} ? "* " : " ") . $text }, 1421 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1049 activate => sub { $cb->($item->{value} = !$item->{value}); }, 1422 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1050 }; 1423 };
1051 1424
1052 $self->add_item ($item); 1425 $self->add_item ($item);
1053} 1426}
1427
1428=item $popup->show
1429
1430Displays the popup (which is initially hidden).
1431
1432=cut
1054 1433
1055sub show { 1434sub show {
1056 my ($self) = @_; 1435 my ($self) = @_;
1057 1436
1058 local $urxvt::popup::self = $self; 1437 local $urxvt::popup::self = $self;
1059 1438
1439 my $env = $self->{term}->env;
1440 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1441 delete $env->{LC_ALL};
1442 $env->{LC_CTYPE} = $self->{term}->locale;
1443
1444 urxvt::term->new ($env, $self->{term}->resource ("name"),
1060 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1445 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1061 "--transient-for" => $self->{term}->parent, 1446 "--transient-for" => $self->{term}->parent,
1447 "-display" => $self->{term}->display_id,
1062 "-pe" => "urxvt-popup") 1448 "-pe" => "urxvt-popup")
1063 or die "unable to create popup window\n"; 1449 or die "unable to create popup window\n";
1064} 1450}
1065 1451
1066sub DESTROY { 1452sub DESTROY {
1067 my ($self) = @_; 1453 my ($self) = @_;
1068 1454
1455 delete $self->{term}{_destroy}{$self};
1069 $self->{term}->ungrab; 1456 $self->{term}->ungrab;
1070} 1457}
1458
1459=back
1071 1460
1072=head2 The C<urxvt::timer> Class 1461=head2 The C<urxvt::timer> Class
1073 1462
1074This class implements timer watchers/events. Time is represented as a 1463This class implements timer watchers/events. Time is represented as a
1075fractional number of seconds since the epoch. Example: 1464fractional number of seconds since the epoch. Example:
1128 1517
1129 $term->{socket} = ... 1518 $term->{socket} = ...
1130 $term->{iow} = urxvt::iow 1519 $term->{iow} = urxvt::iow
1131 ->new 1520 ->new
1132 ->fd (fileno $term->{socket}) 1521 ->fd (fileno $term->{socket})
1133 ->events (1) # wait for read data 1522 ->events (urxvt::EVENT_READ)
1134 ->start 1523 ->start
1135 ->cb (sub { 1524 ->cb (sub {
1136 my ($iow, $revents) = @_; 1525 my ($iow, $revents) = @_;
1137 # $revents must be 1 here, no need to check 1526 # $revents must be 1 here, no need to check
1138 sysread $term->{socket}, my $buf, 8192 1527 sysread $term->{socket}, my $buf, 8192
1155 1544
1156Set the filedescriptor (not handle) to watch. 1545Set the filedescriptor (not handle) to watch.
1157 1546
1158=item $iow = $iow->events ($eventmask) 1547=item $iow = $iow->events ($eventmask)
1159 1548
1160Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1549Set the event mask to watch. The only allowed values are
1161data, Bit #1 (value C<2>) enables watching for write data. 1550C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1551together, or C<urxvt::EVENT_NONE>.
1162 1552
1163=item $iow = $iow->start 1553=item $iow = $iow->start
1164 1554
1165Start watching for requested events on the given handle. 1555Start watching for requested events on the given handle.
1166 1556
1177This variable controls the verbosity level of the perl extension. Higher 1567This variable controls the verbosity level of the perl extension. Higher
1178numbers indicate more verbose output. 1568numbers indicate more verbose output.
1179 1569
1180=over 4 1570=over 4
1181 1571
1182=item =0 - only fatal messages 1572=item == 0 - fatal messages
1183 1573
1184=item =3 - script loading and management 1574=item >= 3 - script loading and management
1185 1575
1186=item =10 - all events received 1576=item >=10 - all events received
1187 1577
1188=back 1578=back
1189 1579
1190=head1 AUTHOR 1580=head1 AUTHOR
1191 1581

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines