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.54 by root, Sun Jan 8 01:59:29 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 (enabled by default) 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
58 58
59=back 59=back
60 60
61=item option-popup (enabled by default) 61=item option-popup (enabled by default)
62 62
63Binds a popup menu to Ctrl-Button3 that lets you toggle (some) options at 63Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
64runtime. 64runtime.
65 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
66=item digital-clock 83=item digital-clock
67 84
68Displays a digital clock using the built-in overlay. 85Displays a digital clock using the built-in overlay.
69 86
70=item mark-urls 87=item mark-urls
71 88
72Uses 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.
73 92
74=item block-graphics-to-ascii 93=item block-graphics-to-ascii
75 94
76A 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,
77by replacing all line-drawing characters (U+2500 .. U+259F) by a 96by replacing all line-drawing characters (U+2500 .. U+259F) by a
82Displays 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
83window. Illustrates overwriting the refresh callbacks to create your own 102window. Illustrates overwriting the refresh callbacks to create your own
84overlays or changes. 103overlays or changes.
85 104
86=back 105=back
106
107=head1 API DOCUMENTATION
87 108
88=head2 General API Considerations 109=head2 General API Considerations
89 110
90All objects (such as terminals, time watchers etc.) are typical 111All objects (such as terminals, time watchers etc.) are typical
91reference-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
104=over 4 125=over 4
105 126
106=item $text 127=item $text
107 128
108Rxvt-unicodes special way of encoding text, where one "unicode" character 129Rxvt-unicodes special way of encoding text, where one "unicode" character
109always 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.
110 131
111=item $string 132=item $string
112 133
113A 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
114characters and is to be distinguished with text encoded in a specific 135characters and is to be distinguished with text encoded in a specific
119Either binary data or - more common - a text string encoded in a 140Either binary data or - more common - a text string encoded in a
120locale-specific way. 141locale-specific way.
121 142
122=back 143=back
123 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
124=head2 Hooks 178=head2 Hooks
125 179
126The following subroutines can be declared in extension files, and will be 180The following subroutines can be declared in extension files, and will be
127called whenever the relevant event happens. 181called whenever the relevant event happens.
128 182
129The 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
130and extension package. You can call all C<urxvt::term> methods on it, but 184the in the C<Extension Objects> section.
131its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
132object that is shared between all packages is stored in the C<term>
133member. It is, however, blessed intot he package of the extension script,
134so for all practical purposes you can treat an extension script as a class.
135 185
136All 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
137counts 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
138and 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.
139 189
140When in doubt, return a false value (preferably C<()>). 190I<< When in doubt, return a false value (preferably C<()>). >>
141 191
142=over 4 192=over 4
143 193
144=item on_init $term 194=item on_init $term
145 195
199than the scroll back buffer or the terminal. 249than the scroll back buffer or the terminal.
200 250
201It 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,
202$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
203number of lines that will be in the scrollback buffer. 253number of lines that will be in the scrollback buffer.
204
205=item on_tty_activity $term *NYI*
206
207Called whenever the program(s) running in the urxvt window send output.
208 254
209=item on_osc_seq $term, $string 255=item on_osc_seq $term, $string
210 256
211Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 257Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
212operating system command) is processed. Cursor position and other state 258operating system command) is processed. Cursor position and other state
225can 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
226and calling C<< $term->scr_add_lines >> yourself. Please note that this 272and calling C<< $term->scr_add_lines >> yourself. Please note that this
227might 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
228output. 274output.
229 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
230=item on_line_update $term, $row 281=item on_line_update $term, $row
231 282
232Called 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
233screen output (e.g. underline urls or other useless stuff). Only lines 284screen output (e.g. underline urls or other useless stuff). Only lines
234that are being shown will be filtered, and, due to performance reasons, 285that are being shown will be filtered, and, due to performance reasons,
266=item on_focus_out $term 317=item on_focus_out $term
267 318
268Called wheneever the window loses keyboard focus, before rxvt-unicode does 319Called wheneever the window loses keyboard focus, before rxvt-unicode does
269focus out processing. 320focus out processing.
270 321
271=item on_key_press $term, $event, $octets 322=item on_key_press $term, $event, $keysym, $octets
272 323
273=item on_key_release $term, $event 324=item on_key_release $term, $event, $keysym
274 325
275=item on_button_press $term, $event 326=item on_button_press $term, $event
276 327
277=item on_button_release $term, $event 328=item on_button_release $term, $event
278 329
294 345
295subwindow. 346subwindow.
296 347
297=back 348=back
298 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
299=head2 Variables in the C<urxvt> Package 371=head2 Variables in the C<urxvt> Package
300 372
301=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>.
302 387
303=item $urxvt::TERM 388=item $urxvt::TERM
304 389
305The current terminal. This variable stores the current C<urxvt::term> 390The current terminal. This variable stores the current C<urxvt::term>
306object, whenever a callback/hook is executing. 391object, whenever a callback/hook is executing.
308=back 393=back
309 394
310=head2 Functions in the C<urxvt> Package 395=head2 Functions in the C<urxvt> Package
311 396
312=over 4 397=over 4
313
314=item $term = new urxvt [arg...]
315
316Creates a new terminal, very similar as if you had started it with
317C<system $binfile, arg...>. Croaks (and probably outputs an error message)
318if the new instance couldn't be created. Returns C<undef> if the new
319instance didn't initialise perl, and the terminal object otherwise. The
320C<init> and C<start> hooks will be called during the call.
321 398
322=item urxvt::fatal $errormessage 399=item urxvt::fatal $errormessage
323 400
324Fatally aborts execution with the given error message. Avoid at all 401Fatally aborts execution with the given error message. Avoid at all
325costs! The only time this is acceptable is when the terminal process 402costs! The only time this is acceptable is when the terminal process
332that calls this function. 409that calls this function.
333 410
334Using 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
335correct place, e.g. on stderr of the connecting urxvtc client. 412correct place, e.g. on stderr of the connecting urxvtc client.
336 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
337=item $time = urxvt::NOW 422=item $time = urxvt::NOW
338 423
339Returns the "current time" (as per the event loop). 424Returns the "current time" (as per the event loop).
340 425
341=item urxvt::CurrentTime 426=item urxvt::CurrentTime
342 427
343=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 428=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
344Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 429Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
345Button4Mask, Button5Mask, AnyModifier 430Button4Mask, Button5Mask, AnyModifier
346 431
347Various constants for use in X events. 432Various constants for use in X calls and event processing.
348 433
349=back 434=back
350 435
351=head2 RENDITION 436=head2 RENDITION
352 437
379 464
380=item $background = urxvt::GET_BASEBG $rend 465=item $background = urxvt::GET_BASEBG $rend
381 466
382Return the foreground/background colour index, respectively. 467Return the foreground/background colour index, respectively.
383 468
384=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 469=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
385 470
386=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 471=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
387 472
388Replace the foreground/background colour in the rendition mask with the 473Replace the foreground/background colour in the rendition mask with the
389specified one. 474specified one.
390 475
391=item $value = urxvt::GET_CUSTOM ($rend) 476=item $value = urxvt::GET_CUSTOM $rend
392 477
393Return the "custom" value: Every rendition has 5 bits for use by 478Return the "custom" value: Every rendition has 5 bits for use by
394extensions. 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
395zero. 480zero.
396 481
397=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 482=item $rend = urxvt::SET_CUSTOM $rend, $new_value
398 483
399Change the custom value. 484Change the custom value.
400 485
401=back 486=back
402 487
403=cut 488=cut
404
405package urxvt;
406
407use utf8;
408use strict;
409use Scalar::Util ();
410use List::Util ();
411
412our $TERM;
413our @HOOKNAME;
414our %OPTION;
415our $LIBDIR;
416 489
417BEGIN { 490BEGIN {
418 urxvt->bootstrap; 491 urxvt->bootstrap;
419 492
420 # overwrite perl's warn 493 # overwrite perl's warn
422 my $msg = join "", @_; 495 my $msg = join "", @_;
423 $msg .= "\n" 496 $msg .= "\n"
424 unless $msg =~ /\n$/; 497 unless $msg =~ /\n$/;
425 urxvt::warn ($msg); 498 urxvt::warn ($msg);
426 }; 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";
427} 506}
428 507
429my @hook_count; 508my @hook_count;
430my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 509my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
431 510
432sub verbose { 511sub verbose {
433 my ($level, $msg) = @_; 512 my ($level, $msg) = @_;
434 warn "$msg\n" if $level <= $verbosity; 513 warn "$msg\n" if $level <= $verbosity;
435} 514}
436 515
437# find on_xxx subs in the package and register them
438# as hooks
439sub register_package($) {
440 my ($pkg) = @_;
441
442 for my $htype (0.. $#HOOKNAME) {
443 my $name = $HOOKNAME[$htype];
444
445 my $ref = $pkg->can ("on_" . lc $name)
446 or next;
447
448 $TERM->{_hook}[$htype]{$pkg} = $ref;
449 $hook_count[$htype]++
450 or set_should_invoke $htype, 1;
451 }
452}
453
454my $extension_pkg = "extension0000"; 516my $extension_pkg = "extension0000";
455my %extension_pkg; 517my %extension_pkg;
456 518
457# load a single script into its own package, once only 519# load a single script into its own package, once only
458sub extension_package($) { 520sub extension_package($) {
464 verbose 3, "loading extension '$path' into package '$pkg'"; 526 verbose 3, "loading extension '$path' into package '$pkg'";
465 527
466 open my $fh, "<:raw", $path 528 open my $fh, "<:raw", $path
467 or die "$path: $!"; 529 or die "$path: $!";
468 530
531 my $source = untaint
469 my $source = "package $pkg; use strict; use utf8;\n" 532 "package $pkg; use strict; use utf8;\n"
470 . "use base urxvt::term::proxy::;\n" 533 . "use base urxvt::term::extension::;\n"
471 . "#line 1 \"$path\"\n{\n" 534 . "#line 1 \"$path\"\n{\n"
472 . (do { local $/; <$fh> }) 535 . (do { local $/; <$fh> })
473 . "\n};\n1"; 536 . "\n};\n1";
474 537
538 eval $source
475 eval $source or die "$path: $@"; 539 or die "$path: $@";
476 540
477 $pkg 541 $pkg
478 } 542 }
479} 543}
480 544
486 my $htype = shift; 550 my $htype = shift;
487 551
488 if ($htype == 0) { # INIT 552 if ($htype == 0) { # INIT
489 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 553 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
490 554
491 my %want_ext; 555 my %ext_arg;
492 556
493 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 557 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
494 if ($_ eq "default") { 558 if ($_ eq "default") {
495 $want_ext{$_}++ for qw(selection option-popup); 559 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
496 } elsif (/^-(.*)$/) { 560 } elsif (/^-(.*)$/) {
497 delete $want_ext{$1}; 561 delete $ext_arg{$1};
562 } elsif (/^([^<]+)<(.*)>$/) {
563 push @{ $ext_arg{$1} }, $2;
498 } else { 564 } else {
499 $want_ext{$_}++; 565 $ext_arg{$_} ||= [];
500 } 566 }
501 } 567 }
502 568
503 for my $ext (keys %want_ext) { 569 while (my ($ext, $argv) = each %ext_arg) {
504 my @files = grep -f $_, map "$_/$ext", @dirs; 570 my @files = grep -f $_, map "$_/$ext", @dirs;
505 571
506 if (@files) { 572 if (@files) {
507 register_package extension_package $files[0]; 573 $TERM->register_package (extension_package $files[0], $argv);
508 } else { 574 } else {
509 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";
510 } 576 }
511 } 577 }
578
579 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
580 warn $@ if $@;
512 } 581 }
513 582
514 $retval = undef; 583 $retval = undef;
515 584
516 if (my $cb = $TERM->{_hook}[$htype]) { 585 if (my $cb = $TERM->{_hook}[$htype]) {
518 if $verbosity >= 10; 587 if $verbosity >= 10;
519 588
520 keys %$cb; 589 keys %$cb;
521 590
522 while (my ($pkg, $cb) = each %$cb) { 591 while (my ($pkg, $cb) = each %$cb) {
523 eval { 592 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
524 $retval = $cb->(
525 $TERM->{_pkg}{$pkg} ||= do {
526 my $proxy = bless { }, $pkg;
527 Scalar::Util::weaken ($proxy->{term} = $TERM);
528 $proxy
529 },
530 @_,
531 ) and last; 593 and last;
594
595 if ($@) {
596 $TERM->ungrab; # better to lose the grab than the session
597 warn $@;
532 }; 598 }
533 warn $@ if $@;#d#
534 } 599 }
535 } 600 }
536 601
537 if ($htype == 1) { # DESTROY 602 if ($htype == 1) { # DESTROY
538 # remove hooks if unused
539 if (my $hook = $TERM->{_hook}) { 603 if (my $hook = delete $TERM->{_hook}) {
540 for my $htype (0..$#$hook) { 604 for my $htype (0..$#$hook) {
541 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 605 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
542 or set_should_invoke $htype, 0; 606 or set_should_invoke $htype, 0;
543 } 607 }
544 } 608 }
551 } 615 }
552 616
553 $retval 617 $retval
554} 618}
555 619
556sub urxvt::term::proxy::AUTOLOAD { 620sub exec_async(@) {
557 $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 =~ /:([^:]+)$/
558 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 674 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
559 675
560 eval qq{ 676 eval qq{
561 sub $urxvt::term::proxy::AUTOLOAD { 677 sub $AUTOLOAD {
562 my \$proxy = shift; 678 my \$proxy = shift;
563 \$proxy->{term}->$1 (\@_) 679 \$proxy->{term}->$1 (\@_)
564 } 680 }
565 1 681 1
566 } or die "FATAL: unable to compile method forwarder: $@"; 682 } or die "FATAL: unable to compile method forwarder: $@";
567 683
568 goto &$urxvt::term::proxy::AUTOLOAD; 684 goto &$AUTOLOAD;
569} 685}
686
687sub DESTROY {
688 # nop
689}
690
691# urxvt::destroy_hook
570 692
571sub urxvt::destroy_hook::DESTROY { 693sub urxvt::destroy_hook::DESTROY {
572 ${$_[0]}->(); 694 ${$_[0]}->();
573} 695}
574 696
575sub urxvt::destroy_hook(&) { 697sub urxvt::destroy_hook(&) {
576 bless \shift, urxvt::destroy_hook:: 698 bless \shift, urxvt::destroy_hook::
577} 699}
578 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
579=head2 The C<urxvt::term> Class 771=head2 The C<urxvt::term> Class
580 772
581=over 4 773=over 4
582 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
583=item $term->destroy 816=item $term->destroy
584 817
585Destroy 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.
586 821
587=item $isset = $term->option ($optval[, $set]) 822=item $isset = $term->option ($optval[, $set])
588 823
589Returns true if the option specified by C<$optval> is enabled, and 824Returns true if the option specified by C<$optval> is enabled, and
590optionally 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
634 shade term_name title transparent transparent_all tripleclickwords 869 shade term_name title transparent transparent_all tripleclickwords
635 utmpInhibit visualBell 870 utmpInhibit visualBell
636 871
637=cut 872=cut
638 873
639sub urxvt::term::resource($$;$) { 874sub resource($$;$) {
640 my ($self, $name) = (shift, shift); 875 my ($self, $name) = (shift, shift);
641 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 876 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
642 &urxvt::term::_resource 877 &urxvt::term::_resource
643} 878}
644 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
645=item $rend = $term->rstyle ([$new_rstyle]) 896=item $rend = $term->rstyle ([$new_rstyle])
646 897
647Return and optionally change the current rendition. Text that is output by 898Return and optionally change the current rendition. Text that is output by
648the terminal application will use this style. 899the terminal application will use this style.
649 900
668 919
669=item $oldtext = $term->selection ([$newtext]) 920=item $oldtext = $term->selection ([$newtext])
670 921
671Return the current selection text and optionally replace it by C<$newtext>. 922Return the current selection text and optionally replace it by C<$newtext>.
672 923
673#=item $term->overlay ($x, $y, $text) 924=item $term->overlay_simple ($x, $y, $text)
674# 925
675#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.
676# 927
677#=cut 928=cut
678# 929
679#sub urxvt::term::scr_overlay { 930sub overlay_simple {
680# my ($self, $x, $y, $text) = @_; 931 my ($self, $x, $y, $text) = @_;
681# 932
682# my @lines = split /\n/, $text; 933 my @lines = split /\n/, $text;
683# 934
684# my $w = 0; 935 my $w = List::Util::max map $self->strwidth ($_), @lines;
685# for (map $self->strwidth ($_), @lines) { 936
686# $w = $_ if $w < $_;
687# }
688#
689# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 937 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
690# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 938 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
691#} 939
940 $overlay
941}
692 942
693=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 943=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
694 944
695Create a new (empty) overlay at the given position with the given 945Create a new (empty) overlay at the given position with the given
696width/height. C<$rstyle> defines the initial rendition style 946width/height. C<$rstyle> defines the initial rendition style
731C<$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,
732currently). 982currently).
733 983
734=cut 984=cut
735 985
736sub urxvt::term::popup { 986sub popup {
737 my ($self, $event) = @_; 987 my ($self, $event) = @_;
738 988
739 $self->grab ($event->{time}, 1) 989 $self->grab ($event->{time}, 1)
740 or return; 990 or return;
741 991
763 1013
764=item $string = $term->locale_decode ($octets) 1014=item $string = $term->locale_decode ($octets)
765 1015
766Convert the given locale-encoded octets into a perl string. 1016Convert the given locale-encoded octets into a perl string.
767 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
768=item $term->scr_add_lines ($string) 1035=item $term->scr_add_lines ($string)
769 1036
770Write 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
771running inside the terminal. It may not contain command sequences (escape 1038running inside the terminal. It may not contain command sequences (escape
772codes), 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
786 1053
787Write 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
788pass characters instead of octets, you should convert your strings first 1055pass characters instead of octets, you should convert your strings first
789to the locale-specific encoding using C<< $term->locale_encode >>. 1056to the locale-specific encoding using C<< $term->locale_encode >>.
790 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
791=item $windowid = $term->parent 1065=item $windowid = $term->parent
792 1066
793Return the window id of the toplevel window. 1067Return the window id of the toplevel window.
794 1068
795=item $windowid = $term->vt 1069=item $windowid = $term->vt
819=item $nrow_plus_saveLines = $term->total_rows 1093=item $nrow_plus_saveLines = $term->total_rows
820 1094
821=item $lines_in_scrollback = $term->nsaved 1095=item $lines_in_scrollback = $term->nsaved
822 1096
823Return 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}
824 1121
825=item $modifiermask = $term->ModLevel3Mask 1122=item $modifiermask = $term->ModLevel3Mask
826 1123
827=item $modifiermask = $term->ModMetaMask 1124=item $modifiermask = $term->ModMetaMask
828 1125
931 1228
932=back 1229=back
933 1230
934=cut 1231=cut
935 1232
936sub urxvt::term::line { 1233sub line {
937 my ($self, $row) = @_; 1234 my ($self, $row) = @_;
938 1235
939 my $maxrow = $self->nrow - 1; 1236 my $maxrow = $self->nrow - 1;
940 1237
941 my ($beg, $end) = ($row, $row); 1238 my ($beg, $end) = ($row, $row);
1005 $offset / $self->{ncol} + $self->{beg}, 1302 $offset / $self->{ncol} + $self->{beg},
1006 $offset % $self->{ncol} 1303 $offset % $self->{ncol}
1007 ) 1304 )
1008} 1305}
1009 1306
1010=item ($row, $col) = $line->coord_of ($offset)
1011=item $text = $term->special_encode $string 1307=item $text = $term->special_encode $string
1012 1308
1013Converts a perl string into the special encoding used by rxvt-unicode, 1309Converts a perl string into the special encoding used by rxvt-unicode,
1014where one character corresponds to one screen cell. See 1310where one character corresponds to one screen cell. See
1015C<< $term->ROW_t >> for details. 1311C<< $term->ROW_t >> for details.
1017=item $string = $term->special_decode $text 1313=item $string = $term->special_decode $text
1018 1314
1019Converts rxvt-unicodes text reprsentation into a perl string. See 1315Converts rxvt-unicodes text reprsentation into a perl string. See
1020C<< $term->ROW_t >> for details. 1316C<< $term->ROW_t >> for details.
1021 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
1022=back 1346=back
1023 1347
1348=cut
1349
1350package urxvt::popup;
1351
1024=head2 The C<urxvt::popup> Class 1352=head2 The C<urxvt::popup> Class
1025 1353
1026=over 4 1354=over 4
1027 1355
1028=cut 1356=cut
1029
1030package urxvt::popup;
1031 1357
1032sub add_item { 1358sub add_item {
1033 my ($self, $item) = @_; 1359 my ($self, $item) = @_;
1034 1360
1035 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal}; 1361 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1039 $item->{render} ||= sub { $_[0]{text} }; 1365 $item->{render} ||= sub { $_[0]{text} };
1040 1366
1041 push @{ $self->{item} }, $item; 1367 push @{ $self->{item} }, $item;
1042} 1368}
1043 1369
1044sub add_separator { 1370=item $popup->add_title ($title)
1045 my ($self, $sep) = @_;
1046 1371
1047 $sep ||= "═"; 1372Adds a non-clickable title to the popup.
1048 1373
1049 $self->add_item ({ 1374=cut
1050 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1051 text => "",
1052 render => sub { $sep x $urxvt::TERM->ncol },
1053 activate => sub { },
1054 });
1055}
1056 1375
1057sub add_title { 1376sub add_title {
1058 my ($self, $title) = @_; 1377 my ($self, $title) = @_;
1059 1378
1060 $self->add_item ({ 1379 $self->add_item ({
1062 text => $title, 1381 text => $title,
1063 activate => sub { }, 1382 activate => sub { },
1064 }); 1383 });
1065} 1384}
1066 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
1411
1067sub add_button { 1412sub add_button {
1068 my ($self, $text, $cb) = @_; 1413 my ($self, $text, $cb) = @_;
1069 1414
1070 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb}); 1415 $self->add_item ({ type => "button", text => $text, activate => $cb});
1071} 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
1072 1425
1073sub add_toggle { 1426sub add_toggle {
1074 my ($self, $text, $cb, $value) = @_; 1427 my ($self, $text, $cb, $value) = @_;
1075 1428
1076 my $item; $item = { 1429 my $item; $item = {
1077 type => "button", 1430 type => "button",
1078 text => " $text", 1431 text => " $text",
1079 value => $value, 1432 value => $value,
1080 render => sub { ($item->{value} ? "* " : " ") . $text }, 1433 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1081 activate => sub { $cb->($item->{value} = !$item->{value}); }, 1434 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1082 }; 1435 };
1083 1436
1084 $self->add_item ($item); 1437 $self->add_item ($item);
1085} 1438}
1439
1440=item $popup->show
1441
1442Displays the popup (which is initially hidden).
1443
1444=cut
1086 1445
1087sub show { 1446sub show {
1088 my ($self) = @_; 1447 my ($self) = @_;
1089 1448
1090 local $urxvt::popup::self = $self; 1449 local $urxvt::popup::self = $self;
1091 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"),
1092 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,
1093 "--transient-for" => $self->{term}->parent, 1458 "--transient-for" => $self->{term}->parent,
1459 "-display" => $self->{term}->display_id,
1094 "-pe" => "urxvt-popup") 1460 "-pe" => "urxvt-popup")
1095 or die "unable to create popup window\n"; 1461 or die "unable to create popup window\n";
1096} 1462}
1097 1463
1098sub DESTROY { 1464sub DESTROY {
1099 my ($self) = @_; 1465 my ($self) = @_;
1100 1466
1467 delete $self->{term}{_destroy}{$self};
1101 $self->{term}->ungrab; 1468 $self->{term}->ungrab;
1102} 1469}
1470
1471=back
1103 1472
1104=head2 The C<urxvt::timer> Class 1473=head2 The C<urxvt::timer> Class
1105 1474
1106This class implements timer watchers/events. Time is represented as a 1475This class implements timer watchers/events. Time is represented as a
1107fractional number of seconds since the epoch. Example: 1476fractional number of seconds since the epoch. Example:
1160 1529
1161 $term->{socket} = ... 1530 $term->{socket} = ...
1162 $term->{iow} = urxvt::iow 1531 $term->{iow} = urxvt::iow
1163 ->new 1532 ->new
1164 ->fd (fileno $term->{socket}) 1533 ->fd (fileno $term->{socket})
1165 ->events (1) # wait for read data 1534 ->events (urxvt::EVENT_READ)
1166 ->start 1535 ->start
1167 ->cb (sub { 1536 ->cb (sub {
1168 my ($iow, $revents) = @_; 1537 my ($iow, $revents) = @_;
1169 # $revents must be 1 here, no need to check 1538 # $revents must be 1 here, no need to check
1170 sysread $term->{socket}, my $buf, 8192 1539 sysread $term->{socket}, my $buf, 8192
1187 1556
1188Set the filedescriptor (not handle) to watch. 1557Set the filedescriptor (not handle) to watch.
1189 1558
1190=item $iow = $iow->events ($eventmask) 1559=item $iow = $iow->events ($eventmask)
1191 1560
1192Set 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
1193data, 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>.
1194 1564
1195=item $iow = $iow->start 1565=item $iow = $iow->start
1196 1566
1197Start watching for requested events on the given handle. 1567Start watching for requested events on the given handle.
1198 1568
1209This variable controls the verbosity level of the perl extension. Higher 1579This variable controls the verbosity level of the perl extension. Higher
1210numbers indicate more verbose output. 1580numbers indicate more verbose output.
1211 1581
1212=over 4 1582=over 4
1213 1583
1214=item =0 - only fatal messages 1584=item == 0 - fatal messages
1215 1585
1216=item =3 - script loading and management 1586=item >= 3 - script loading and management
1217 1587
1218=item =10 - all events received 1588=item >=10 - all events received
1219 1589
1220=back 1590=back
1221 1591
1222=head1 AUTHOR 1592=head1 AUTHOR
1223 1593

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines