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.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).
335 423
336=item urxvt::CurrentTime 424=item urxvt::CurrentTime
337 425
338=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 426=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
339Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 427Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
340Button4Mask, Button5Mask, AnyModifier 428Button4Mask, Button5Mask, AnyModifier
341 429
342Various constants for use in X events. 430Various constants for use in X calls and event processing.
343 431
344=back 432=back
345 433
346=head2 RENDITION 434=head2 RENDITION
347 435
374 462
375=item $background = urxvt::GET_BASEBG $rend 463=item $background = urxvt::GET_BASEBG $rend
376 464
377Return the foreground/background colour index, respectively. 465Return the foreground/background colour index, respectively.
378 466
379=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 467=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
380 468
381=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 469=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
382 470
383Replace the foreground/background colour in the rendition mask with the 471Replace the foreground/background colour in the rendition mask with the
384specified one. 472specified one.
385 473
386=item $value = urxvt::GET_CUSTOM ($rend) 474=item $value = urxvt::GET_CUSTOM $rend
387 475
388Return the "custom" value: Every rendition has 5 bits for use by 476Return the "custom" value: Every rendition has 5 bits for use by
389extensions. 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
390zero. 478zero.
391 479
392=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 480=item $rend = urxvt::SET_CUSTOM $rend, $new_value
393 481
394Change the custom value. 482Change the custom value.
395 483
396=back 484=back
397 485
398=cut 486=cut
399
400package urxvt;
401
402use strict;
403use Scalar::Util ();
404
405our $TERM;
406our @HOOKNAME;
407our $LIBDIR;
408 487
409BEGIN { 488BEGIN {
410 urxvt->bootstrap; 489 urxvt->bootstrap;
411 490
412 # overwrite perl's warn 491 # overwrite perl's warn
414 my $msg = join "", @_; 493 my $msg = join "", @_;
415 $msg .= "\n" 494 $msg .= "\n"
416 unless $msg =~ /\n$/; 495 unless $msg =~ /\n$/;
417 urxvt::warn ($msg); 496 urxvt::warn ($msg);
418 }; 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";
419} 503}
420 504
421my @hook_count; 505my @hook_count;
422my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 506my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
423 507
424sub verbose { 508sub verbose {
425 my ($level, $msg) = @_; 509 my ($level, $msg) = @_;
426 warn "$msg\n" if $level <= $verbosity; 510 warn "$msg\n" if $level <= $verbosity;
427} 511}
428 512
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"; 513my $extension_pkg = "extension0000";
447my %extension_pkg; 514my %extension_pkg;
448 515
449# load a single script into its own package, once only 516# load a single script into its own package, once only
450sub extension_package($) { 517sub extension_package($) {
456 verbose 3, "loading extension '$path' into package '$pkg'"; 523 verbose 3, "loading extension '$path' into package '$pkg'";
457 524
458 open my $fh, "<:raw", $path 525 open my $fh, "<:raw", $path
459 or die "$path: $!"; 526 or die "$path: $!";
460 527
528 my $source = untaint
461 my $source = "package $pkg; use strict; use utf8;\n" 529 "package $pkg; use strict; use utf8;\n"
462 . "use base urxvt::term::proxy::;\n" 530 . "use base urxvt::term::extension::;\n"
463 . "#line 1 \"$path\"\n{\n" 531 . "#line 1 \"$path\"\n{\n"
464 . (do { local $/; <$fh> }) 532 . (do { local $/; <$fh> })
465 . "\n};\n1"; 533 . "\n};\n1";
466 534
535 eval $source
467 eval $source or die "$path: $@"; 536 or die "$path: $@";
468 537
469 $pkg 538 $pkg
470 } 539 }
471} 540}
472 541
477 local $TERM = shift; 546 local $TERM = shift;
478 my $htype = shift; 547 my $htype = shift;
479 548
480 if ($htype == 0) { # INIT 549 if ($htype == 0) { # INIT
481 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 550 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
551
552 my %ext_arg;
482 553
483 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) {
484 my @files = grep -f $_, map "$_/$ext", @dirs; 567 my @files = grep -f $_, map "$_/$ext", @dirs;
485 568
486 if (@files) { 569 if (@files) {
487 register_package extension_package $files[0]; 570 $TERM->register_package (extension_package $files[0], $argv);
488 } else { 571 } else {
489 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";
490 } 573 }
491 } 574 }
575
576 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
577 warn $@ if $@;
492 } 578 }
493 579
494 $retval = undef; 580 $retval = undef;
495 581
496 if (my $cb = $TERM->{_hook}[$htype]) { 582 if (my $cb = $TERM->{_hook}[$htype]) {
498 if $verbosity >= 10; 584 if $verbosity >= 10;
499 585
500 keys %$cb; 586 keys %$cb;
501 587
502 while (my ($pkg, $cb) = each %$cb) { 588 while (my ($pkg, $cb) = each %$cb) {
503 eval { 589 $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; 590 and last;
591
592 if ($@) {
593 $TERM->ungrab; # better to lose the grab than the session
594 warn $@;
512 }; 595 }
513 warn $@ if $@;#d#
514 } 596 }
515 } 597 }
516 598
517 if ($htype == 1) { # DESTROY 599 if ($htype == 1) { # DESTROY
518 # remove hooks if unused
519 if (my $hook = $TERM->{_hook}) { 600 if (my $hook = delete $TERM->{_hook}) {
520 for my $htype (0..$#$hook) { 601 for my $htype (0..$#$hook) {
521 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 602 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
522 or set_should_invoke $htype, 0; 603 or set_should_invoke $htype, 0;
523 } 604 }
524 } 605 }
531 } 612 }
532 613
533 $retval 614 $retval
534} 615}
535 616
536sub urxvt::term::proxy::AUTOLOAD { 617# urxvt::term::extension
537 $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 =~ /:([^:]+)$/
538 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 659 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
539 660
540 eval qq{ 661 eval qq{
541 sub $urxvt::term::proxy::AUTOLOAD { 662 sub $AUTOLOAD {
542 my \$proxy = shift; 663 my \$proxy = shift;
543 \$proxy->{term}->$1 (\@_) 664 \$proxy->{term}->$1 (\@_)
544 } 665 }
545 1 666 1
546 } or die "FATAL: unable to compile method forwarder: $@"; 667 } or die "FATAL: unable to compile method forwarder: $@";
547 668
548 goto &$urxvt::term::proxy::AUTOLOAD; 669 goto &$AUTOLOAD;
549} 670}
671
672sub DESTROY {
673 # nop
674}
675
676# urxvt::destroy_hook
550 677
551sub urxvt::destroy_hook::DESTROY { 678sub urxvt::destroy_hook::DESTROY {
552 ${$_[0]}->(); 679 ${$_[0]}->();
553} 680}
554 681
555sub urxvt::destroy_hook(&) { 682sub urxvt::destroy_hook(&) {
556 bless \shift, urxvt::destroy_hook:: 683 bless \shift, urxvt::destroy_hook::
557} 684}
558 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
559=head2 The C<urxvt::term> Class 756=head2 The C<urxvt::term> Class
560 757
561=over 4 758=over 4
562 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
563=item $term->destroy 801=item $term->destroy
564 802
565Destroy 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
566 822
567=item $value = $term->resource ($name[, $newval]) 823=item $value = $term->resource ($name[, $newval])
568 824
569Returns the current resource value associated with a given name and 825Returns the current resource value associated with a given name and
570optionally 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>
580 836
581Please note that resource strings will currently only be freed when the 837Please note that resource strings will currently only be freed when the
582terminal is destroyed, so changing options frequently will eat memory. 838terminal is destroyed, so changing options frequently will eat memory.
583 839
584Here 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
585are 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>
586list: 842to see the actual list:
587 843
588 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 844 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
589 borderLess color cursorBlink cursorUnderline cutchars delete_key 845 borderLess color cursorBlink cursorUnderline cutchars delete_key
590 display_name embed ext_bwidth fade font geometry hold iconName 846 display_name embed ext_bwidth fade font geometry hold iconName
591 imFont imLocale inputMethod insecure int_bwidth intensityStyles 847 imFont imLocale inputMethod insecure int_bwidth intensityStyles
598 shade term_name title transparent transparent_all tripleclickwords 854 shade term_name title transparent transparent_all tripleclickwords
599 utmpInhibit visualBell 855 utmpInhibit visualBell
600 856
601=cut 857=cut
602 858
603sub urxvt::term::resource($$;$) { 859sub resource($$;$) {
604 my ($self, $name) = (shift, shift); 860 my ($self, $name) = (shift, shift);
605 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 861 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
606 &urxvt::term::_resource 862 &urxvt::term::_resource
607} 863}
608 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
609=item $rend = $term->rstyle ([$new_rstyle]) 870=item $rend = $term->rstyle ([$new_rstyle])
610 871
611Return and optionally change the current rendition. Text that is output by 872Return and optionally change the current rendition. Text that is output by
612the terminal application will use this style. 873the terminal application will use this style.
613 874
632 893
633=item $oldtext = $term->selection ([$newtext]) 894=item $oldtext = $term->selection ([$newtext])
634 895
635Return the current selection text and optionally replace it by C<$newtext>. 896Return the current selection text and optionally replace it by C<$newtext>.
636 897
637#=item $term->overlay ($x, $y, $text) 898=item $term->overlay_simple ($x, $y, $text)
638# 899
639#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.
640# 901
641#=cut 902=cut
642# 903
643#sub urxvt::term::scr_overlay { 904sub overlay_simple {
644# my ($self, $x, $y, $text) = @_; 905 my ($self, $x, $y, $text) = @_;
645# 906
646# my @lines = split /\n/, $text; 907 my @lines = split /\n/, $text;
647# 908
648# my $w = 0; 909 my $w = List::Util::max map $self->strwidth ($_), @lines;
649# for (map $self->strwidth ($_), @lines) { 910
650# $w = $_ if $w < $_;
651# }
652#
653# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 911 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
654# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 912 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
655#} 913
914 $overlay
915}
656 916
657=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 917=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
658 918
659Create a new (empty) overlay at the given position with the given 919Create a new (empty) overlay at the given position with the given
660width/height. C<$rstyle> defines the initial rendition style 920width/height. C<$rstyle> defines the initial rendition style
695C<$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,
696currently). 956currently).
697 957
698=cut 958=cut
699 959
700sub urxvt::term::popup { 960sub popup {
701 my ($self, $event) = @_; 961 my ($self, $event) = @_;
702 962
703 $self->grab ($event->{time}, 1) 963 $self->grab ($event->{time}, 1)
704 or return; 964 or return;
705 965
727 987
728=item $string = $term->locale_decode ($octets) 988=item $string = $term->locale_decode ($octets)
729 989
730Convert the given locale-encoded octets into a perl string. 990Convert the given locale-encoded octets into a perl string.
731 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
732=item $term->scr_add_lines ($string) 1009=item $term->scr_add_lines ($string)
733 1010
734Write 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
735running inside the terminal. It may not contain command sequences (escape 1012running inside the terminal. It may not contain command sequences (escape
736codes), 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
750 1027
751Write 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
752pass characters instead of octets, you should convert your strings first 1029pass characters instead of octets, you should convert your strings first
753to the locale-specific encoding using C<< $term->locale_encode >>. 1030to the locale-specific encoding using C<< $term->locale_encode >>.
754 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
755=item $windowid = $term->parent 1039=item $windowid = $term->parent
756 1040
757Return the window id of the toplevel window. 1041Return the window id of the toplevel window.
758 1042
759=item $windowid = $term->vt 1043=item $windowid = $term->vt
783=item $nrow_plus_saveLines = $term->total_rows 1067=item $nrow_plus_saveLines = $term->total_rows
784 1068
785=item $lines_in_scrollback = $term->nsaved 1069=item $lines_in_scrollback = $term->nsaved
786 1070
787Return 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}
788 1095
789=item $modifiermask = $term->ModLevel3Mask 1096=item $modifiermask = $term->ModLevel3Mask
790 1097
791=item $modifiermask = $term->ModMetaMask 1098=item $modifiermask = $term->ModMetaMask
792 1099
895 1202
896=back 1203=back
897 1204
898=cut 1205=cut
899 1206
900sub urxvt::term::line { 1207sub line {
901 my ($self, $row) = @_; 1208 my ($self, $row) = @_;
902 1209
903 my $maxrow = $self->nrow - 1; 1210 my $maxrow = $self->nrow - 1;
904 1211
905 my ($beg, $end) = ($row, $row); 1212 my ($beg, $end) = ($row, $row);
969 $offset / $self->{ncol} + $self->{beg}, 1276 $offset / $self->{ncol} + $self->{beg},
970 $offset % $self->{ncol} 1277 $offset % $self->{ncol}
971 ) 1278 )
972} 1279}
973 1280
974=item ($row, $col) = $line->coord_of ($offset)
975=item $text = $term->special_encode $string 1281=item $text = $term->special_encode $string
976 1282
977Converts a perl string into the special encoding used by rxvt-unicode, 1283Converts a perl string into the special encoding used by rxvt-unicode,
978where one character corresponds to one screen cell. See 1284where one character corresponds to one screen cell. See
979C<< $term->ROW_t >> for details. 1285C<< $term->ROW_t >> for details.
981=item $string = $term->special_decode $text 1287=item $string = $term->special_decode $text
982 1288
983Converts rxvt-unicodes text reprsentation into a perl string. See 1289Converts rxvt-unicodes text reprsentation into a perl string. See
984C<< $term->ROW_t >> for details. 1290C<< $term->ROW_t >> for details.
985 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
986=back 1320=back
987 1321
1322=cut
1323
1324package urxvt::popup;
1325
988=head2 The C<urxvt::popup> Class 1326=head2 The C<urxvt::popup> Class
989 1327
990=over 4 1328=over 4
991 1329
992=cut 1330=cut
993
994package urxvt::popup;
995 1331
996sub add_item { 1332sub add_item {
997 my ($self, $item) = @_; 1333 my ($self, $item) = @_;
998 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
999 push @{ $self->{item} }, $item; 1341 push @{ $self->{item} }, $item;
1000} 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
1001 1385
1002sub add_button { 1386sub add_button {
1003 my ($self, $text, $cb) = @_; 1387 my ($self, $text, $cb) = @_;
1004 1388
1005 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb }); 1389 $self->add_item ({ type => "button", text => $text, activate => $cb});
1006} 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
1007 1419
1008sub show { 1420sub show {
1009 my ($self) = @_; 1421 my ($self) = @_;
1010 1422
1011 local $urxvt::popup::self = $self; 1423 local $urxvt::popup::self = $self;
1012 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"),
1013 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,
1014 "--transient-for" => $self->{term}->parent, 1432 "--transient-for" => $self->{term}->parent,
1433 "-display" => $self->{term}->display_id,
1015 "-pe" => "urxvt-popup") 1434 "-pe" => "urxvt-popup")
1016 or die "unable to create popup window\n"; 1435 or die "unable to create popup window\n";
1017} 1436}
1018 1437
1019sub DESTROY { 1438sub DESTROY {
1020 my ($self) = @_; 1439 my ($self) = @_;
1021 1440
1441 delete $self->{term}{_destroy}{$self};
1022 $self->{term}->ungrab; 1442 $self->{term}->ungrab;
1023} 1443}
1444
1445=back
1024 1446
1025=head2 The C<urxvt::timer> Class 1447=head2 The C<urxvt::timer> Class
1026 1448
1027This class implements timer watchers/events. Time is represented as a 1449This class implements timer watchers/events. Time is represented as a
1028fractional number of seconds since the epoch. Example: 1450fractional number of seconds since the epoch. Example:
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