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.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 (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 { 620# urxvt::term::extension
557 $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 =~ /:([^:]+)$/
558 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 662 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
559 663
560 eval qq{ 664 eval qq{
561 sub $urxvt::term::proxy::AUTOLOAD { 665 sub $AUTOLOAD {
562 my \$proxy = shift; 666 my \$proxy = shift;
563 \$proxy->{term}->$1 (\@_) 667 \$proxy->{term}->$1 (\@_)
564 } 668 }
565 1 669 1
566 } or die "FATAL: unable to compile method forwarder: $@"; 670 } or die "FATAL: unable to compile method forwarder: $@";
567 671
568 goto &$urxvt::term::proxy::AUTOLOAD; 672 goto &$AUTOLOAD;
569} 673}
674
675sub DESTROY {
676 # nop
677}
678
679# urxvt::destroy_hook
570 680
571sub urxvt::destroy_hook::DESTROY { 681sub urxvt::destroy_hook::DESTROY {
572 ${$_[0]}->(); 682 ${$_[0]}->();
573} 683}
574 684
575sub urxvt::destroy_hook(&) { 685sub urxvt::destroy_hook(&) {
576 bless \shift, urxvt::destroy_hook:: 686 bless \shift, urxvt::destroy_hook::
577} 687}
578 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
579=head2 The C<urxvt::term> Class 759=head2 The C<urxvt::term> Class
580 760
581=over 4 761=over 4
582 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
583=item $term->destroy 804=item $term->destroy
584 805
585Destroy 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.
586 809
587=item $isset = $term->option ($optval[, $set]) 810=item $isset = $term->option ($optval[, $set])
588 811
589Returns true if the option specified by C<$optval> is enabled, and 812Returns true if the option specified by C<$optval> is enabled, and
590optionally 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
634 shade term_name title transparent transparent_all tripleclickwords 857 shade term_name title transparent transparent_all tripleclickwords
635 utmpInhibit visualBell 858 utmpInhibit visualBell
636 859
637=cut 860=cut
638 861
639sub urxvt::term::resource($$;$) { 862sub resource($$;$) {
640 my ($self, $name) = (shift, shift); 863 my ($self, $name) = (shift, shift);
641 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 864 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
642 &urxvt::term::_resource 865 &urxvt::term::_resource
643} 866}
644 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
645=item $rend = $term->rstyle ([$new_rstyle]) 884=item $rend = $term->rstyle ([$new_rstyle])
646 885
647Return and optionally change the current rendition. Text that is output by 886Return and optionally change the current rendition. Text that is output by
648the terminal application will use this style. 887the terminal application will use this style.
649 888
668 907
669=item $oldtext = $term->selection ([$newtext]) 908=item $oldtext = $term->selection ([$newtext])
670 909
671Return the current selection text and optionally replace it by C<$newtext>. 910Return the current selection text and optionally replace it by C<$newtext>.
672 911
673#=item $term->overlay ($x, $y, $text) 912=item $term->overlay_simple ($x, $y, $text)
674# 913
675#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.
676# 915
677#=cut 916=cut
678# 917
679#sub urxvt::term::scr_overlay { 918sub overlay_simple {
680# my ($self, $x, $y, $text) = @_; 919 my ($self, $x, $y, $text) = @_;
681# 920
682# my @lines = split /\n/, $text; 921 my @lines = split /\n/, $text;
683# 922
684# my $w = 0; 923 my $w = List::Util::max map $self->strwidth ($_), @lines;
685# for (map $self->strwidth ($_), @lines) { 924
686# $w = $_ if $w < $_;
687# }
688#
689# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 925 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
690# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 926 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
691#} 927
928 $overlay
929}
692 930
693=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 931=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
694 932
695Create a new (empty) overlay at the given position with the given 933Create a new (empty) overlay at the given position with the given
696width/height. C<$rstyle> defines the initial rendition style 934width/height. C<$rstyle> defines the initial rendition style
731C<$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,
732currently). 970currently).
733 971
734=cut 972=cut
735 973
736sub urxvt::term::popup { 974sub popup {
737 my ($self, $event) = @_; 975 my ($self, $event) = @_;
738 976
739 $self->grab ($event->{time}, 1) 977 $self->grab ($event->{time}, 1)
740 or return; 978 or return;
741 979
763 1001
764=item $string = $term->locale_decode ($octets) 1002=item $string = $term->locale_decode ($octets)
765 1003
766Convert the given locale-encoded octets into a perl string. 1004Convert the given locale-encoded octets into a perl string.
767 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
768=item $term->scr_add_lines ($string) 1023=item $term->scr_add_lines ($string)
769 1024
770Write 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
771running inside the terminal. It may not contain command sequences (escape 1026running inside the terminal. It may not contain command sequences (escape
772codes), 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
786 1041
787Write 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
788pass characters instead of octets, you should convert your strings first 1043pass characters instead of octets, you should convert your strings first
789to the locale-specific encoding using C<< $term->locale_encode >>. 1044to the locale-specific encoding using C<< $term->locale_encode >>.
790 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
791=item $windowid = $term->parent 1053=item $windowid = $term->parent
792 1054
793Return the window id of the toplevel window. 1055Return the window id of the toplevel window.
794 1056
795=item $windowid = $term->vt 1057=item $windowid = $term->vt
819=item $nrow_plus_saveLines = $term->total_rows 1081=item $nrow_plus_saveLines = $term->total_rows
820 1082
821=item $lines_in_scrollback = $term->nsaved 1083=item $lines_in_scrollback = $term->nsaved
822 1084
823Return 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}
824 1109
825=item $modifiermask = $term->ModLevel3Mask 1110=item $modifiermask = $term->ModLevel3Mask
826 1111
827=item $modifiermask = $term->ModMetaMask 1112=item $modifiermask = $term->ModMetaMask
828 1113
931 1216
932=back 1217=back
933 1218
934=cut 1219=cut
935 1220
936sub urxvt::term::line { 1221sub line {
937 my ($self, $row) = @_; 1222 my ($self, $row) = @_;
938 1223
939 my $maxrow = $self->nrow - 1; 1224 my $maxrow = $self->nrow - 1;
940 1225
941 my ($beg, $end) = ($row, $row); 1226 my ($beg, $end) = ($row, $row);
1005 $offset / $self->{ncol} + $self->{beg}, 1290 $offset / $self->{ncol} + $self->{beg},
1006 $offset % $self->{ncol} 1291 $offset % $self->{ncol}
1007 ) 1292 )
1008} 1293}
1009 1294
1010=item ($row, $col) = $line->coord_of ($offset)
1011=item $text = $term->special_encode $string 1295=item $text = $term->special_encode $string
1012 1296
1013Converts a perl string into the special encoding used by rxvt-unicode, 1297Converts a perl string into the special encoding used by rxvt-unicode,
1014where one character corresponds to one screen cell. See 1298where one character corresponds to one screen cell. See
1015C<< $term->ROW_t >> for details. 1299C<< $term->ROW_t >> for details.
1017=item $string = $term->special_decode $text 1301=item $string = $term->special_decode $text
1018 1302
1019Converts rxvt-unicodes text reprsentation into a perl string. See 1303Converts rxvt-unicodes text reprsentation into a perl string. See
1020C<< $term->ROW_t >> for details. 1304C<< $term->ROW_t >> for details.
1021 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
1022=back 1334=back
1023 1335
1336=cut
1337
1338package urxvt::popup;
1339
1024=head2 The C<urxvt::popup> Class 1340=head2 The C<urxvt::popup> Class
1025 1341
1026=over 4 1342=over 4
1027 1343
1028=cut 1344=cut
1029
1030package urxvt::popup;
1031 1345
1032sub add_item { 1346sub add_item {
1033 my ($self, $item) = @_; 1347 my ($self, $item) = @_;
1034 1348
1035 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal}; 1349 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1039 $item->{render} ||= sub { $_[0]{text} }; 1353 $item->{render} ||= sub { $_[0]{text} };
1040 1354
1041 push @{ $self->{item} }, $item; 1355 push @{ $self->{item} }, $item;
1042} 1356}
1043 1357
1044sub add_separator { 1358=item $popup->add_title ($title)
1045 my ($self, $sep) = @_;
1046 1359
1047 $sep ||= "═"; 1360Adds a non-clickable title to the popup.
1048 1361
1049 $self->add_item ({ 1362=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 1363
1057sub add_title { 1364sub add_title {
1058 my ($self, $title) = @_; 1365 my ($self, $title) = @_;
1059 1366
1060 $self->add_item ({ 1367 $self->add_item ({
1062 text => $title, 1369 text => $title,
1063 activate => sub { }, 1370 activate => sub { },
1064 }); 1371 });
1065} 1372}
1066 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
1399
1067sub add_button { 1400sub add_button {
1068 my ($self, $text, $cb) = @_; 1401 my ($self, $text, $cb) = @_;
1069 1402
1070 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb}); 1403 $self->add_item ({ type => "button", text => $text, activate => $cb});
1071} 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
1072 1413
1073sub add_toggle { 1414sub add_toggle {
1074 my ($self, $text, $cb, $value) = @_; 1415 my ($self, $text, $cb, $value) = @_;
1075 1416
1076 my $item; $item = { 1417 my $item; $item = {
1077 type => "button", 1418 type => "button",
1078 text => " $text", 1419 text => " $text",
1079 value => $value, 1420 value => $value,
1080 render => sub { ($item->{value} ? "* " : " ") . $text }, 1421 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1081 activate => sub { $cb->($item->{value} = !$item->{value}); }, 1422 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1082 }; 1423 };
1083 1424
1084 $self->add_item ($item); 1425 $self->add_item ($item);
1085} 1426}
1427
1428=item $popup->show
1429
1430Displays the popup (which is initially hidden).
1431
1432=cut
1086 1433
1087sub show { 1434sub show {
1088 my ($self) = @_; 1435 my ($self) = @_;
1089 1436
1090 local $urxvt::popup::self = $self; 1437 local $urxvt::popup::self = $self;
1091 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"),
1092 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,
1093 "--transient-for" => $self->{term}->parent, 1446 "--transient-for" => $self->{term}->parent,
1447 "-display" => $self->{term}->display_id,
1094 "-pe" => "urxvt-popup") 1448 "-pe" => "urxvt-popup")
1095 or die "unable to create popup window\n"; 1449 or die "unable to create popup window\n";
1096} 1450}
1097 1451
1098sub DESTROY { 1452sub DESTROY {
1099 my ($self) = @_; 1453 my ($self) = @_;
1100 1454
1455 delete $self->{term}{_destroy}{$self};
1101 $self->{term}->ungrab; 1456 $self->{term}->ungrab;
1102} 1457}
1458
1459=back
1103 1460
1104=head2 The C<urxvt::timer> Class 1461=head2 The C<urxvt::timer> Class
1105 1462
1106This class implements timer watchers/events. Time is represented as a 1463This class implements timer watchers/events. Time is represented as a
1107fractional number of seconds since the epoch. Example: 1464fractional number of seconds since the epoch. Example:
1160 1517
1161 $term->{socket} = ... 1518 $term->{socket} = ...
1162 $term->{iow} = urxvt::iow 1519 $term->{iow} = urxvt::iow
1163 ->new 1520 ->new
1164 ->fd (fileno $term->{socket}) 1521 ->fd (fileno $term->{socket})
1165 ->events (1) # wait for read data 1522 ->events (urxvt::EVENT_READ)
1166 ->start 1523 ->start
1167 ->cb (sub { 1524 ->cb (sub {
1168 my ($iow, $revents) = @_; 1525 my ($iow, $revents) = @_;
1169 # $revents must be 1 here, no need to check 1526 # $revents must be 1 here, no need to check
1170 sysread $term->{socket}, my $buf, 8192 1527 sysread $term->{socket}, my $buf, 8192
1187 1544
1188Set the filedescriptor (not handle) to watch. 1545Set the filedescriptor (not handle) to watch.
1189 1546
1190=item $iow = $iow->events ($eventmask) 1547=item $iow = $iow->events ($eventmask)
1191 1548
1192Set 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
1193data, 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>.
1194 1552
1195=item $iow = $iow->start 1553=item $iow = $iow->start
1196 1554
1197Start watching for requested events on the given handle. 1555Start watching for requested events on the given handle.
1198 1556
1209This variable controls the verbosity level of the perl extension. Higher 1567This variable controls the verbosity level of the perl extension. Higher
1210numbers indicate more verbose output. 1568numbers indicate more verbose output.
1211 1569
1212=over 4 1570=over 4
1213 1571
1214=item =0 - only fatal messages 1572=item == 0 - fatal messages
1215 1573
1216=item =3 - script loading and management 1574=item >= 3 - script loading and management
1217 1575
1218=item =10 - all events received 1576=item >=10 - all events received
1219 1577
1220=back 1578=back
1221 1579
1222=head1 AUTHOR 1580=head1 AUTHOR
1223 1581

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines