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.47 by root, Sat Jan 7 21:22:02 2006 UTC vs.
Revision 1.77 by root, Wed Jan 11 00:59:58 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
55Rot-13 the selection when activated. Used via keyboard trigger: 55Rot-13 the selection when activated. Used via keyboard trigger:
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
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.
60 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
77Displays a very simple digital clock in the upper right corner of the 99Displays a very simple digital clock in the upper right corner of the
78window. Illustrates overwriting the refresh callbacks to create your own 100window. Illustrates overwriting the refresh callbacks to create your own
79overlays or changes. 101overlays or changes.
80 102
81=back 103=back
104
105=head1 API DOCUMENTATION
82 106
83=head2 General API Considerations 107=head2 General API Considerations
84 108
85All objects (such as terminals, time watchers etc.) are typical 109All objects (such as terminals, time watchers etc.) are typical
86reference-to-hash objects. The hash can be used to store anything you 110reference-to-hash objects. The hash can be used to store anything you
114Either binary data or - more common - a text string encoded in a 138Either binary data or - more common - a text string encoded in a
115locale-specific way. 139locale-specific way.
116 140
117=back 141=back
118 142
143=head2 Extension Objects
144
145Very perl extension is a perl class. A separate perl object is created
146for each terminal and each extension and passed as the first parameter to
147hooks. So extensions can use their C<$self> object without having to think
148about other extensions, with the exception of methods and members that
149begin with an underscore character C<_>: these are reserved for internal
150use.
151
152Although it isn't a C<urxvt::term> object, you can call all methods of the
153C<urxvt::term> class on this object.
154
155It has the following methods and data members:
156
157=over 4
158
159=item $urxvt_term = $self->{term}
160
161Returns the C<urxvt::term> object associated with this instance of the
162extension. This member I<must not> be changed in any way.
163
164=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
165
166Dynamically enable the given hooks (named without the C<on_> prefix) for
167this extension, replacing any previous hook. This is useful when you want
168to overwrite time-critical hooks only temporarily.
169
170=item $self->disable ($hook_name[, $hook_name..])
171
172Dynamically disable the given hooks.
173
174=back
175
119=head2 Hooks 176=head2 Hooks
120 177
121The following subroutines can be declared in extension files, and will be 178The following subroutines can be declared in extension files, and will be
122called whenever the relevant event happens. 179called whenever the relevant event happens.
123 180
124The first argument passed to them is an object private to each terminal 181The first argument passed to them is an extension oject as described in
125and extension package. You can call all C<urxvt::term> methods on it, but 182the 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 183
131All of them must return a boolean value. If it is true, then the event 184B<All> of these hooks must return a boolean value. If it is true, then the
132counts as being I<consumed>, and the invocation of other hooks is skipped, 185event counts as being I<consumed>, and the invocation of other hooks is
133and the relevant action might not be carried out by the C++ code. 186skipped, and the relevant action might not be carried out by the C++ code.
134 187
135When in doubt, return a false value (preferably C<()>). 188I<< When in doubt, return a false value (preferably C<()>). >>
136 189
137=over 4 190=over 4
138 191
139=item on_init $term 192=item on_init $term
140 193
194than the scroll back buffer or the terminal. 247than the scroll back buffer or the terminal.
195 248
196It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 249It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
197$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 250$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
198number of lines that will be in the scrollback buffer. 251number 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 252
204=item on_osc_seq $term, $string 253=item on_osc_seq $term, $string
205 254
206Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 255Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
207operating system command) is processed. Cursor position and other state 256operating system command) is processed. Cursor position and other state
220can filter/change and output the text yourself by returning a true value 269can filter/change and output the text yourself by returning a true value
221and calling C<< $term->scr_add_lines >> yourself. Please note that this 270and 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 271might be very slow, however, as your hook is called for B<all> text being
223output. 272output.
224 273
274=item on_tt_write $term, $octets
275
276Called whenever some data is written to the tty/pty and can be used to
277suppress or filter tty input.
278
225=item on_line_update $term, $row 279=item on_line_update $term, $row
226 280
227Called whenever a line was updated or changed. Can be used to filter 281Called whenever a line was updated or changed. Can be used to filter
228screen output (e.g. underline urls or other useless stuff). Only lines 282screen output (e.g. underline urls or other useless stuff). Only lines
229that are being shown will be filtered, and, due to performance reasons, 283that are being shown will be filtered, and, due to performance reasons,
261=item on_focus_out $term 315=item on_focus_out $term
262 316
263Called wheneever the window loses keyboard focus, before rxvt-unicode does 317Called wheneever the window loses keyboard focus, before rxvt-unicode does
264focus out processing. 318focus out processing.
265 319
266=item on_key_press $term, $event, $octets 320=item on_key_press $term, $event, $keysym, $octets
267 321
268=item on_key_release $term, $event 322=item on_key_release $term, $event, $keysym
269 323
270=item on_button_press $term, $event 324=item on_button_press $term, $event
271 325
272=item on_button_release $term, $event 326=item on_button_release $term, $event
273 327
289 343
290subwindow. 344subwindow.
291 345
292=back 346=back
293 347
348=cut
349
350package urxvt;
351
352use utf8;
353use strict;
354use Carp ();
355use Scalar::Util ();
356use List::Util ();
357
358our $VERSION = 1;
359our $TERM;
360our @HOOKNAME;
361our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
362our %OPTION;
363
364our $LIBDIR;
365our $RESNAME;
366our $RESCLASS;
367our $RXVTNAME;
368
294=head2 Variables in the C<urxvt> Package 369=head2 Variables in the C<urxvt> Package
295 370
296=over 4 371=over 4
372
373=item $urxvt::LIBDIR
374
375The rxvt-unicode library directory, where, among other things, the perl
376modules and scripts are stored.
377
378=item $urxvt::RESCLASS, $urxvt::RESCLASS
379
380The resource class and name rxvt-unicode uses to look up X resources.
381
382=item $urxvt::RXVTNAME
383
384The basename of the installed binaries, usually C<urxvt>.
297 385
298=item $urxvt::TERM 386=item $urxvt::TERM
299 387
300The current terminal. This variable stores the current C<urxvt::term> 388The current terminal. This variable stores the current C<urxvt::term>
301object, whenever a callback/hook is executing. 389object, whenever a callback/hook is executing.
302 390
391=item
392
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 strict;
403use Scalar::Util ();
404
405our $TERM;
406our @HOOKNAME;
407our $LIBDIR;
408 489
409BEGIN { 490BEGIN {
410 urxvt->bootstrap; 491 urxvt->bootstrap;
411 492
412 # overwrite perl's warn 493 # overwrite perl's warn
414 my $msg = join "", @_; 495 my $msg = join "", @_;
415 $msg .= "\n" 496 $msg .= "\n"
416 unless $msg =~ /\n$/; 497 unless $msg =~ /\n$/;
417 urxvt::warn ($msg); 498 urxvt::warn ($msg);
418 }; 499 };
500
501 delete $ENV{IFS};
502 delete $ENV{CDPATH};
503 delete $ENV{BASH_ENV};
504 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
419} 505}
420 506
421my @hook_count; 507my @hook_count;
422my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 508my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
423 509
424sub verbose { 510sub verbose {
425 my ($level, $msg) = @_; 511 my ($level, $msg) = @_;
426 warn "$msg\n" if $level <= $verbosity; 512 warn "$msg\n" if $level <= $verbosity;
427} 513}
428 514
429# find on_xxx subs in the package and register them
430# as hooks
431sub register_package($) {
432 my ($pkg) = @_;
433
434 for my $htype (0.. $#HOOKNAME) {
435 my $name = $HOOKNAME[$htype];
436
437 my $ref = $pkg->can ("on_" . lc $name)
438 or next;
439
440 $TERM->{_hook}[$htype]{$pkg} = $ref;
441 $hook_count[$htype]++
442 or set_should_invoke $htype, 1;
443 }
444}
445
446my $extension_pkg = "extension0000"; 515my $extension_pkg = "extension0000";
447my %extension_pkg; 516my %extension_pkg;
448 517
449# load a single script into its own package, once only 518# load a single script into its own package, once only
450sub extension_package($) { 519sub extension_package($) {
456 verbose 3, "loading extension '$path' into package '$pkg'"; 525 verbose 3, "loading extension '$path' into package '$pkg'";
457 526
458 open my $fh, "<:raw", $path 527 open my $fh, "<:raw", $path
459 or die "$path: $!"; 528 or die "$path: $!";
460 529
530 my $source = untaint
461 my $source = "package $pkg; use strict; use utf8;\n" 531 "package $pkg; use strict; use utf8;\n"
462 . "use base urxvt::term::proxy::;\n" 532 . "use base urxvt::term::extension::;\n"
463 . "#line 1 \"$path\"\n{\n" 533 . "#line 1 \"$path\"\n{\n"
464 . (do { local $/; <$fh> }) 534 . (do { local $/; <$fh> })
465 . "\n};\n1"; 535 . "\n};\n1";
466 536
537 eval $source
467 eval $source or die "$path: $@"; 538 or die "$path: $@";
468 539
469 $pkg 540 $pkg
470 } 541 }
471} 542}
472 543
477 local $TERM = shift; 548 local $TERM = shift;
478 my $htype = shift; 549 my $htype = shift;
479 550
480 if ($htype == 0) { # INIT 551 if ($htype == 0) { # INIT
481 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 552 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
553
554 my %ext_arg;
482 555
483 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 556 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
557 if ($_ eq "default") {
558 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
559 } elsif (/^-(.*)$/) {
560 delete $ext_arg{$1};
561 } elsif (/^([^<]+)<(.*)>$/) {
562 push @{ $ext_arg{$1} }, $2;
563 } else {
564 $ext_arg{$_} ||= [];
565 }
566 }
567
568 while (my ($ext, $argv) = each %ext_arg) {
484 my @files = grep -f $_, map "$_/$ext", @dirs; 569 my @files = grep -f $_, map "$_/$ext", @dirs;
485 570
486 if (@files) { 571 if (@files) {
487 register_package extension_package $files[0]; 572 $TERM->register_package (extension_package $files[0], $argv);
488 } else { 573 } else {
489 warn "perl extension '$ext' not found in perl library search path\n"; 574 warn "perl extension '$ext' not found in perl library search path\n";
490 } 575 }
491 } 576 }
577
578 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
579 warn $@ if $@;
492 } 580 }
493 581
494 $retval = undef; 582 $retval = undef;
495 583
496 if (my $cb = $TERM->{_hook}[$htype]) { 584 if (my $cb = $TERM->{_hook}[$htype]) {
498 if $verbosity >= 10; 586 if $verbosity >= 10;
499 587
500 keys %$cb; 588 keys %$cb;
501 589
502 while (my ($pkg, $cb) = each %$cb) { 590 while (my ($pkg, $cb) = each %$cb) {
503 eval { 591 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
504 $retval = $cb->(
505 $TERM->{_pkg}{$pkg} ||= do {
506 my $proxy = bless { }, $pkg;
507 Scalar::Util::weaken ($proxy->{term} = $TERM);
508 $proxy
509 },
510 @_,
511 ) and last; 592 and last;
593
594 if ($@) {
595 $TERM->ungrab; # better to lose the grab than the session
596 warn $@;
512 }; 597 }
513 warn $@ if $@;#d#
514 } 598 }
515 } 599 }
516 600
517 if ($htype == 1) { # DESTROY 601 if ($htype == 1) { # DESTROY
518 # remove hooks if unused
519 if (my $hook = $TERM->{_hook}) { 602 if (my $hook = delete $TERM->{_hook}) {
520 for my $htype (0..$#$hook) { 603 for my $htype (0..$#$hook) {
521 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 604 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
522 or set_should_invoke $htype, 0; 605 or set_should_invoke $htype, 0;
523 } 606 }
524 } 607 }
531 } 614 }
532 615
533 $retval 616 $retval
534} 617}
535 618
536sub urxvt::term::proxy::AUTOLOAD { 619# urxvt::term::extension
537 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 620
621package urxvt::term::extension;
622
623sub enable {
624 my ($self, %hook) = @_;
625 my $pkg = $self->{_pkg};
626
627 while (my ($name, $cb) = each %hook) {
628 my $htype = $HOOKTYPE{uc $name};
629 defined $htype
630 or Carp::croak "unsupported hook type '$name'";
631
632 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
633 $hook_count[$htype]++
634 or urxvt::set_should_invoke $htype, 1;
635 }
636
637 $self->{term}{_hook}[$htype]{$pkg} = $cb;
638 }
639}
640
641sub disable {
642 my ($self, @hook) = @_;
643 my $pkg = $self->{_pkg};
644
645 for my $name (@hook) {
646 my $htype = $HOOKTYPE{uc $name};
647 defined $htype
648 or Carp::croak "unsupported hook type '$name'";
649
650 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
651 --$hook_count[$htype]
652 or urxvt::set_should_invoke $htype, 0;
653 }
654 }
655}
656
657our $AUTOLOAD;
658
659sub AUTOLOAD {
660 $AUTOLOAD =~ /:([^:]+)$/
538 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 661 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
539 662
540 eval qq{ 663 eval qq{
541 sub $urxvt::term::proxy::AUTOLOAD { 664 sub $AUTOLOAD {
542 my \$proxy = shift; 665 my \$proxy = shift;
543 \$proxy->{term}->$1 (\@_) 666 \$proxy->{term}->$1 (\@_)
544 } 667 }
545 1 668 1
546 } or die "FATAL: unable to compile method forwarder: $@"; 669 } or die "FATAL: unable to compile method forwarder: $@";
547 670
548 goto &$urxvt::term::proxy::AUTOLOAD; 671 goto &$AUTOLOAD;
549} 672}
673
674sub DESTROY {
675 # nop
676}
677
678# urxvt::destroy_hook
550 679
551sub urxvt::destroy_hook::DESTROY { 680sub urxvt::destroy_hook::DESTROY {
552 ${$_[0]}->(); 681 ${$_[0]}->();
553} 682}
554 683
555sub urxvt::destroy_hook(&) { 684sub urxvt::destroy_hook(&) {
556 bless \shift, urxvt::destroy_hook:: 685 bless \shift, urxvt::destroy_hook::
557} 686}
558 687
688package urxvt::anyevent;
689
690=head2 The C<urxvt::anyevent> Class
691
692The sole purpose of this class is to deliver an interface to the
693C<AnyEvent> module - any module using it will work inside urxvt without
694further programming. The only exception is that you cannot wait on
695condition variables, but non-blocking condvar use is ok. What this means
696is that you cannot use blocking APIs, but the non-blocking variant should
697work.
698
699=cut
700
701our $VERSION = 1;
702
703$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
704push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
705
706sub timer {
707 my ($class, %arg) = @_;
708
709 my $cb = $arg{cb};
710
711 urxvt::timer
712 ->new
713 ->start (urxvt::NOW + $arg{after})
714 ->cb (sub {
715 $_[0]->stop; # need to cancel manually
716 $cb->();
717 })
718}
719
720sub io {
721 my ($class, %arg) = @_;
722
723 my $cb = $arg{cb};
724
725 bless [$arg{fh}, urxvt::iow
726 ->new
727 ->fd (fileno $arg{fh})
728 ->events (($arg{poll} =~ /r/ ? 1 : 0)
729 | ($arg{poll} =~ /w/ ? 2 : 0))
730 ->start
731 ->cb (sub {
732 $cb->(($_[1] & 1 ? 'r' : '')
733 . ($_[1] & 2 ? 'w' : ''));
734 })],
735 urxvt::anyevent::
736}
737
738sub DESTROY {
739 $_[0][1]->stop;
740}
741
742sub condvar {
743 bless \my $flag, urxvt::anyevent::condvar::
744}
745
746sub urxvt::anyevent::condvar::broadcast {
747 ${$_[0]}++;
748}
749
750sub urxvt::anyevent::condvar::wait {
751 unless (${$_[0]}) {
752 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
753 }
754}
755
756package urxvt::term;
757
559=head2 The C<urxvt::term> Class 758=head2 The C<urxvt::term> Class
560 759
561=over 4 760=over 4
562 761
762=cut
763
764# find on_xxx subs in the package and register them
765# as hooks
766sub register_package {
767 my ($self, $pkg, $argv) = @_;
768
769 my $proxy = bless {
770 _pkg => $pkg,
771 argv => $argv,
772 }, $pkg;
773 Scalar::Util::weaken ($proxy->{term} = $self);
774
775 $self->{_pkg}{$pkg} = $proxy;
776
777 for my $name (@HOOKNAME) {
778 if (my $ref = $pkg->can ("on_" . lc $name)) {
779 $proxy->enable ($name => $ref);
780 }
781 }
782}
783
784=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
785
786Creates a new terminal, very similar as if you had started it with system
787C<$rxvtname, arg...>. C<$envhashref> must be a reference to a %ENV>-like
788C<hash which defines the environment of the new terminal.
789
790Croaks (and probably outputs an error message) if the new instance
791couldn't be created. Returns C<undef> if the new instance didn't
792initialise perl, and the terminal object otherwise. The C<init> and
793C<start> hooks will be called during this call.
794
795=cut
796
797sub new {
798 my ($class, $env, @args) = @_;
799
800 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
801}
802
563=item $term->destroy 803=item $term->destroy
564 804
565Destroy the terminal object (close the window, free resources etc.). 805Destroy the terminal object (close the window, free resources
806etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
807watchers (timers, io watchers) are still active.
808
809=item $isset = $term->option ($optval[, $set])
810
811Returns true if the option specified by C<$optval> is enabled, and
812optionally change it. All option values are stored by name in the hash
813C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
814
815Here is a a likely non-exhaustive list of option names, please see the
816source file F</src/optinc.h> to see the actual list:
817
818 borderLess console cursorBlink cursorUnderline hold iconic insecure
819 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
820 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
821 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
822 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
823 tripleclickwords utmpInhibit visualBell
566 824
567=item $value = $term->resource ($name[, $newval]) 825=item $value = $term->resource ($name[, $newval])
568 826
569Returns the current resource value associated with a given name and 827Returns the current resource value associated with a given name and
570optionally sets a new value. Setting values is most useful in the C<init> 828optionally sets a new value. Setting values is most useful in the C<init>
580 838
581Please note that resource strings will currently only be freed when the 839Please note that resource strings will currently only be freed when the
582terminal is destroyed, so changing options frequently will eat memory. 840terminal is destroyed, so changing options frequently will eat memory.
583 841
584Here is a a likely non-exhaustive list of resource names, not all of which 842Here is a a likely non-exhaustive list of resource names, not all of which
585are supported in every build, please see the source to see the actual 843are supported in every build, please see the source file F</src/rsinc.h>
586list: 844to see the actual list:
587 845
588 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 846 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
589 borderLess color cursorBlink cursorUnderline cutchars delete_key 847 borderLess color cursorBlink cursorUnderline cutchars delete_key
590 display_name embed ext_bwidth fade font geometry hold iconName 848 display_name embed ext_bwidth fade font geometry hold iconName
591 imFont imLocale inputMethod insecure int_bwidth intensityStyles 849 imFont imLocale inputMethod insecure int_bwidth intensityStyles
598 shade term_name title transparent transparent_all tripleclickwords 856 shade term_name title transparent transparent_all tripleclickwords
599 utmpInhibit visualBell 857 utmpInhibit visualBell
600 858
601=cut 859=cut
602 860
603sub urxvt::term::resource($$;$) { 861sub resource($$;$) {
604 my ($self, $name) = (shift, shift); 862 my ($self, $name) = (shift, shift);
605 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 863 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
606 &urxvt::term::_resource 864 &urxvt::term::_resource
607} 865}
608 866
867=item $success = $term->parse_keysym ($keysym_spec, $command_string)
868
869Adds a keymap translation exactly as specified via a resource. See the
870C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
871
609=item $rend = $term->rstyle ([$new_rstyle]) 872=item $rend = $term->rstyle ([$new_rstyle])
610 873
611Return and optionally change the current rendition. Text that is output by 874Return and optionally change the current rendition. Text that is output by
612the terminal application will use this style. 875the terminal application will use this style.
613 876
632 895
633=item $oldtext = $term->selection ([$newtext]) 896=item $oldtext = $term->selection ([$newtext])
634 897
635Return the current selection text and optionally replace it by C<$newtext>. 898Return the current selection text and optionally replace it by C<$newtext>.
636 899
637#=item $term->overlay ($x, $y, $text) 900=item $term->overlay_simple ($x, $y, $text)
638# 901
639#Create a simple multi-line overlay box. See the next method for details. 902Create a simple multi-line overlay box. See the next method for details.
640# 903
641#=cut 904=cut
642# 905
643#sub urxvt::term::scr_overlay { 906sub overlay_simple {
644# my ($self, $x, $y, $text) = @_; 907 my ($self, $x, $y, $text) = @_;
645# 908
646# my @lines = split /\n/, $text; 909 my @lines = split /\n/, $text;
647# 910
648# my $w = 0; 911 my $w = List::Util::max map $self->strwidth ($_), @lines;
649# for (map $self->strwidth ($_), @lines) { 912
650# $w = $_ if $w < $_;
651# }
652#
653# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 913 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
654# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 914 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
655#} 915
916 $overlay
917}
656 918
657=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 919=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
658 920
659Create a new (empty) overlay at the given position with the given 921Create a new (empty) overlay at the given position with the given
660width/height. C<$rstyle> defines the initial rendition style 922width/height. C<$rstyle> defines the initial rendition style
695C<$event> I<must> be the event causing the menu to pop up (a button event, 957C<$event> I<must> be the event causing the menu to pop up (a button event,
696currently). 958currently).
697 959
698=cut 960=cut
699 961
700sub urxvt::term::popup { 962sub popup {
701 my ($self, $event) = @_; 963 my ($self, $event) = @_;
702 964
703 $self->grab ($event->{time}, 1) 965 $self->grab ($event->{time}, 1)
704 or return; 966 or return;
705 967
727 989
728=item $string = $term->locale_decode ($octets) 990=item $string = $term->locale_decode ($octets)
729 991
730Convert the given locale-encoded octets into a perl string. 992Convert the given locale-encoded octets into a perl string.
731 993
994=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
995
996XORs the rendition values in the given span with the provided value
997(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
998to the selection.
999
1000=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1001
1002Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1003whitespace will additionally be xored with the C<$rstyle2>, which defaults
1004to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1005it instead.
1006
1007=item $term->scr_bell
1008
1009Ring the bell!
1010
732=item $term->scr_add_lines ($string) 1011=item $term->scr_add_lines ($string)
733 1012
734Write the given text string to the screen, as if output by the application 1013Write the given text string to the screen, as if output by the application
735running inside the terminal. It may not contain command sequences (escape 1014running inside the terminal. It may not contain command sequences (escape
736codes), but is free to use line feeds, carriage returns and tabs. The 1015codes), but is free to use line feeds, carriage returns and tabs. The
750 1029
751Write the octets given in C<$data> to the tty (i.e. as program input). To 1030Write the octets given in C<$data> to the tty (i.e. as program input). To
752pass characters instead of octets, you should convert your strings first 1031pass characters instead of octets, you should convert your strings first
753to the locale-specific encoding using C<< $term->locale_encode >>. 1032to the locale-specific encoding using C<< $term->locale_encode >>.
754 1033
1034=item $old_events = $term->pty_ev_events ([$new_events])
1035
1036Replaces the event mask of the pty watcher by the given event mask. Can
1037be used to suppress input and output handling to the pty/tty. See the
1038description of C<< urxvt::timer->events >>. Make sure to always restore
1039the previous value.
1040
755=item $windowid = $term->parent 1041=item $windowid = $term->parent
756 1042
757Return the window id of the toplevel window. 1043Return the window id of the toplevel window.
758 1044
759=item $windowid = $term->vt 1045=item $windowid = $term->vt
783=item $nrow_plus_saveLines = $term->total_rows 1069=item $nrow_plus_saveLines = $term->total_rows
784 1070
785=item $lines_in_scrollback = $term->nsaved 1071=item $lines_in_scrollback = $term->nsaved
786 1072
787Return various integers describing terminal characteristics. 1073Return various integers describing terminal characteristics.
1074
1075=item $x_display = $term->display_id
1076
1077Return the DISPLAY used by rxvt-unicode.
1078
1079=item $lc_ctype = $term->locale
1080
1081Returns the LC_CTYPE category string used by this rxvt-unicode.
1082
1083=item $env = $term->env
1084
1085Returns a copy of the environment in effect for the terminal as a hashref
1086similar to C<\%ENV>.
1087
1088=cut
1089
1090sub env {
1091 if (my $env = $_[0]->_env) {
1092 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1093 } else {
1094 +{ %ENV }
1095 }
1096}
788 1097
789=item $modifiermask = $term->ModLevel3Mask 1098=item $modifiermask = $term->ModLevel3Mask
790 1099
791=item $modifiermask = $term->ModMetaMask 1100=item $modifiermask = $term->ModMetaMask
792 1101
895 1204
896=back 1205=back
897 1206
898=cut 1207=cut
899 1208
900sub urxvt::term::line { 1209sub line {
901 my ($self, $row) = @_; 1210 my ($self, $row) = @_;
902 1211
903 my $maxrow = $self->nrow - 1; 1212 my $maxrow = $self->nrow - 1;
904 1213
905 my ($beg, $end) = ($row, $row); 1214 my ($beg, $end) = ($row, $row);
969 $offset / $self->{ncol} + $self->{beg}, 1278 $offset / $self->{ncol} + $self->{beg},
970 $offset % $self->{ncol} 1279 $offset % $self->{ncol}
971 ) 1280 )
972} 1281}
973 1282
974=item ($row, $col) = $line->coord_of ($offset)
975=item $text = $term->special_encode $string 1283=item $text = $term->special_encode $string
976 1284
977Converts a perl string into the special encoding used by rxvt-unicode, 1285Converts a perl string into the special encoding used by rxvt-unicode,
978where one character corresponds to one screen cell. See 1286where one character corresponds to one screen cell. See
979C<< $term->ROW_t >> for details. 1287C<< $term->ROW_t >> for details.
981=item $string = $term->special_decode $text 1289=item $string = $term->special_decode $text
982 1290
983Converts rxvt-unicodes text reprsentation into a perl string. See 1291Converts rxvt-unicodes text reprsentation into a perl string. See
984C<< $term->ROW_t >> for details. 1292C<< $term->ROW_t >> for details.
985 1293
1294=item $success = $term->grab_button ($button, $modifiermask)
1295
1296Registers a synchronous button grab. See the XGrabButton manpage.
1297
1298=item $success = $term->grab ($eventtime[, $sync])
1299
1300Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1301synchronous (C<$sync> is true). Also remembers the grab timestampe.
1302
1303=item $term->allow_events_async
1304
1305Calls XAllowEvents with AsyncBoth for the most recent grab.
1306
1307=item $term->allow_events_sync
1308
1309Calls XAllowEvents with SyncBoth for the most recent grab.
1310
1311=item $term->allow_events_replay
1312
1313Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1314recent grab.
1315
1316=item $term->ungrab
1317
1318Calls XUngrab for the most recent grab. Is called automatically on
1319evaluation errors, as it is better to lose the grab in the error case as
1320the session.
1321
986=back 1322=back
987 1323
1324=cut
1325
1326package urxvt::popup;
1327
988=head2 The C<urxvt::popup> Class 1328=head2 The C<urxvt::popup> Class
989 1329
990=over 4 1330=over 4
991 1331
992=cut 1332=cut
993
994package urxvt::popup;
995 1333
996sub add_item { 1334sub add_item {
997 my ($self, $item) = @_; 1335 my ($self, $item) = @_;
998 1336
1337 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1338 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1339 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1340
1341 $item->{render} ||= sub { $_[0]{text} };
1342
999 push @{ $self->{item} }, $item; 1343 push @{ $self->{item} }, $item;
1000} 1344}
1345
1346=item $popup->add_title ($title)
1347
1348Adds a non-clickable title to the popup.
1349
1350=cut
1351
1352sub add_title {
1353 my ($self, $title) = @_;
1354
1355 $self->add_item ({
1356 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1357 text => $title,
1358 activate => sub { },
1359 });
1360}
1361
1362=item $popup->add_separator ([$sepchr])
1363
1364Creates a separator, optionally using the character given as C<$sepchr>.
1365
1366=cut
1367
1368sub add_separator {
1369 my ($self, $sep) = @_;
1370
1371 $sep ||= "=";
1372
1373 $self->add_item ({
1374 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1375 text => "",
1376 render => sub { $sep x $self->{term}->ncol },
1377 activate => sub { },
1378 });
1379}
1380
1381=item $popup->add_button ($text, $cb)
1382
1383Adds a clickable button to the popup. C<$cb> is called whenever it is
1384selected.
1385
1386=cut
1001 1387
1002sub add_button { 1388sub add_button {
1003 my ($self, $text, $cb) = @_; 1389 my ($self, $text, $cb) = @_;
1004 1390
1005 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb }); 1391 $self->add_item ({ type => "button", text => $text, activate => $cb});
1006} 1392}
1393
1394=item $popup->add_toggle ($text, $cb, $initial_value)
1395
1396Adds a toggle/checkbox item to the popup. Teh callback gets called
1397whenever it gets toggled, with a boolean indicating its value as its first
1398argument.
1399
1400=cut
1401
1402sub add_toggle {
1403 my ($self, $text, $cb, $value) = @_;
1404
1405 my $item; $item = {
1406 type => "button",
1407 text => " $text",
1408 value => $value,
1409 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1410 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1411 };
1412
1413 $self->add_item ($item);
1414}
1415
1416=item $popup->show
1417
1418Displays the popup (which is initially hidden).
1419
1420=cut
1007 1421
1008sub show { 1422sub show {
1009 my ($self) = @_; 1423 my ($self) = @_;
1010 1424
1011 local $urxvt::popup::self = $self; 1425 local $urxvt::popup::self = $self;
1012 1426
1427 my $env = $self->{term}->env;
1428 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1429 delete $env->{LC_ALL};
1430 $env->{LC_CTYPE} = $self->{term}->locale;
1431
1432 urxvt::term->new ($env, $self->{term}->resource ("name"),
1013 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1433 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1014 "--transient-for" => $self->{term}->parent, 1434 "--transient-for" => $self->{term}->parent,
1435 "-display" => $self->{term}->display_id,
1015 "-pe" => "urxvt-popup") 1436 "-pe" => "urxvt-popup")
1016 or die "unable to create popup window\n"; 1437 or die "unable to create popup window\n";
1017} 1438}
1018 1439
1019sub DESTROY { 1440sub DESTROY {
1020 my ($self) = @_; 1441 my ($self) = @_;
1021 1442
1443 delete $self->{term}{_destroy}{$self};
1022 $self->{term}->ungrab; 1444 $self->{term}->ungrab;
1023} 1445}
1024 1446
1025=head2 The C<urxvt::timer> Class 1447=head2 The C<urxvt::timer> Class
1026 1448
1081 1503
1082 $term->{socket} = ... 1504 $term->{socket} = ...
1083 $term->{iow} = urxvt::iow 1505 $term->{iow} = urxvt::iow
1084 ->new 1506 ->new
1085 ->fd (fileno $term->{socket}) 1507 ->fd (fileno $term->{socket})
1086 ->events (1) # wait for read data 1508 ->events (urxvt::EVENT_READ)
1087 ->start 1509 ->start
1088 ->cb (sub { 1510 ->cb (sub {
1089 my ($iow, $revents) = @_; 1511 my ($iow, $revents) = @_;
1090 # $revents must be 1 here, no need to check 1512 # $revents must be 1 here, no need to check
1091 sysread $term->{socket}, my $buf, 8192 1513 sysread $term->{socket}, my $buf, 8192
1108 1530
1109Set the filedescriptor (not handle) to watch. 1531Set the filedescriptor (not handle) to watch.
1110 1532
1111=item $iow = $iow->events ($eventmask) 1533=item $iow = $iow->events ($eventmask)
1112 1534
1113Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1535Set the event mask to watch. The only allowed values are
1114data, Bit #1 (value C<2>) enables watching for write data. 1536C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1537together, or C<urxvt::EVENT_NONE>.
1115 1538
1116=item $iow = $iow->start 1539=item $iow = $iow->start
1117 1540
1118Start watching for requested events on the given handle. 1541Start watching for requested events on the given handle.
1119 1542
1130This variable controls the verbosity level of the perl extension. Higher 1553This variable controls the verbosity level of the perl extension. Higher
1131numbers indicate more verbose output. 1554numbers indicate more verbose output.
1132 1555
1133=over 4 1556=over 4
1134 1557
1135=item =0 - only fatal messages 1558=item == 0 - fatal messages
1136 1559
1137=item =3 - script loading and management 1560=item >= 3 - script loading and management
1138 1561
1139=item =10 - all events received 1562=item >=10 - all events received
1140 1563
1141=back 1564=back
1142 1565
1143=head1 AUTHOR 1566=head1 AUTHOR
1144 1567

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines