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.46 by root, Sat Jan 7 20:29:28 2006 UTC vs.
Revision 1.78 by root, Wed Jan 11 01:01:52 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
99=over 4 123=over 4
100 124
101=item $text 125=item $text
102 126
103Rxvt-unicodes special way of encoding text, where one "unicode" character 127Rxvt-unicodes special way of encoding text, where one "unicode" character
104always represents one screen cell. See L<row_t> for a discussion of this format. 128always represents one screen cell. See L<ROW_t> for a discussion of this format.
105 129
106=item $string 130=item $string
107 131
108A perl text string, with an emphasis on I<text>. It can store all unicode 132A perl text string, with an emphasis on I<text>. It can store all unicode
109characters and is to be distinguished with text encoded in a specific 133characters and is to be distinguished with text encoded in a specific
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.
303=back 391=back
304 392
305=head2 Functions in the C<urxvt> Package 393=head2 Functions in the C<urxvt> Package
306 394
307=over 4 395=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 396
317=item urxvt::fatal $errormessage 397=item urxvt::fatal $errormessage
318 398
319Fatally aborts execution with the given error message. Avoid at all 399Fatally aborts execution with the given error message. Avoid at all
320costs! The only time this is acceptable is when the terminal process 400costs! The only time this is acceptable is when the terminal process
327that calls this function. 407that calls this function.
328 408
329Using this function has the advantage that its output ends up in the 409Using this function has the advantage that its output ends up in the
330correct place, e.g. on stderr of the connecting urxvtc client. 410correct place, e.g. on stderr of the connecting urxvtc client.
331 411
412Messages have a size limit of 1023 bytes currently.
413
414=item $is_safe = urxvt::safe
415
416Returns true when it is safe to do potentially unsafe things, such as
417evaluating perl code specified by the user. This is true when urxvt was
418started setuid or setgid.
419
332=item $time = urxvt::NOW 420=item $time = urxvt::NOW
333 421
334Returns the "current time" (as per the event loop). 422Returns the "current time" (as per the event loop).
423
424=item urxvt::CurrentTime
425
426=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
427Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
428Button4Mask, Button5Mask, AnyModifier
429
430Various constants for use in X calls and event processing.
335 431
336=back 432=back
337 433
338=head2 RENDITION 434=head2 RENDITION
339 435
366 462
367=item $background = urxvt::GET_BASEBG $rend 463=item $background = urxvt::GET_BASEBG $rend
368 464
369Return the foreground/background colour index, respectively. 465Return the foreground/background colour index, respectively.
370 466
371=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 467=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
372 468
373=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 469=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
374 470
375Replace the foreground/background colour in the rendition mask with the 471Replace the foreground/background colour in the rendition mask with the
376specified one. 472specified one.
377 473
378=item $value = urxvt::GET_CUSTOM ($rend) 474=item $value = urxvt::GET_CUSTOM $rend
379 475
380Return the "custom" value: Every rendition has 5 bits for use by 476Return the "custom" value: Every rendition has 5 bits for use by
381extensions. They can be set and changed as you like and are initially 477extensions. They can be set and changed as you like and are initially
382zero. 478zero.
383 479
384=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 480=item $rend = urxvt::SET_CUSTOM $rend, $new_value
385 481
386Change the custom value. 482Change the custom value.
387 483
388=back 484=back
389 485
390=cut 486=cut
391
392package urxvt;
393
394use strict;
395use Scalar::Util ();
396
397our $TERM;
398our @HOOKNAME;
399our $LIBDIR;
400 487
401BEGIN { 488BEGIN {
402 urxvt->bootstrap; 489 urxvt->bootstrap;
403 490
404 # overwrite perl's warn 491 # overwrite perl's warn
406 my $msg = join "", @_; 493 my $msg = join "", @_;
407 $msg .= "\n" 494 $msg .= "\n"
408 unless $msg =~ /\n$/; 495 unless $msg =~ /\n$/;
409 urxvt::warn ($msg); 496 urxvt::warn ($msg);
410 }; 497 };
498
499 delete $ENV{IFS};
500 delete $ENV{CDPATH};
501 delete $ENV{BASH_ENV};
502 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
411} 503}
412 504
413my @hook_count; 505my @hook_count;
414my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 506my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
415 507
416sub verbose { 508sub verbose {
417 my ($level, $msg) = @_; 509 my ($level, $msg) = @_;
418 warn "$msg\n" if $level <= $verbosity; 510 warn "$msg\n" if $level <= $verbosity;
419} 511}
420 512
421# find on_xxx subs in the package and register them
422# as hooks
423sub register_package($) {
424 my ($pkg) = @_;
425
426 for my $htype (0.. $#HOOKNAME) {
427 my $name = $HOOKNAME[$htype];
428
429 my $ref = $pkg->can ("on_" . lc $name)
430 or next;
431
432 $TERM->{_hook}[$htype]{$pkg} = $ref;
433 $hook_count[$htype]++
434 or set_should_invoke $htype, 1;
435 }
436}
437
438my $extension_pkg = "extension0000"; 513my $extension_pkg = "extension0000";
439my %extension_pkg; 514my %extension_pkg;
440 515
441# load a single script into its own package, once only 516# load a single script into its own package, once only
442sub extension_package($) { 517sub extension_package($) {
448 verbose 3, "loading extension '$path' into package '$pkg'"; 523 verbose 3, "loading extension '$path' into package '$pkg'";
449 524
450 open my $fh, "<:raw", $path 525 open my $fh, "<:raw", $path
451 or die "$path: $!"; 526 or die "$path: $!";
452 527
528 my $source = untaint
453 my $source = "package $pkg; use strict; use utf8;\n" 529 "package $pkg; use strict; use utf8;\n"
454 . "use base urxvt::term::proxy::;\n" 530 . "use base urxvt::term::extension::;\n"
455 . "#line 1 \"$path\"\n{\n" 531 . "#line 1 \"$path\"\n{\n"
456 . (do { local $/; <$fh> }) 532 . (do { local $/; <$fh> })
457 . "\n};\n1"; 533 . "\n};\n1";
458 534
535 eval $source
459 eval $source or die "$path: $@"; 536 or die "$path: $@";
460 537
461 $pkg 538 $pkg
462 } 539 }
463} 540}
464 541
469 local $TERM = shift; 546 local $TERM = shift;
470 my $htype = shift; 547 my $htype = shift;
471 548
472 if ($htype == 0) { # INIT 549 if ($htype == 0) { # INIT
473 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 550 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
551
552 my %ext_arg;
474 553
475 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 554 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
555 if ($_ eq "default") {
556 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
557 } elsif (/^-(.*)$/) {
558 delete $ext_arg{$1};
559 } elsif (/^([^<]+)<(.*)>$/) {
560 push @{ $ext_arg{$1} }, $2;
561 } else {
562 $ext_arg{$_} ||= [];
563 }
564 }
565
566 while (my ($ext, $argv) = each %ext_arg) {
476 my @files = grep -f $_, map "$_/$ext", @dirs; 567 my @files = grep -f $_, map "$_/$ext", @dirs;
477 568
478 if (@files) { 569 if (@files) {
479 register_package extension_package $files[0]; 570 $TERM->register_package (extension_package $files[0], $argv);
480 } else { 571 } else {
481 warn "perl extension '$ext' not found in perl library search path\n"; 572 warn "perl extension '$ext' not found in perl library search path\n";
482 } 573 }
483 } 574 }
575
576 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
577 warn $@ if $@;
484 } 578 }
485 579
486 $retval = undef; 580 $retval = undef;
487 581
488 if (my $cb = $TERM->{_hook}[$htype]) { 582 if (my $cb = $TERM->{_hook}[$htype]) {
490 if $verbosity >= 10; 584 if $verbosity >= 10;
491 585
492 keys %$cb; 586 keys %$cb;
493 587
494 while (my ($pkg, $cb) = each %$cb) { 588 while (my ($pkg, $cb) = each %$cb) {
495 eval { 589 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
496 $retval = $cb->(
497 $TERM->{_pkg}{$pkg} ||= do {
498 my $proxy = bless { }, $pkg;
499 Scalar::Util::weaken ($proxy->{term} = $TERM);
500 $proxy
501 },
502 @_,
503 ) and last; 590 and last;
591
592 if ($@) {
593 $TERM->ungrab; # better to lose the grab than the session
594 warn $@;
504 }; 595 }
505 warn $@ if $@;#d#
506 } 596 }
507 } 597 }
508 598
509 if ($htype == 1) { # DESTROY 599 if ($htype == 1) { # DESTROY
510 # remove hooks if unused
511 if (my $hook = $TERM->{_hook}) { 600 if (my $hook = delete $TERM->{_hook}) {
512 for my $htype (0..$#$hook) { 601 for my $htype (0..$#$hook) {
513 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 602 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
514 or set_should_invoke $htype, 0; 603 or set_should_invoke $htype, 0;
515 } 604 }
516 } 605 }
523 } 612 }
524 613
525 $retval 614 $retval
526} 615}
527 616
528sub urxvt::term::proxy::AUTOLOAD { 617# urxvt::term::extension
529 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 618
619package urxvt::term::extension;
620
621sub enable {
622 my ($self, %hook) = @_;
623 my $pkg = $self->{_pkg};
624
625 while (my ($name, $cb) = each %hook) {
626 my $htype = $HOOKTYPE{uc $name};
627 defined $htype
628 or Carp::croak "unsupported hook type '$name'";
629
630 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
631 $hook_count[$htype]++
632 or urxvt::set_should_invoke $htype, 1;
633 }
634
635 $self->{term}{_hook}[$htype]{$pkg} = $cb;
636 }
637}
638
639sub disable {
640 my ($self, @hook) = @_;
641 my $pkg = $self->{_pkg};
642
643 for my $name (@hook) {
644 my $htype = $HOOKTYPE{uc $name};
645 defined $htype
646 or Carp::croak "unsupported hook type '$name'";
647
648 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
649 --$hook_count[$htype]
650 or urxvt::set_should_invoke $htype, 0;
651 }
652 }
653}
654
655our $AUTOLOAD;
656
657sub AUTOLOAD {
658 $AUTOLOAD =~ /:([^:]+)$/
530 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 659 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
531 660
532 eval qq{ 661 eval qq{
533 sub $urxvt::term::proxy::AUTOLOAD { 662 sub $AUTOLOAD {
534 my \$proxy = shift; 663 my \$proxy = shift;
535 \$proxy->{term}->$1 (\@_) 664 \$proxy->{term}->$1 (\@_)
536 } 665 }
537 1 666 1
538 } or die "FATAL: unable to compile method forwarder: $@"; 667 } or die "FATAL: unable to compile method forwarder: $@";
539 668
540 goto &$urxvt::term::proxy::AUTOLOAD; 669 goto &$AUTOLOAD;
541} 670}
671
672sub DESTROY {
673 # nop
674}
675
676# urxvt::destroy_hook
542 677
543sub urxvt::destroy_hook::DESTROY { 678sub urxvt::destroy_hook::DESTROY {
544 ${$_[0]}->(); 679 ${$_[0]}->();
545} 680}
546 681
547sub urxvt::destroy_hook(&) { 682sub urxvt::destroy_hook(&) {
548 bless \shift, urxvt::destroy_hook:: 683 bless \shift, urxvt::destroy_hook::
549} 684}
550 685
686package urxvt::anyevent;
687
688=head2 The C<urxvt::anyevent> Class
689
690The sole purpose of this class is to deliver an interface to the
691C<AnyEvent> module - any module using it will work inside urxvt without
692further programming. The only exception is that you cannot wait on
693condition variables, but non-blocking condvar use is ok. What this means
694is that you cannot use blocking APIs, but the non-blocking variant should
695work.
696
697=cut
698
699our $VERSION = 1;
700
701$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
702push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
703
704sub timer {
705 my ($class, %arg) = @_;
706
707 my $cb = $arg{cb};
708
709 urxvt::timer
710 ->new
711 ->start (urxvt::NOW + $arg{after})
712 ->cb (sub {
713 $_[0]->stop; # need to cancel manually
714 $cb->();
715 })
716}
717
718sub io {
719 my ($class, %arg) = @_;
720
721 my $cb = $arg{cb};
722
723 bless [$arg{fh}, urxvt::iow
724 ->new
725 ->fd (fileno $arg{fh})
726 ->events (($arg{poll} =~ /r/ ? 1 : 0)
727 | ($arg{poll} =~ /w/ ? 2 : 0))
728 ->start
729 ->cb (sub {
730 $cb->(($_[1] & 1 ? 'r' : '')
731 . ($_[1] & 2 ? 'w' : ''));
732 })],
733 urxvt::anyevent::
734}
735
736sub DESTROY {
737 $_[0][1]->stop;
738}
739
740sub condvar {
741 bless \my $flag, urxvt::anyevent::condvar::
742}
743
744sub urxvt::anyevent::condvar::broadcast {
745 ${$_[0]}++;
746}
747
748sub urxvt::anyevent::condvar::wait {
749 unless (${$_[0]}) {
750 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
751 }
752}
753
754package urxvt::term;
755
551=head2 The C<urxvt::term> Class 756=head2 The C<urxvt::term> Class
552 757
553=over 4 758=over 4
554 759
760=cut
761
762# find on_xxx subs in the package and register them
763# as hooks
764sub register_package {
765 my ($self, $pkg, $argv) = @_;
766
767 my $proxy = bless {
768 _pkg => $pkg,
769 argv => $argv,
770 }, $pkg;
771 Scalar::Util::weaken ($proxy->{term} = $self);
772
773 $self->{_pkg}{$pkg} = $proxy;
774
775 for my $name (@HOOKNAME) {
776 if (my $ref = $pkg->can ("on_" . lc $name)) {
777 $proxy->enable ($name => $ref);
778 }
779 }
780}
781
782=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
783
784Creates a new terminal, very similar as if you had started it with system
785C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
786hash which defines the environment of the new terminal.
787
788Croaks (and probably outputs an error message) if the new instance
789couldn't be created. Returns C<undef> if the new instance didn't
790initialise perl, and the terminal object otherwise. The C<init> and
791C<start> hooks will be called during this call.
792
793=cut
794
795sub new {
796 my ($class, $env, @args) = @_;
797
798 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
799}
800
555=item $term->destroy 801=item $term->destroy
556 802
557Destroy the terminal object (close the window, free resources etc.). 803Destroy the terminal object (close the window, free resources
804etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
805watchers (timers, io watchers) are still active.
806
807=item $isset = $term->option ($optval[, $set])
808
809Returns true if the option specified by C<$optval> is enabled, and
810optionally change it. All option values are stored by name in the hash
811C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
812
813Here is a a likely non-exhaustive list of option names, please see the
814source file F</src/optinc.h> to see the actual list:
815
816 borderLess console cursorBlink cursorUnderline hold iconic insecure
817 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
818 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
819 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
820 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
821 tripleclickwords utmpInhibit visualBell
558 822
559=item $value = $term->resource ($name[, $newval]) 823=item $value = $term->resource ($name[, $newval])
560 824
561Returns the current resource value associated with a given name and 825Returns the current resource value associated with a given name and
562optionally sets a new value. Setting values is most useful in the C<init> 826optionally sets a new value. Setting values is most useful in the C<init>
572 836
573Please note that resource strings will currently only be freed when the 837Please note that resource strings will currently only be freed when the
574terminal is destroyed, so changing options frequently will eat memory. 838terminal is destroyed, so changing options frequently will eat memory.
575 839
576Here is a a likely non-exhaustive list of resource names, not all of which 840Here is a a likely non-exhaustive list of resource names, not all of which
577are supported in every build, please see the source to see the actual 841are supported in every build, please see the source file F</src/rsinc.h>
578list: 842to see the actual list:
579 843
580 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 844 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
581 borderLess color cursorBlink cursorUnderline cutchars delete_key 845 borderLess color cursorBlink cursorUnderline cutchars delete_key
582 display_name embed ext_bwidth fade font geometry hold iconName 846 display_name embed ext_bwidth fade font geometry hold iconName
583 imFont imLocale inputMethod insecure int_bwidth intensityStyles 847 imFont imLocale inputMethod insecure int_bwidth intensityStyles
590 shade term_name title transparent transparent_all tripleclickwords 854 shade term_name title transparent transparent_all tripleclickwords
591 utmpInhibit visualBell 855 utmpInhibit visualBell
592 856
593=cut 857=cut
594 858
595sub urxvt::term::resource($$;$) { 859sub resource($$;$) {
596 my ($self, $name) = (shift, shift); 860 my ($self, $name) = (shift, shift);
597 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 861 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
598 &urxvt::term::_resource 862 &urxvt::term::_resource
599} 863}
600 864
865=item $success = $term->parse_keysym ($keysym_spec, $command_string)
866
867Adds a keymap translation exactly as specified via a resource. See the
868C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
869
601=item $rend = $term->rstyle ([$new_rstyle]) 870=item $rend = $term->rstyle ([$new_rstyle])
602 871
603Return and optionally change the current rendition. Text that is output by 872Return and optionally change the current rendition. Text that is output by
604the terminal application will use this style. 873the terminal application will use this style.
605 874
624 893
625=item $oldtext = $term->selection ([$newtext]) 894=item $oldtext = $term->selection ([$newtext])
626 895
627Return the current selection text and optionally replace it by C<$newtext>. 896Return the current selection text and optionally replace it by C<$newtext>.
628 897
629#=item $term->overlay ($x, $y, $text) 898=item $term->overlay_simple ($x, $y, $text)
630# 899
631#Create a simple multi-line overlay box. See the next method for details. 900Create a simple multi-line overlay box. See the next method for details.
632# 901
633#=cut 902=cut
634# 903
635#sub urxvt::term::scr_overlay { 904sub overlay_simple {
636# my ($self, $x, $y, $text) = @_; 905 my ($self, $x, $y, $text) = @_;
637# 906
638# my @lines = split /\n/, $text; 907 my @lines = split /\n/, $text;
639# 908
640# my $w = 0; 909 my $w = List::Util::max map $self->strwidth ($_), @lines;
641# for (map $self->strwidth ($_), @lines) { 910
642# $w = $_ if $w < $_;
643# }
644#
645# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 911 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
646# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 912 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
647#} 913
914 $overlay
915}
648 916
649=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 917=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
650 918
651Create a new (empty) overlay at the given position with the given 919Create a new (empty) overlay at the given position with the given
652width/height. C<$rstyle> defines the initial rendition style 920width/height. C<$rstyle> defines the initial rendition style
687C<$event> I<must> be the event causing the menu to pop up (a button event, 955C<$event> I<must> be the event causing the menu to pop up (a button event,
688currently). 956currently).
689 957
690=cut 958=cut
691 959
692sub urxvt::term::popup { 960sub popup {
693 my ($self, $event) = @_; 961 my ($self, $event) = @_;
694 962
695 $self->grab ($event->{time}, 1) 963 $self->grab ($event->{time}, 1)
696 or return; 964 or return;
697 965
719 987
720=item $string = $term->locale_decode ($octets) 988=item $string = $term->locale_decode ($octets)
721 989
722Convert the given locale-encoded octets into a perl string. 990Convert the given locale-encoded octets into a perl string.
723 991
992=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
993
994XORs the rendition values in the given span with the provided value
995(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
996to the selection.
997
998=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
999
1000Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1001whitespace will additionally be xored with the C<$rstyle2>, which defaults
1002to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1003it instead.
1004
1005=item $term->scr_bell
1006
1007Ring the bell!
1008
724=item $term->scr_add_lines ($string) 1009=item $term->scr_add_lines ($string)
725 1010
726Write the given text string to the screen, as if output by the application 1011Write the given text string to the screen, as if output by the application
727running inside the terminal. It may not contain command sequences (escape 1012running inside the terminal. It may not contain command sequences (escape
728codes), but is free to use line feeds, carriage returns and tabs. The 1013codes), but is free to use line feeds, carriage returns and tabs. The
742 1027
743Write the octets given in C<$data> to the tty (i.e. as program input). To 1028Write the octets given in C<$data> to the tty (i.e. as program input). To
744pass characters instead of octets, you should convert your strings first 1029pass characters instead of octets, you should convert your strings first
745to the locale-specific encoding using C<< $term->locale_encode >>. 1030to the locale-specific encoding using C<< $term->locale_encode >>.
746 1031
1032=item $old_events = $term->pty_ev_events ([$new_events])
1033
1034Replaces the event mask of the pty watcher by the given event mask. Can
1035be used to suppress input and output handling to the pty/tty. See the
1036description of C<< urxvt::timer->events >>. Make sure to always restore
1037the previous value.
1038
747=item $windowid = $term->parent 1039=item $windowid = $term->parent
748 1040
749Return the window id of the toplevel window. 1041Return the window id of the toplevel window.
750 1042
751=item $windowid = $term->vt 1043=item $windowid = $term->vt
775=item $nrow_plus_saveLines = $term->total_rows 1067=item $nrow_plus_saveLines = $term->total_rows
776 1068
777=item $lines_in_scrollback = $term->nsaved 1069=item $lines_in_scrollback = $term->nsaved
778 1070
779Return various integers describing terminal characteristics. 1071Return various integers describing terminal characteristics.
1072
1073=item $x_display = $term->display_id
1074
1075Return the DISPLAY used by rxvt-unicode.
1076
1077=item $lc_ctype = $term->locale
1078
1079Returns the LC_CTYPE category string used by this rxvt-unicode.
1080
1081=item $env = $term->env
1082
1083Returns a copy of the environment in effect for the terminal as a hashref
1084similar to C<\%ENV>.
1085
1086=cut
1087
1088sub env {
1089 if (my $env = $_[0]->_env) {
1090 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1091 } else {
1092 +{ %ENV }
1093 }
1094}
1095
1096=item $modifiermask = $term->ModLevel3Mask
1097
1098=item $modifiermask = $term->ModMetaMask
1099
1100=item $modifiermask = $term->ModNumLockMask
1101
1102Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1103AltGr), the meta key (often Alt) and the num lock key, if applicable.
780 1104
781=item $view_start = $term->view_start ([$newvalue]) 1105=item $view_start = $term->view_start ([$newvalue])
782 1106
783Returns the negative row number of the topmost line. Minimum value is 1107Returns the negative row number of the topmost line. Minimum value is
784C<0>, which displays the normal terminal contents. Larger values scroll 1108C<0>, which displays the normal terminal contents. Larger values scroll
878 1202
879=back 1203=back
880 1204
881=cut 1205=cut
882 1206
883sub urxvt::term::line { 1207sub line {
884 my ($self, $row) = @_; 1208 my ($self, $row) = @_;
885 1209
886 my $maxrow = $self->nrow - 1; 1210 my $maxrow = $self->nrow - 1;
887 1211
888 my ($beg, $end) = ($row, $row); 1212 my ($beg, $end) = ($row, $row);
952 $offset / $self->{ncol} + $self->{beg}, 1276 $offset / $self->{ncol} + $self->{beg},
953 $offset % $self->{ncol} 1277 $offset % $self->{ncol}
954 ) 1278 )
955} 1279}
956 1280
957=item ($row, $col) = $line->coord_of ($offset)
958=item $text = $term->special_encode $string 1281=item $text = $term->special_encode $string
959 1282
960Converts a perl string into the special encoding used by rxvt-unicode, 1283Converts a perl string into the special encoding used by rxvt-unicode,
961where one character corresponds to one screen cell. See 1284where one character corresponds to one screen cell. See
962C<< $term->ROW_t >> for details. 1285C<< $term->ROW_t >> for details.
964=item $string = $term->special_decode $text 1287=item $string = $term->special_decode $text
965 1288
966Converts rxvt-unicodes text reprsentation into a perl string. See 1289Converts rxvt-unicodes text reprsentation into a perl string. See
967C<< $term->ROW_t >> for details. 1290C<< $term->ROW_t >> for details.
968 1291
1292=item $success = $term->grab_button ($button, $modifiermask)
1293
1294Registers a synchronous button grab. See the XGrabButton manpage.
1295
1296=item $success = $term->grab ($eventtime[, $sync])
1297
1298Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1299synchronous (C<$sync> is true). Also remembers the grab timestampe.
1300
1301=item $term->allow_events_async
1302
1303Calls XAllowEvents with AsyncBoth for the most recent grab.
1304
1305=item $term->allow_events_sync
1306
1307Calls XAllowEvents with SyncBoth for the most recent grab.
1308
1309=item $term->allow_events_replay
1310
1311Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1312recent grab.
1313
1314=item $term->ungrab
1315
1316Calls XUngrab for the most recent grab. Is called automatically on
1317evaluation errors, as it is better to lose the grab in the error case as
1318the session.
1319
969=back 1320=back
970 1321
1322=cut
1323
1324package urxvt::popup;
1325
971=head2 The C<urxvt::popup> Class 1326=head2 The C<urxvt::popup> Class
972 1327
973=over 4 1328=over 4
974 1329
975=cut 1330=cut
976
977package urxvt::popup;
978 1331
979sub add_item { 1332sub add_item {
980 my ($self, $item) = @_; 1333 my ($self, $item) = @_;
981 1334
1335 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1336 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1337 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1338
1339 $item->{render} ||= sub { $_[0]{text} };
1340
982 push @{ $self->{item} }, $item; 1341 push @{ $self->{item} }, $item;
983} 1342}
1343
1344=item $popup->add_title ($title)
1345
1346Adds a non-clickable title to the popup.
1347
1348=cut
1349
1350sub add_title {
1351 my ($self, $title) = @_;
1352
1353 $self->add_item ({
1354 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1355 text => $title,
1356 activate => sub { },
1357 });
1358}
1359
1360=item $popup->add_separator ([$sepchr])
1361
1362Creates a separator, optionally using the character given as C<$sepchr>.
1363
1364=cut
1365
1366sub add_separator {
1367 my ($self, $sep) = @_;
1368
1369 $sep ||= "=";
1370
1371 $self->add_item ({
1372 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1373 text => "",
1374 render => sub { $sep x $self->{term}->ncol },
1375 activate => sub { },
1376 });
1377}
1378
1379=item $popup->add_button ($text, $cb)
1380
1381Adds a clickable button to the popup. C<$cb> is called whenever it is
1382selected.
1383
1384=cut
984 1385
985sub add_button { 1386sub add_button {
986 my ($self, $text, $cb) = @_; 1387 my ($self, $text, $cb) = @_;
987 1388
988 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb }); 1389 $self->add_item ({ type => "button", text => $text, activate => $cb});
989} 1390}
1391
1392=item $popup->add_toggle ($text, $cb, $initial_value)
1393
1394Adds a toggle/checkbox item to the popup. Teh callback gets called
1395whenever it gets toggled, with a boolean indicating its value as its first
1396argument.
1397
1398=cut
1399
1400sub add_toggle {
1401 my ($self, $text, $cb, $value) = @_;
1402
1403 my $item; $item = {
1404 type => "button",
1405 text => " $text",
1406 value => $value,
1407 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1408 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1409 };
1410
1411 $self->add_item ($item);
1412}
1413
1414=item $popup->show
1415
1416Displays the popup (which is initially hidden).
1417
1418=cut
990 1419
991sub show { 1420sub show {
992 my ($self) = @_; 1421 my ($self) = @_;
993 1422
994 local $urxvt::popup::self = $self; 1423 local $urxvt::popup::self = $self;
995 1424
1425 my $env = $self->{term}->env;
1426 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1427 delete $env->{LC_ALL};
1428 $env->{LC_CTYPE} = $self->{term}->locale;
1429
1430 urxvt::term->new ($env, $self->{term}->resource ("name"),
996 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1431 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
997 "--transient-for" => $self->{term}->parent, 1432 "--transient-for" => $self->{term}->parent,
1433 "-display" => $self->{term}->display_id,
998 "-pe" => "urxvt-popup") 1434 "-pe" => "urxvt-popup")
999 or die "unable to create popup window\n"; 1435 or die "unable to create popup window\n";
1000} 1436}
1001 1437
1002sub DESTROY { 1438sub DESTROY {
1003 my ($self) = @_; 1439 my ($self) = @_;
1004 1440
1441 delete $self->{term}{_destroy}{$self};
1005 $self->{term}->ungrab; 1442 $self->{term}->ungrab;
1006} 1443}
1444
1445=back
1007 1446
1008=head2 The C<urxvt::timer> Class 1447=head2 The C<urxvt::timer> Class
1009 1448
1010This class implements timer watchers/events. Time is represented as a 1449This class implements timer watchers/events. Time is represented as a
1011fractional number of seconds since the epoch. Example: 1450fractional number of seconds since the epoch. Example:
1064 1503
1065 $term->{socket} = ... 1504 $term->{socket} = ...
1066 $term->{iow} = urxvt::iow 1505 $term->{iow} = urxvt::iow
1067 ->new 1506 ->new
1068 ->fd (fileno $term->{socket}) 1507 ->fd (fileno $term->{socket})
1069 ->events (1) # wait for read data 1508 ->events (urxvt::EVENT_READ)
1070 ->start 1509 ->start
1071 ->cb (sub { 1510 ->cb (sub {
1072 my ($iow, $revents) = @_; 1511 my ($iow, $revents) = @_;
1073 # $revents must be 1 here, no need to check 1512 # $revents must be 1 here, no need to check
1074 sysread $term->{socket}, my $buf, 8192 1513 sysread $term->{socket}, my $buf, 8192
1091 1530
1092Set the filedescriptor (not handle) to watch. 1531Set the filedescriptor (not handle) to watch.
1093 1532
1094=item $iow = $iow->events ($eventmask) 1533=item $iow = $iow->events ($eventmask)
1095 1534
1096Set 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
1097data, 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>.
1098 1538
1099=item $iow = $iow->start 1539=item $iow = $iow->start
1100 1540
1101Start watching for requested events on the given handle. 1541Start watching for requested events on the given handle.
1102 1542
1113This variable controls the verbosity level of the perl extension. Higher 1553This variable controls the verbosity level of the perl extension. Higher
1114numbers indicate more verbose output. 1554numbers indicate more verbose output.
1115 1555
1116=over 4 1556=over 4
1117 1557
1118=item =0 - only fatal messages 1558=item == 0 - fatal messages
1119 1559
1120=item =3 - script loading and management 1560=item >= 3 - script loading and management
1121 1561
1122=item =10 - all events received 1562=item >=10 - all events received
1123 1563
1124=back 1564=back
1125 1565
1126=head1 AUTHOR 1566=head1 AUTHOR
1127 1567

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines