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.51 by root, Sun Jan 8 00:27:47 2006 UTC vs.
Revision 1.84 by root, Thu Jan 12 02:20:56 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 { 620sub exec_async(@) {
552 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 621 my $pid = fork;
622
623 return
624 if !defined $pid or $pid;
625
626 %ENV = %{ $TERM->env };
627
628 exec @_;
629 _exit 255;
630}
631
632# urxvt::term::extension
633
634package urxvt::term::extension;
635
636sub enable {
637 my ($self, %hook) = @_;
638 my $pkg = $self->{_pkg};
639
640 while (my ($name, $cb) = each %hook) {
641 my $htype = $HOOKTYPE{uc $name};
642 defined $htype
643 or Carp::croak "unsupported hook type '$name'";
644
645 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
646 $hook_count[$htype]++
647 or urxvt::set_should_invoke $htype, 1;
648 }
649
650 $self->{term}{_hook}[$htype]{$pkg} = $cb;
651 }
652}
653
654sub disable {
655 my ($self, @hook) = @_;
656 my $pkg = $self->{_pkg};
657
658 for my $name (@hook) {
659 my $htype = $HOOKTYPE{uc $name};
660 defined $htype
661 or Carp::croak "unsupported hook type '$name'";
662
663 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
664 --$hook_count[$htype]
665 or urxvt::set_should_invoke $htype, 0;
666 }
667 }
668}
669
670our $AUTOLOAD;
671
672sub AUTOLOAD {
673 $AUTOLOAD =~ /:([^:]+)$/
553 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 674 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
554 675
555 eval qq{ 676 eval qq{
556 sub $urxvt::term::proxy::AUTOLOAD { 677 sub $AUTOLOAD {
557 my \$proxy = shift; 678 my \$proxy = shift;
558 \$proxy->{term}->$1 (\@_) 679 \$proxy->{term}->$1 (\@_)
559 } 680 }
560 1 681 1
561 } or die "FATAL: unable to compile method forwarder: $@"; 682 } or die "FATAL: unable to compile method forwarder: $@";
562 683
563 goto &$urxvt::term::proxy::AUTOLOAD; 684 goto &$AUTOLOAD;
564} 685}
686
687sub DESTROY {
688 # nop
689}
690
691# urxvt::destroy_hook
565 692
566sub urxvt::destroy_hook::DESTROY { 693sub urxvt::destroy_hook::DESTROY {
567 ${$_[0]}->(); 694 ${$_[0]}->();
568} 695}
569 696
570sub urxvt::destroy_hook(&) { 697sub urxvt::destroy_hook(&) {
571 bless \shift, urxvt::destroy_hook:: 698 bless \shift, urxvt::destroy_hook::
572} 699}
573 700
701package urxvt::anyevent;
702
703=head2 The C<urxvt::anyevent> Class
704
705The sole purpose of this class is to deliver an interface to the
706C<AnyEvent> module - any module using it will work inside urxvt without
707further programming. The only exception is that you cannot wait on
708condition variables, but non-blocking condvar use is ok. What this means
709is that you cannot use blocking APIs, but the non-blocking variant should
710work.
711
712=cut
713
714our $VERSION = 1;
715
716$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
717push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
718
719sub timer {
720 my ($class, %arg) = @_;
721
722 my $cb = $arg{cb};
723
724 urxvt::timer
725 ->new
726 ->start (urxvt::NOW + $arg{after})
727 ->cb (sub {
728 $_[0]->stop; # need to cancel manually
729 $cb->();
730 })
731}
732
733sub io {
734 my ($class, %arg) = @_;
735
736 my $cb = $arg{cb};
737
738 bless [$arg{fh}, urxvt::iow
739 ->new
740 ->fd (fileno $arg{fh})
741 ->events (($arg{poll} =~ /r/ ? 1 : 0)
742 | ($arg{poll} =~ /w/ ? 2 : 0))
743 ->start
744 ->cb (sub {
745 $cb->(($_[1] & 1 ? 'r' : '')
746 . ($_[1] & 2 ? 'w' : ''));
747 })],
748 urxvt::anyevent::
749}
750
751sub DESTROY {
752 $_[0][1]->stop;
753}
754
755sub condvar {
756 bless \my $flag, urxvt::anyevent::condvar::
757}
758
759sub urxvt::anyevent::condvar::broadcast {
760 ${$_[0]}++;
761}
762
763sub urxvt::anyevent::condvar::wait {
764 unless (${$_[0]}) {
765 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
766 }
767}
768
769package urxvt::term;
770
574=head2 The C<urxvt::term> Class 771=head2 The C<urxvt::term> Class
575 772
576=over 4 773=over 4
577 774
775=cut
776
777# find on_xxx subs in the package and register them
778# as hooks
779sub register_package {
780 my ($self, $pkg, $argv) = @_;
781
782 my $proxy = bless {
783 _pkg => $pkg,
784 argv => $argv,
785 }, $pkg;
786 Scalar::Util::weaken ($proxy->{term} = $self);
787
788 $self->{_pkg}{$pkg} = $proxy;
789
790 for my $name (@HOOKNAME) {
791 if (my $ref = $pkg->can ("on_" . lc $name)) {
792 $proxy->enable ($name => $ref);
793 }
794 }
795}
796
797=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
798
799Creates a new terminal, very similar as if you had started it with system
800C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
801hash which defines the environment of the new terminal.
802
803Croaks (and probably outputs an error message) if the new instance
804couldn't be created. Returns C<undef> if the new instance didn't
805initialise perl, and the terminal object otherwise. The C<init> and
806C<start> hooks will be called during this call.
807
808=cut
809
810sub new {
811 my ($class, $env, @args) = @_;
812
813 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
814}
815
578=item $term->destroy 816=item $term->destroy
579 817
580Destroy the terminal object (close the window, free resources etc.). 818Destroy the terminal object (close the window, free resources
819etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
820watchers (timers, io watchers) are still active.
581 821
582=item $isset = $term->option ($optval[, $set]) 822=item $isset = $term->option ($optval[, $set])
583 823
584Returns true if the option specified by C<$optval> is enabled, and 824Returns true if the option specified by C<$optval> is enabled, and
585optionally change it. All option values are stored by name in the hash 825optionally change it. All option values are stored by name in the hash
629 shade term_name title transparent transparent_all tripleclickwords 869 shade term_name title transparent transparent_all tripleclickwords
630 utmpInhibit visualBell 870 utmpInhibit visualBell
631 871
632=cut 872=cut
633 873
634sub urxvt::term::resource($$;$) { 874sub resource($$;$) {
635 my ($self, $name) = (shift, shift); 875 my ($self, $name) = (shift, shift);
636 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 876 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
637 &urxvt::term::_resource 877 &urxvt::term::_resource
638} 878}
639 879
880=item $value = $term->x_resource ($pattern)
881
882Returns the X-Resource for the given pattern, excluding the program or
883class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
884same value as used by this instance of rxvt-unicode. Returns C<undef> if no
885resource with that pattern exists.
886
887This method should only be called during the C<on_start> hook, as there is
888only one resource database per display, and later invocations might return
889the wrong resources.
890
891=item $success = $term->parse_keysym ($keysym_spec, $command_string)
892
893Adds a keymap translation exactly as specified via a resource. See the
894C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
895
640=item $rend = $term->rstyle ([$new_rstyle]) 896=item $rend = $term->rstyle ([$new_rstyle])
641 897
642Return and optionally change the current rendition. Text that is output by 898Return and optionally change the current rendition. Text that is output by
643the terminal application will use this style. 899the terminal application will use this style.
644 900
663 919
664=item $oldtext = $term->selection ([$newtext]) 920=item $oldtext = $term->selection ([$newtext])
665 921
666Return the current selection text and optionally replace it by C<$newtext>. 922Return the current selection text and optionally replace it by C<$newtext>.
667 923
668#=item $term->overlay ($x, $y, $text) 924=item $term->overlay_simple ($x, $y, $text)
669# 925
670#Create a simple multi-line overlay box. See the next method for details. 926Create a simple multi-line overlay box. See the next method for details.
671# 927
672#=cut 928=cut
673# 929
674#sub urxvt::term::scr_overlay { 930sub overlay_simple {
675# my ($self, $x, $y, $text) = @_; 931 my ($self, $x, $y, $text) = @_;
676# 932
677# my @lines = split /\n/, $text; 933 my @lines = split /\n/, $text;
678# 934
679# my $w = 0; 935 my $w = List::Util::max map $self->strwidth ($_), @lines;
680# for (map $self->strwidth ($_), @lines) { 936
681# $w = $_ if $w < $_;
682# }
683#
684# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 937 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
685# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 938 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
686#} 939
940 $overlay
941}
687 942
688=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 943=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
689 944
690Create a new (empty) overlay at the given position with the given 945Create a new (empty) overlay at the given position with the given
691width/height. C<$rstyle> defines the initial rendition style 946width/height. C<$rstyle> defines the initial rendition style
726C<$event> I<must> be the event causing the menu to pop up (a button event, 981C<$event> I<must> be the event causing the menu to pop up (a button event,
727currently). 982currently).
728 983
729=cut 984=cut
730 985
731sub urxvt::term::popup { 986sub popup {
732 my ($self, $event) = @_; 987 my ($self, $event) = @_;
733 988
734 $self->grab ($event->{time}, 1) 989 $self->grab ($event->{time}, 1)
735 or return; 990 or return;
736 991
758 1013
759=item $string = $term->locale_decode ($octets) 1014=item $string = $term->locale_decode ($octets)
760 1015
761Convert the given locale-encoded octets into a perl string. 1016Convert the given locale-encoded octets into a perl string.
762 1017
1018=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1019
1020XORs the rendition values in the given span with the provided value
1021(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
1022to the selection.
1023
1024=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1025
1026Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1027whitespace will additionally be xored with the C<$rstyle2>, which defaults
1028to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1029it instead.
1030
1031=item $term->scr_bell
1032
1033Ring the bell!
1034
763=item $term->scr_add_lines ($string) 1035=item $term->scr_add_lines ($string)
764 1036
765Write the given text string to the screen, as if output by the application 1037Write the given text string to the screen, as if output by the application
766running inside the terminal. It may not contain command sequences (escape 1038running inside the terminal. It may not contain command sequences (escape
767codes), but is free to use line feeds, carriage returns and tabs. The 1039codes), but is free to use line feeds, carriage returns and tabs. The
781 1053
782Write the octets given in C<$data> to the tty (i.e. as program input). To 1054Write 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 1055pass characters instead of octets, you should convert your strings first
784to the locale-specific encoding using C<< $term->locale_encode >>. 1056to the locale-specific encoding using C<< $term->locale_encode >>.
785 1057
1058=item $old_events = $term->pty_ev_events ([$new_events])
1059
1060Replaces the event mask of the pty watcher by the given event mask. Can
1061be used to suppress input and output handling to the pty/tty. See the
1062description of C<< urxvt::timer->events >>. Make sure to always restore
1063the previous value.
1064
786=item $windowid = $term->parent 1065=item $windowid = $term->parent
787 1066
788Return the window id of the toplevel window. 1067Return the window id of the toplevel window.
789 1068
790=item $windowid = $term->vt 1069=item $windowid = $term->vt
814=item $nrow_plus_saveLines = $term->total_rows 1093=item $nrow_plus_saveLines = $term->total_rows
815 1094
816=item $lines_in_scrollback = $term->nsaved 1095=item $lines_in_scrollback = $term->nsaved
817 1096
818Return various integers describing terminal characteristics. 1097Return various integers describing terminal characteristics.
1098
1099=item $x_display = $term->display_id
1100
1101Return the DISPLAY used by rxvt-unicode.
1102
1103=item $lc_ctype = $term->locale
1104
1105Returns the LC_CTYPE category string used by this rxvt-unicode.
1106
1107=item $env = $term->env
1108
1109Returns a copy of the environment in effect for the terminal as a hashref
1110similar to C<\%ENV>.
1111
1112=cut
1113
1114sub env {
1115 if (my $env = $_[0]->_env) {
1116 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1117 } else {
1118 +{ %ENV }
1119 }
1120}
819 1121
820=item $modifiermask = $term->ModLevel3Mask 1122=item $modifiermask = $term->ModLevel3Mask
821 1123
822=item $modifiermask = $term->ModMetaMask 1124=item $modifiermask = $term->ModMetaMask
823 1125
926 1228
927=back 1229=back
928 1230
929=cut 1231=cut
930 1232
931sub urxvt::term::line { 1233sub line {
932 my ($self, $row) = @_; 1234 my ($self, $row) = @_;
933 1235
934 my $maxrow = $self->nrow - 1; 1236 my $maxrow = $self->nrow - 1;
935 1237
936 my ($beg, $end) = ($row, $row); 1238 my ($beg, $end) = ($row, $row);
1000 $offset / $self->{ncol} + $self->{beg}, 1302 $offset / $self->{ncol} + $self->{beg},
1001 $offset % $self->{ncol} 1303 $offset % $self->{ncol}
1002 ) 1304 )
1003} 1305}
1004 1306
1005=item ($row, $col) = $line->coord_of ($offset)
1006=item $text = $term->special_encode $string 1307=item $text = $term->special_encode $string
1007 1308
1008Converts a perl string into the special encoding used by rxvt-unicode, 1309Converts a perl string into the special encoding used by rxvt-unicode,
1009where one character corresponds to one screen cell. See 1310where one character corresponds to one screen cell. See
1010C<< $term->ROW_t >> for details. 1311C<< $term->ROW_t >> for details.
1012=item $string = $term->special_decode $text 1313=item $string = $term->special_decode $text
1013 1314
1014Converts rxvt-unicodes text reprsentation into a perl string. See 1315Converts rxvt-unicodes text reprsentation into a perl string. See
1015C<< $term->ROW_t >> for details. 1316C<< $term->ROW_t >> for details.
1016 1317
1318=item $success = $term->grab_button ($button, $modifiermask)
1319
1320Registers a synchronous button grab. See the XGrabButton manpage.
1321
1322=item $success = $term->grab ($eventtime[, $sync])
1323
1324Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1325synchronous (C<$sync> is true). Also remembers the grab timestampe.
1326
1327=item $term->allow_events_async
1328
1329Calls XAllowEvents with AsyncBoth for the most recent grab.
1330
1331=item $term->allow_events_sync
1332
1333Calls XAllowEvents with SyncBoth for the most recent grab.
1334
1335=item $term->allow_events_replay
1336
1337Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1338recent grab.
1339
1340=item $term->ungrab
1341
1342Calls XUngrab for the most recent grab. Is called automatically on
1343evaluation errors, as it is better to lose the grab in the error case as
1344the session.
1345
1017=back 1346=back
1018 1347
1348=cut
1349
1350package urxvt::popup;
1351
1019=head2 The C<urxvt::popup> Class 1352=head2 The C<urxvt::popup> Class
1020 1353
1021=over 4 1354=over 4
1022 1355
1023=cut 1356=cut
1024
1025package urxvt::popup;
1026 1357
1027sub add_item { 1358sub add_item {
1028 my ($self, $item) = @_; 1359 my ($self, $item) = @_;
1029 1360
1361 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1362 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1363 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1364
1365 $item->{render} ||= sub { $_[0]{text} };
1366
1030 push @{ $self->{item} }, $item; 1367 push @{ $self->{item} }, $item;
1031} 1368}
1369
1370=item $popup->add_title ($title)
1371
1372Adds a non-clickable title to the popup.
1373
1374=cut
1375
1376sub add_title {
1377 my ($self, $title) = @_;
1378
1379 $self->add_item ({
1380 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1381 text => $title,
1382 activate => sub { },
1383 });
1384}
1385
1386=item $popup->add_separator ([$sepchr])
1387
1388Creates a separator, optionally using the character given as C<$sepchr>.
1389
1390=cut
1391
1392sub add_separator {
1393 my ($self, $sep) = @_;
1394
1395 $sep ||= "=";
1396
1397 $self->add_item ({
1398 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1399 text => "",
1400 render => sub { $sep x $self->{term}->ncol },
1401 activate => sub { },
1402 });
1403}
1404
1405=item $popup->add_button ($text, $cb)
1406
1407Adds a clickable button to the popup. C<$cb> is called whenever it is
1408selected.
1409
1410=cut
1032 1411
1033sub add_button { 1412sub add_button {
1034 my ($self, $text, $cb) = @_; 1413 my ($self, $text, $cb) = @_;
1035 1414
1036 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb, 1415 $self->add_item ({ type => "button", text => $text, activate => $cb});
1037 render => sub { $_[0]{text} },
1038 });
1039} 1416}
1417
1418=item $popup->add_toggle ($text, $cb, $initial_value)
1419
1420Adds a toggle/checkbox item to the popup. Teh callback gets called
1421whenever it gets toggled, with a boolean indicating its value as its first
1422argument.
1423
1424=cut
1040 1425
1041sub add_toggle { 1426sub add_toggle {
1042 my ($self, $text, $cb, $value) = @_; 1427 my ($self, $text, $cb, $value) = @_;
1043 1428
1044 my $item; $item = { 1429 my $item; $item = {
1045 type => "button", 1430 type => "button",
1046 text => " $text", 1431 text => " $text",
1047 value => $value, 1432 value => $value,
1048 render => sub { ($item->{value} ? "" : " ") . $text }, 1433 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1049 activate => sub { $cb->($item->{value} = !$item->{value}); }, 1434 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1050 }; 1435 };
1051 1436
1052 $self->add_item ($item); 1437 $self->add_item ($item);
1053} 1438}
1439
1440=item $popup->show
1441
1442Displays the popup (which is initially hidden).
1443
1444=cut
1054 1445
1055sub show { 1446sub show {
1056 my ($self) = @_; 1447 my ($self) = @_;
1057 1448
1058 local $urxvt::popup::self = $self; 1449 local $urxvt::popup::self = $self;
1059 1450
1451 my $env = $self->{term}->env;
1452 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1453 delete $env->{LC_ALL};
1454 $env->{LC_CTYPE} = $self->{term}->locale;
1455
1456 urxvt::term->new ($env, $self->{term}->resource ("name"),
1060 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1457 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1061 "--transient-for" => $self->{term}->parent, 1458 "--transient-for" => $self->{term}->parent,
1459 "-display" => $self->{term}->display_id,
1062 "-pe" => "urxvt-popup") 1460 "-pe" => "urxvt-popup")
1063 or die "unable to create popup window\n"; 1461 or die "unable to create popup window\n";
1064} 1462}
1065 1463
1066sub DESTROY { 1464sub DESTROY {
1067 my ($self) = @_; 1465 my ($self) = @_;
1068 1466
1467 delete $self->{term}{_destroy}{$self};
1069 $self->{term}->ungrab; 1468 $self->{term}->ungrab;
1070} 1469}
1470
1471=back
1071 1472
1072=head2 The C<urxvt::timer> Class 1473=head2 The C<urxvt::timer> Class
1073 1474
1074This class implements timer watchers/events. Time is represented as a 1475This class implements timer watchers/events. Time is represented as a
1075fractional number of seconds since the epoch. Example: 1476fractional number of seconds since the epoch. Example:
1128 1529
1129 $term->{socket} = ... 1530 $term->{socket} = ...
1130 $term->{iow} = urxvt::iow 1531 $term->{iow} = urxvt::iow
1131 ->new 1532 ->new
1132 ->fd (fileno $term->{socket}) 1533 ->fd (fileno $term->{socket})
1133 ->events (1) # wait for read data 1534 ->events (urxvt::EVENT_READ)
1134 ->start 1535 ->start
1135 ->cb (sub { 1536 ->cb (sub {
1136 my ($iow, $revents) = @_; 1537 my ($iow, $revents) = @_;
1137 # $revents must be 1 here, no need to check 1538 # $revents must be 1 here, no need to check
1138 sysread $term->{socket}, my $buf, 8192 1539 sysread $term->{socket}, my $buf, 8192
1155 1556
1156Set the filedescriptor (not handle) to watch. 1557Set the filedescriptor (not handle) to watch.
1157 1558
1158=item $iow = $iow->events ($eventmask) 1559=item $iow = $iow->events ($eventmask)
1159 1560
1160Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1561Set the event mask to watch. The only allowed values are
1161data, Bit #1 (value C<2>) enables watching for write data. 1562C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1563together, or C<urxvt::EVENT_NONE>.
1162 1564
1163=item $iow = $iow->start 1565=item $iow = $iow->start
1164 1566
1165Start watching for requested events on the given handle. 1567Start watching for requested events on the given handle.
1166 1568
1177This variable controls the verbosity level of the perl extension. Higher 1579This variable controls the verbosity level of the perl extension. Higher
1178numbers indicate more verbose output. 1580numbers indicate more verbose output.
1179 1581
1180=over 4 1582=over 4
1181 1583
1182=item =0 - only fatal messages 1584=item == 0 - fatal messages
1183 1585
1184=item =3 - script loading and management 1586=item >= 3 - script loading and management
1185 1587
1186=item =10 - all events received 1588=item >=10 - all events received
1187 1589
1188=back 1590=back
1189 1591
1190=head1 AUTHOR 1592=head1 AUTHOR
1191 1593

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines