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.60 by root, Mon Jan 9 01:21:43 2006 UTC vs.
Revision 1.91 by root, Fri Jan 13 01:09:37 2006 UTC

26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40=over 4 40=over 4
41 41
42=item selection (enabled by default) 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 45when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 46now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 47arguments, which is very convenient, too, if your F<ls> supports
48C<--quoting-style=shell>.
48 49
49It also offers the following bindable event: 50A double-click usually selects the word under the cursor, further clicks
51will enlarge the selection.
52
53The selection works by trying to match a number of regexes and displaying
54them in increasing order of length. You can add your own regexes by
55specifying resources of the form:
56
57 URxvt.selection.pattern-0: perl-regex
58 URxvt.selection.pattern-1: perl-regex
59 ...
60
61The index number (0, 1...) must not have any holes, and each regex must
62contain at least one pair of capturing parentheses, which will be used for
63the match. For example, the followign adds a regex that matches everything
64between two vertical bars:
65
66 URxvt.selection.pattern-0: \\|([^|]+)\\|
67
68You can look at the source of the selection extension to see more
69interesting uses, such as parsing a line from beginning to end.
70
71This extension also offers the following bindable keyboard command:
50 72
51=over 4 73=over 4
52 74
53=item rot13 75=item rot13
54 76
64runtime. 86runtime.
65 87
66=item selection-popup (enabled by default) 88=item selection-popup (enabled by default)
67 89
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection 90Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action. 91text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content.
70 93
71=item digital-clock 94=item searchable-scrollback<hotkey> (enabled by default)
72 95
73Displays a digital clock using the built-in overlay. 96Adds regex search functionality to the scrollback buffer, triggered
97by a hotkey (default: C<M-s>). While in search mode, normal terminal
98input/output is suspended and a regex is displayed at the bottom of the
99screen.
100
101Inputting characters appends them to the regex and continues incremental
102search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
103search upwards/downwards in the scrollback buffer, C<End> jumps to the
104bottom. C<Escape> leaves search mode and returns to the point where search
105was started, while C<Enter> or C<Return> stay at the current position and
106additionally stores the first match in the current line into the primary
107selection.
108
109=item selection-autotransform
110
111This selection allows you to do automatic transforms on a selection
112whenever a selection is made.
113
114It works by specifying perl snippets (most useful is a single C<s///>
115operator) that modify C<$_> as resources:
116
117 URxvt.selection-autotransform.0: transform
118 URxvt.selection-autotransform.1: transform
119 ...
120
121For example, the following will transform selections of the form
122C<filename:number>, often seen in compiler messages, into C<vi +$filename
123$word>:
124
125 URxvt.selection-autotransform.0: s/^(\\S+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
126
127And this example matches the same,but replaces it with vi-commands you can
128paste directly into your (vi :) editor:
129
130 URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
131
132Of course, this can be modified to suit your needs and your editor :)
133
134To expand the example above to typical perl error messages ("XXX at
135FILENAME line YYY."), you need a slightly more elaborate solution:
136
137 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
138 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
139
140The first line tells the selection code to treat the unchanging part of
141every error message as a selection pattern, and the second line transforms
142the message into vi commands to load the file.
74 143
75=item mark-urls 144=item mark-urls
76 145
77Uses per-line display filtering (C<on_line_update>) to underline urls. 146Uses per-line display filtering (C<on_line_update>) to underline urls and
147make them clickable. When middle-clicked, the program specified in the
148resource C<urlLauncher> (default C<x-www-browser>) will be started with
149the URL as first argument.
78 150
79=item block-graphics-to-ascii 151=item block-graphics-to-ascii
80 152
81A not very useful example of filtering all text output to the terminal, 153A not very useful example of filtering all text output to the terminal,
82by replacing all line-drawing characters (U+2500 .. U+259F) by a 154by replacing all line-drawing characters (U+2500 .. U+259F) by a
83similar-looking ascii character. 155similar-looking ascii character.
84 156
157=item digital-clock
158
159Displays a digital clock using the built-in overlay.
160
85=item example-refresh-hooks 161=item example-refresh-hooks
86 162
87Displays a very simple digital clock in the upper right corner of the 163Displays a very simple digital clock in the upper right corner of the
88window. Illustrates overwriting the refresh callbacks to create your own 164window. Illustrates overwriting the refresh callbacks to create your own
89overlays or changes. 165overlays or changes.
90 166
91=back 167=back
168
169=head1 API DOCUMENTATION
92 170
93=head2 General API Considerations 171=head2 General API Considerations
94 172
95All objects (such as terminals, time watchers etc.) are typical 173All objects (such as terminals, time watchers etc.) are typical
96reference-to-hash objects. The hash can be used to store anything you 174reference-to-hash objects. The hash can be used to store anything you
109=over 4 187=over 4
110 188
111=item $text 189=item $text
112 190
113Rxvt-unicodes special way of encoding text, where one "unicode" character 191Rxvt-unicodes special way of encoding text, where one "unicode" character
114always represents one screen cell. See L<row_t> for a discussion of this format. 192always represents one screen cell. See L<ROW_t> for a discussion of this format.
115 193
116=item $string 194=item $string
117 195
118A perl text string, with an emphasis on I<text>. It can store all unicode 196A perl text string, with an emphasis on I<text>. It can store all unicode
119characters and is to be distinguished with text encoded in a specific 197characters and is to be distinguished with text encoded in a specific
124Either binary data or - more common - a text string encoded in a 202Either binary data or - more common - a text string encoded in a
125locale-specific way. 203locale-specific way.
126 204
127=back 205=back
128 206
207=head2 Extension Objects
208
209Very perl extension is a perl class. A separate perl object is created
210for each terminal and each extension and passed as the first parameter to
211hooks. So extensions can use their C<$self> object without having to think
212about other extensions, with the exception of methods and members that
213begin with an underscore character C<_>: these are reserved for internal
214use.
215
216Although it isn't a C<urxvt::term> object, you can call all methods of the
217C<urxvt::term> class on this object.
218
219It has the following methods and data members:
220
221=over 4
222
223=item $urxvt_term = $self->{term}
224
225Returns the C<urxvt::term> object associated with this instance of the
226extension. This member I<must not> be changed in any way.
227
228=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
229
230Dynamically enable the given hooks (named without the C<on_> prefix) for
231this extension, replacing any previous hook. This is useful when you want
232to overwrite time-critical hooks only temporarily.
233
234=item $self->disable ($hook_name[, $hook_name..])
235
236Dynamically disable the given hooks.
237
238=back
239
129=head2 Hooks 240=head2 Hooks
130 241
131The following subroutines can be declared in extension files, and will be 242The following subroutines can be declared in extension files, and will be
132called whenever the relevant event happens. 243called whenever the relevant event happens.
133 244
134The first argument passed to them is an object private to each terminal 245The first argument passed to them is an extension oject as described in
135and extension package. You can call all C<urxvt::term> methods on it, but 246the in the C<Extension Objects> section.
136its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
137object that is shared between all packages is stored in the C<term>
138member. It is, however, blessed intot he package of the extension script,
139so for all practical purposes you can treat an extension script as a class.
140 247
141All of them must return a boolean value. If it is true, then the event 248B<All> of these hooks must return a boolean value. If it is true, then the
142counts as being I<consumed>, and the invocation of other hooks is skipped, 249event counts as being I<consumed>, and the invocation of other hooks is
143and the relevant action might not be carried out by the C++ code. 250skipped, and the relevant action might not be carried out by the C++ code.
144 251
145When in doubt, return a false value (preferably C<()>). 252I<< When in doubt, return a false value (preferably C<()>). >>
146 253
147=over 4 254=over 4
148 255
149=item on_init $term 256=item on_init $term
150 257
185=item on_sel_extend $term 292=item on_sel_extend $term
186 293
187Called whenever the user tries to extend the selection (e.g. with a double 294Called whenever the user tries to extend the selection (e.g. with a double
188click) and is either supposed to return false (normal operation), or 295click) and is either supposed to return false (normal operation), or
189should extend the selection itelf and return true to suppress the built-in 296should extend the selection itelf and return true to suppress the built-in
190processing. 297processing. This can happen multiple times, as long as the callback
298returns true, it will be called on every further click by the user and is
299supposed to enlarge the selection more and more, if possible.
191 300
192See the F<selection> example extension. 301See the F<selection> example extension.
193 302
194=item on_view_change $term, $offset 303=item on_view_change $term, $offset
195 304
204than the scroll back buffer or the terminal. 313than the scroll back buffer or the terminal.
205 314
206It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 315It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
207$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 316$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
208number of lines that will be in the scrollback buffer. 317number of lines that will be in the scrollback buffer.
209
210=item on_tty_activity $term *NYI*
211
212Called whenever the program(s) running in the urxvt window send output.
213 318
214=item on_osc_seq $term, $string 319=item on_osc_seq $term, $string
215 320
216Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 321Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
217operating system command) is processed. Cursor position and other state 322operating system command) is processed. Cursor position and other state
230can filter/change and output the text yourself by returning a true value 335can filter/change and output the text yourself by returning a true value
231and calling C<< $term->scr_add_lines >> yourself. Please note that this 336and calling C<< $term->scr_add_lines >> yourself. Please note that this
232might be very slow, however, as your hook is called for B<all> text being 337might be very slow, however, as your hook is called for B<all> text being
233output. 338output.
234 339
340=item on_tt_write $term, $octets
341
342Called whenever some data is written to the tty/pty and can be used to
343suppress or filter tty input.
344
235=item on_line_update $term, $row 345=item on_line_update $term, $row
236 346
237Called whenever a line was updated or changed. Can be used to filter 347Called whenever a line was updated or changed. Can be used to filter
238screen output (e.g. underline urls or other useless stuff). Only lines 348screen output (e.g. underline urls or other useless stuff). Only lines
239that are being shown will be filtered, and, due to performance reasons, 349that are being shown will be filtered, and, due to performance reasons,
271=item on_focus_out $term 381=item on_focus_out $term
272 382
273Called wheneever the window loses keyboard focus, before rxvt-unicode does 383Called wheneever the window loses keyboard focus, before rxvt-unicode does
274focus out processing. 384focus out processing.
275 385
276=item on_key_press $term, $event, $octets 386=item on_key_press $term, $event, $keysym, $octets
277 387
278=item on_key_release $term, $event 388=item on_key_release $term, $event, $keysym
279 389
280=item on_button_press $term, $event 390=item on_button_press $term, $event
281 391
282=item on_button_release $term, $event 392=item on_button_release $term, $event
283 393
299 409
300subwindow. 410subwindow.
301 411
302=back 412=back
303 413
414=cut
415
416package urxvt;
417
418use utf8;
419use strict;
420use Carp ();
421use Scalar::Util ();
422use List::Util ();
423
424our $VERSION = 1;
425our $TERM;
426our @HOOKNAME;
427our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
428our %OPTION;
429
430our $LIBDIR;
431our $RESNAME;
432our $RESCLASS;
433our $RXVTNAME;
434
304=head2 Variables in the C<urxvt> Package 435=head2 Variables in the C<urxvt> Package
305 436
306=over 4 437=over 4
438
439=item $urxvt::LIBDIR
440
441The rxvt-unicode library directory, where, among other things, the perl
442modules and scripts are stored.
443
444=item $urxvt::RESCLASS, $urxvt::RESCLASS
445
446The resource class and name rxvt-unicode uses to look up X resources.
447
448=item $urxvt::RXVTNAME
449
450The basename of the installed binaries, usually C<urxvt>.
307 451
308=item $urxvt::TERM 452=item $urxvt::TERM
309 453
310The current terminal. This variable stores the current C<urxvt::term> 454The current terminal. This variable stores the current C<urxvt::term>
311object, whenever a callback/hook is executing. 455object, whenever a callback/hook is executing.
313=back 457=back
314 458
315=head2 Functions in the C<urxvt> Package 459=head2 Functions in the C<urxvt> Package
316 460
317=over 4 461=over 4
318
319=item $term = new urxvt [arg...]
320
321Creates a new terminal, very similar as if you had started it with
322C<system $binfile, arg...>. Croaks (and probably outputs an error message)
323if the new instance couldn't be created. Returns C<undef> if the new
324instance didn't initialise perl, and the terminal object otherwise. The
325C<init> and C<start> hooks will be called during the call.
326 462
327=item urxvt::fatal $errormessage 463=item urxvt::fatal $errormessage
328 464
329Fatally aborts execution with the given error message. Avoid at all 465Fatally aborts execution with the given error message. Avoid at all
330costs! The only time this is acceptable is when the terminal process 466costs! The only time this is acceptable is when the terminal process
336newline. The module also overwrites the C<warn> builtin with a function 472newline. The module also overwrites the C<warn> builtin with a function
337that calls this function. 473that calls this function.
338 474
339Using this function has the advantage that its output ends up in the 475Using this function has the advantage that its output ends up in the
340correct place, e.g. on stderr of the connecting urxvtc client. 476correct place, e.g. on stderr of the connecting urxvtc client.
477
478Messages have a size limit of 1023 bytes currently.
479
480=item $is_safe = urxvt::safe
481
482Returns true when it is safe to do potentially unsafe things, such as
483evaluating perl code specified by the user. This is true when urxvt was
484started setuid or setgid.
341 485
342=item $time = urxvt::NOW 486=item $time = urxvt::NOW
343 487
344Returns the "current time" (as per the event loop). 488Returns the "current time" (as per the event loop).
345 489
384 528
385=item $background = urxvt::GET_BASEBG $rend 529=item $background = urxvt::GET_BASEBG $rend
386 530
387Return the foreground/background colour index, respectively. 531Return the foreground/background colour index, respectively.
388 532
389=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 533=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
390 534
391=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 535=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
392 536
393Replace the foreground/background colour in the rendition mask with the 537Replace the foreground/background colour in the rendition mask with the
394specified one. 538specified one.
395 539
396=item $value = urxvt::GET_CUSTOM ($rend) 540=item $value = urxvt::GET_CUSTOM $rend
397 541
398Return the "custom" value: Every rendition has 5 bits for use by 542Return the "custom" value: Every rendition has 5 bits for use by
399extensions. They can be set and changed as you like and are initially 543extensions. They can be set and changed as you like and are initially
400zero. 544zero.
401 545
402=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 546=item $rend = urxvt::SET_CUSTOM $rend, $new_value
403 547
404Change the custom value. 548Change the custom value.
405 549
406=back 550=back
407 551
408=cut 552=cut
409
410package urxvt;
411
412use utf8;
413use strict;
414use Scalar::Util ();
415use List::Util ();
416
417our $VERSION = 1;
418our $TERM;
419our @HOOKNAME;
420our %OPTION;
421our $LIBDIR;
422 553
423BEGIN { 554BEGIN {
424 urxvt->bootstrap; 555 urxvt->bootstrap;
425 556
426 # overwrite perl's warn 557 # overwrite perl's warn
429 $msg .= "\n" 560 $msg .= "\n"
430 unless $msg =~ /\n$/; 561 unless $msg =~ /\n$/;
431 urxvt::warn ($msg); 562 urxvt::warn ($msg);
432 }; 563 };
433 564
565 # %ENV is the original startup environment
434 delete $ENV{IFS}; 566 delete $ENV{IFS};
435 delete $ENV{CDPATH}; 567 delete $ENV{CDPATH};
436 delete $ENV{BASH_ENV}; 568 delete $ENV{BASH_ENV};
437 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin"; 569 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
438} 570}
443sub verbose { 575sub verbose {
444 my ($level, $msg) = @_; 576 my ($level, $msg) = @_;
445 warn "$msg\n" if $level <= $verbosity; 577 warn "$msg\n" if $level <= $verbosity;
446} 578}
447 579
448# find on_xxx subs in the package and register them
449# as hooks
450sub register_package($) {
451 my ($pkg) = @_;
452
453 for my $htype (0.. $#HOOKNAME) {
454 my $name = $HOOKNAME[$htype];
455
456 my $ref = $pkg->can ("on_" . lc $name)
457 or next;
458
459 $TERM->{_hook}[$htype]{$pkg} = $ref;
460 $hook_count[$htype]++
461 or set_should_invoke $htype, 1;
462 }
463}
464
465my $extension_pkg = "extension0000"; 580my $extension_pkg = "extension0000";
466my %extension_pkg; 581my %extension_pkg;
467 582
468# load a single script into its own package, once only 583# load a single script into its own package, once only
469sub extension_package($) { 584sub extension_package($) {
475 verbose 3, "loading extension '$path' into package '$pkg'"; 590 verbose 3, "loading extension '$path' into package '$pkg'";
476 591
477 open my $fh, "<:raw", $path 592 open my $fh, "<:raw", $path
478 or die "$path: $!"; 593 or die "$path: $!";
479 594
595 my $source = untaint
480 my $source = untaint "package $pkg; use strict; use utf8;\n" 596 "package $pkg; use strict; use utf8;\n"
481 . "use base urxvt::term::proxy::;\n" 597 . "use base urxvt::term::extension::;\n"
482 . "#line 1 \"$path\"\n{\n" 598 . "#line 1 \"$path\"\n{\n"
483 . (do { local $/; <$fh> }) 599 . (do { local $/; <$fh> })
484 . "\n};\n1"; 600 . "\n};\n1";
485 601
602 eval $source
486 eval $source or die "$path: $@"; 603 or die "$path: $@";
487 604
488 $pkg 605 $pkg
489 } 606 }
490} 607}
491 608
497 my $htype = shift; 614 my $htype = shift;
498 615
499 if ($htype == 0) { # INIT 616 if ($htype == 0) { # INIT
500 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 617 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
501 618
502 my %want_ext; 619 my %ext_arg;
503 620
504 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 621 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
505 if ($_ eq "default") { 622 if ($_ eq "default") {
506 $want_ext{$_}++ for qw(selection option-popup selection-popup); 623 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
507 } elsif (/^-(.*)$/) { 624 } elsif (/^-(.*)$/) {
508 delete $want_ext{$1}; 625 delete $ext_arg{$1};
626 } elsif (/^([^<]+)<(.*)>$/) {
627 push @{ $ext_arg{$1} }, $2;
509 } else { 628 } else {
510 $want_ext{$_}++; 629 $ext_arg{$_} ||= [];
511 } 630 }
512 } 631 }
513 632
514 for my $ext (keys %want_ext) { 633 while (my ($ext, $argv) = each %ext_arg) {
515 my @files = grep -f $_, map "$_/$ext", @dirs; 634 my @files = grep -f $_, map "$_/$ext", @dirs;
516 635
517 if (@files) { 636 if (@files) {
518 register_package extension_package $files[0]; 637 $TERM->register_package (extension_package $files[0], $argv);
519 } else { 638 } else {
520 warn "perl extension '$ext' not found in perl library search path\n"; 639 warn "perl extension '$ext' not found in perl library search path\n";
521 } 640 }
522 } 641 }
523 642
532 if $verbosity >= 10; 651 if $verbosity >= 10;
533 652
534 keys %$cb; 653 keys %$cb;
535 654
536 while (my ($pkg, $cb) = each %$cb) { 655 while (my ($pkg, $cb) = each %$cb) {
537 eval { 656 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
538 $retval = $cb->(
539 $TERM->{_pkg}{$pkg} ||= do {
540 my $proxy = bless { }, $pkg;
541 Scalar::Util::weaken ($proxy->{term} = $TERM);
542 $proxy
543 },
544 @_,
545 ) and last; 657 and last;
546 }; 658
547 if ($@) { 659 if ($@) {
548 $TERM->ungrab; # better to lose the grab than the session 660 $TERM->ungrab; # better to lose the grab than the session
549 warn $@; 661 warn $@;
550 } 662 }
551 } 663 }
664
665 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
666 if $verbosity >= 11;
552 } 667 }
553 668
554 if ($htype == 1) { # DESTROY 669 if ($htype == 1) { # DESTROY
555 # remove hooks if unused
556 if (my $hook = $TERM->{_hook}) { 670 if (my $hook = delete $TERM->{_hook}) {
557 for my $htype (0..$#$hook) { 671 for my $htype (0..$#$hook) {
558 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 672 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
559 or set_should_invoke $htype, 0; 673 or set_should_invoke $htype, 0;
560 } 674 }
561 } 675 }
568 } 682 }
569 683
570 $retval 684 $retval
571} 685}
572 686
573# urxvt::term::proxy 687sub exec_async(@) {
688 my $pid = fork;
574 689
575sub urxvt::term::proxy::AUTOLOAD { 690 return
576 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 691 if !defined $pid or $pid;
692
693 %ENV = %{ $TERM->env };
694
695 exec @_;
696 _exit 255;
697}
698
699# urxvt::term::extension
700
701package urxvt::term::extension;
702
703sub enable {
704 my ($self, %hook) = @_;
705 my $pkg = $self->{_pkg};
706
707 while (my ($name, $cb) = each %hook) {
708 my $htype = $HOOKTYPE{uc $name};
709 defined $htype
710 or Carp::croak "unsupported hook type '$name'";
711
712 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
713 $hook_count[$htype]++
714 or urxvt::set_should_invoke $htype, 1;
715 }
716
717 $self->{term}{_hook}[$htype]{$pkg} = $cb;
718 }
719}
720
721sub disable {
722 my ($self, @hook) = @_;
723 my $pkg = $self->{_pkg};
724
725 for my $name (@hook) {
726 my $htype = $HOOKTYPE{uc $name};
727 defined $htype
728 or Carp::croak "unsupported hook type '$name'";
729
730 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
731 --$hook_count[$htype]
732 or urxvt::set_should_invoke $htype, 0;
733 }
734 }
735}
736
737our $AUTOLOAD;
738
739sub AUTOLOAD {
740 $AUTOLOAD =~ /:([^:]+)$/
577 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 741 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
578 742
579 eval qq{ 743 eval qq{
580 sub $urxvt::term::proxy::AUTOLOAD { 744 sub $AUTOLOAD {
581 my \$proxy = shift; 745 my \$proxy = shift;
582 \$proxy->{term}->$1 (\@_) 746 \$proxy->{term}->$1 (\@_)
583 } 747 }
584 1 748 1
585 } or die "FATAL: unable to compile method forwarder: $@"; 749 } or die "FATAL: unable to compile method forwarder: $@";
586 750
587 goto &$urxvt::term::proxy::AUTOLOAD; 751 goto &$AUTOLOAD;
588} 752}
589 753
590sub urxvt::term::proxy::DESTROY { 754sub DESTROY {
591 # nop 755 # nop
592} 756}
593 757
594# urxvt::destroy_hook 758# urxvt::destroy_hook
595 759
605 769
606=head2 The C<urxvt::anyevent> Class 770=head2 The C<urxvt::anyevent> Class
607 771
608The sole purpose of this class is to deliver an interface to the 772The sole purpose of this class is to deliver an interface to the
609C<AnyEvent> module - any module using it will work inside urxvt without 773C<AnyEvent> module - any module using it will work inside urxvt without
610further work. The only exception is that you cannot wait on condition 774further programming. The only exception is that you cannot wait on
611variables, but non-blocking condvar use is ok. What this means is that you 775condition variables, but non-blocking condvar use is ok. What this means
612cannot use blocking APIs, but the non-blocking variant should work. 776is that you cannot use blocking APIs, but the non-blocking variant should
777work.
613 778
614=cut 779=cut
615 780
616our $VERSION = 1; 781our $VERSION = 1;
617 782
662 ${$_[0]}++; 827 ${$_[0]}++;
663} 828}
664 829
665sub urxvt::anyevent::condvar::wait { 830sub urxvt::anyevent::condvar::wait {
666 unless (${$_[0]}) { 831 unless (${$_[0]}) {
667 require Carp;
668 Carp::croak ("AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"); 832 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
669 } 833 }
670} 834}
671 835
672package urxvt::term; 836package urxvt::term;
673 837
674=head2 The C<urxvt::term> Class 838=head2 The C<urxvt::term> Class
675 839
676=over 4 840=over 4
677 841
842=cut
843
844# find on_xxx subs in the package and register them
845# as hooks
846sub register_package {
847 my ($self, $pkg, $argv) = @_;
848
849 my $proxy = bless {
850 _pkg => $pkg,
851 argv => $argv,
852 }, $pkg;
853 Scalar::Util::weaken ($proxy->{term} = $self);
854
855 $self->{_pkg}{$pkg} = $proxy;
856
857 for my $name (@HOOKNAME) {
858 if (my $ref = $pkg->can ("on_" . lc $name)) {
859 $proxy->enable ($name => $ref);
860 }
861 }
862}
863
864=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
865
866Creates a new terminal, very similar as if you had started it with system
867C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
868hash which defines the environment of the new terminal.
869
870Croaks (and probably outputs an error message) if the new instance
871couldn't be created. Returns C<undef> if the new instance didn't
872initialise perl, and the terminal object otherwise. The C<init> and
873C<start> hooks will be called during this call.
874
875=cut
876
877sub new {
878 my ($class, $env, @args) = @_;
879
880 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
881}
882
678=item $term->destroy 883=item $term->destroy
679 884
680Destroy the terminal object (close the window, free resources etc.). 885Destroy the terminal object (close the window, free resources
886etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
887watchers (timers, io watchers) are still active.
681 888
682=item $isset = $term->option ($optval[, $set]) 889=item $isset = $term->option ($optval[, $set])
683 890
684Returns true if the option specified by C<$optval> is enabled, and 891Returns true if the option specified by C<$optval> is enabled, and
685optionally change it. All option values are stored by name in the hash 892optionally change it. All option values are stored by name in the hash
735 my ($self, $name) = (shift, shift); 942 my ($self, $name) = (shift, shift);
736 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 943 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
737 &urxvt::term::_resource 944 &urxvt::term::_resource
738} 945}
739 946
947=item $value = $term->x_resource ($pattern)
948
949Returns the X-Resource for the given pattern, excluding the program or
950class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
951same value as used by this instance of rxvt-unicode. Returns C<undef> if no
952resource with that pattern exists.
953
954This method should only be called during the C<on_start> hook, as there is
955only one resource database per display, and later invocations might return
956the wrong resources.
957
958=item $success = $term->parse_keysym ($keysym_spec, $command_string)
959
960Adds a keymap translation exactly as specified via a resource. See the
961C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
962
740=item $rend = $term->rstyle ([$new_rstyle]) 963=item $rend = $term->rstyle ([$new_rstyle])
741 964
742Return and optionally change the current rendition. Text that is output by 965Return and optionally change the current rendition. Text that is output by
743the terminal application will use this style. 966the terminal application will use this style.
744 967
754=item ($row, $col) = $term->selection_end ([$row, $col]) 977=item ($row, $col) = $term->selection_end ([$row, $col])
755 978
756Return the current values of the selection mark, begin or end positions, 979Return the current values of the selection mark, begin or end positions,
757and optionally set them to new values. 980and optionally set them to new values.
758 981
982=item $term->selection_make ($eventtime[, $rectangular])
983
984Tries to make a selection as set by C<selection_beg> and
985C<selection_end>. If C<$rectangular> is true (default: false), a
986rectangular selection will be made. This is the prefered function to make
987a selection.
988
759=item $success = $term->selection_grab ($eventtime) 989=item $success = $term->selection_grab ($eventtime)
760 990
761Try to request the primary selection from the server (for example, as set 991Try to request the primary selection text from the server (for example, as
762by the next method). 992set by the next method). No visual feedback will be given. This function
993is mostly useful from within C<on_sel_grab> hooks.
763 994
764=item $oldtext = $term->selection ([$newtext]) 995=item $oldtext = $term->selection ([$newtext])
765 996
766Return the current selection text and optionally replace it by C<$newtext>. 997Return the current selection text and optionally replace it by C<$newtext>.
767 998
768#=item $term->overlay ($x, $y, $text) 999=item $term->overlay_simple ($x, $y, $text)
769# 1000
770#Create a simple multi-line overlay box. See the next method for details. 1001Create a simple multi-line overlay box. See the next method for details.
771# 1002
772#=cut 1003=cut
773# 1004
774#sub urxvt::term::scr_overlay { 1005sub overlay_simple {
775# my ($self, $x, $y, $text) = @_; 1006 my ($self, $x, $y, $text) = @_;
776# 1007
777# my @lines = split /\n/, $text; 1008 my @lines = split /\n/, $text;
778# 1009
779# my $w = 0; 1010 my $w = List::Util::max map $self->strwidth ($_), @lines;
780# for (map $self->strwidth ($_), @lines) { 1011
781# $w = $_ if $w < $_;
782# }
783#
784# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1012 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
785# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1013 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
786#} 1014
1015 $overlay
1016}
787 1017
788=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1018=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
789 1019
790Create a new (empty) overlay at the given position with the given 1020Create a new (empty) overlay at the given position with the given
791width/height. C<$rstyle> defines the initial rendition style 1021width/height. C<$rstyle> defines the initial rendition style
858 1088
859=item $string = $term->locale_decode ($octets) 1089=item $string = $term->locale_decode ($octets)
860 1090
861Convert the given locale-encoded octets into a perl string. 1091Convert the given locale-encoded octets into a perl string.
862 1092
1093=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1094
1095XORs the rendition values in the given span with the provided value
1096(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1097refresh hooks to provide effects similar to the selection.
1098
1099=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1100
1101Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1102whitespace will additionally be xored with the C<$rstyle2>, which defaults
1103to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1104it instead. Both styles I<MUST NOT> contain font styles.
1105
1106=item $term->scr_bell
1107
1108Ring the bell!
1109
863=item $term->scr_add_lines ($string) 1110=item $term->scr_add_lines ($string)
864 1111
865Write the given text string to the screen, as if output by the application 1112Write the given text string to the screen, as if output by the application
866running inside the terminal. It may not contain command sequences (escape 1113running inside the terminal. It may not contain command sequences (escape
867codes), but is free to use line feeds, carriage returns and tabs. The 1114codes), but is free to use line feeds, carriage returns and tabs. The
881 1128
882Write the octets given in C<$data> to the tty (i.e. as program input). To 1129Write the octets given in C<$data> to the tty (i.e. as program input). To
883pass characters instead of octets, you should convert your strings first 1130pass characters instead of octets, you should convert your strings first
884to the locale-specific encoding using C<< $term->locale_encode >>. 1131to the locale-specific encoding using C<< $term->locale_encode >>.
885 1132
1133=item $old_events = $term->pty_ev_events ([$new_events])
1134
1135Replaces the event mask of the pty watcher by the given event mask. Can
1136be used to suppress input and output handling to the pty/tty. See the
1137description of C<< urxvt::timer->events >>. Make sure to always restore
1138the previous value.
1139
886=item $windowid = $term->parent 1140=item $windowid = $term->parent
887 1141
888Return the window id of the toplevel window. 1142Return the window id of the toplevel window.
889 1143
890=item $windowid = $term->vt 1144=item $windowid = $term->vt
914=item $nrow_plus_saveLines = $term->total_rows 1168=item $nrow_plus_saveLines = $term->total_rows
915 1169
916=item $lines_in_scrollback = $term->nsaved 1170=item $lines_in_scrollback = $term->nsaved
917 1171
918Return various integers describing terminal characteristics. 1172Return various integers describing terminal characteristics.
1173
1174=item $x_display = $term->display_id
1175
1176Return the DISPLAY used by rxvt-unicode.
1177
1178=item $lc_ctype = $term->locale
1179
1180Returns the LC_CTYPE category string used by this rxvt-unicode.
1181
1182=item $env = $term->env
1183
1184Returns a copy of the environment in effect for the terminal as a hashref
1185similar to C<\%ENV>.
1186
1187=cut
1188
1189sub env {
1190 if (my $env = $_[0]->_env) {
1191 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1192 } else {
1193 +{ %ENV }
1194 }
1195}
919 1196
920=item $modifiermask = $term->ModLevel3Mask 1197=item $modifiermask = $term->ModLevel3Mask
921 1198
922=item $modifiermask = $term->ModMetaMask 1199=item $modifiermask = $term->ModMetaMask
923 1200
1016Return the row number of the first/last row of the line, respectively. 1293Return the row number of the first/last row of the line, respectively.
1017 1294
1018=item $offset = $line->offset_of ($row, $col) 1295=item $offset = $line->offset_of ($row, $col)
1019 1296
1020Returns the character offset of the given row|col pair within the logical 1297Returns the character offset of the given row|col pair within the logical
1021line. 1298line. Works for rows outside the line, too, and returns corresponding
1299offsets outside the string.
1022 1300
1023=item ($row, $col) = $line->coord_of ($offset) 1301=item ($row, $col) = $line->coord_of ($offset)
1024 1302
1025Translates a string offset into terminal coordinates again. 1303Translates a string offset into terminal coordinates again.
1026 1304
1100 $offset / $self->{ncol} + $self->{beg}, 1378 $offset / $self->{ncol} + $self->{beg},
1101 $offset % $self->{ncol} 1379 $offset % $self->{ncol}
1102 ) 1380 )
1103} 1381}
1104 1382
1105=item ($row, $col) = $line->coord_of ($offset)
1106=item $text = $term->special_encode $string 1383=item $text = $term->special_encode $string
1107 1384
1108Converts a perl string into the special encoding used by rxvt-unicode, 1385Converts a perl string into the special encoding used by rxvt-unicode,
1109where one character corresponds to one screen cell. See 1386where one character corresponds to one screen cell. See
1110C<< $term->ROW_t >> for details. 1387C<< $term->ROW_t >> for details.
1112=item $string = $term->special_decode $text 1389=item $string = $term->special_decode $text
1113 1390
1114Converts rxvt-unicodes text reprsentation into a perl string. See 1391Converts rxvt-unicodes text reprsentation into a perl string. See
1115C<< $term->ROW_t >> for details. 1392C<< $term->ROW_t >> for details.
1116 1393
1394=item $success = $term->grab_button ($button, $modifiermask)
1395
1396Registers a synchronous button grab. See the XGrabButton manpage.
1397
1398=item $success = $term->grab ($eventtime[, $sync])
1399
1400Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1401synchronous (C<$sync> is true). Also remembers the grab timestampe.
1402
1403=item $term->allow_events_async
1404
1405Calls XAllowEvents with AsyncBoth for the most recent grab.
1406
1407=item $term->allow_events_sync
1408
1409Calls XAllowEvents with SyncBoth for the most recent grab.
1410
1411=item $term->allow_events_replay
1412
1413Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1414recent grab.
1415
1416=item $term->ungrab
1417
1418Calls XUngrab for the most recent grab. Is called automatically on
1419evaluation errors, as it is better to lose the grab in the error case as
1420the session.
1421
1117=back 1422=back
1118 1423
1119=cut 1424=cut
1120 1425
1121package urxvt::popup; 1426package urxvt::popup;
1136 $item->{render} ||= sub { $_[0]{text} }; 1441 $item->{render} ||= sub { $_[0]{text} };
1137 1442
1138 push @{ $self->{item} }, $item; 1443 push @{ $self->{item} }, $item;
1139} 1444}
1140 1445
1141sub add_separator { 1446=item $popup->add_title ($title)
1142 my ($self, $sep) = @_;
1143 1447
1144 $sep ||= "═"; 1448Adds a non-clickable title to the popup.
1145 1449
1146 $self->add_item ({ 1450=cut
1147 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1148 text => "",
1149 render => sub { $sep x $urxvt::TERM->ncol },
1150 activate => sub { },
1151 });
1152}
1153 1451
1154sub add_title { 1452sub add_title {
1155 my ($self, $title) = @_; 1453 my ($self, $title) = @_;
1156 1454
1157 $self->add_item ({ 1455 $self->add_item ({
1159 text => $title, 1457 text => $title,
1160 activate => sub { }, 1458 activate => sub { },
1161 }); 1459 });
1162} 1460}
1163 1461
1462=item $popup->add_separator ([$sepchr])
1463
1464Creates a separator, optionally using the character given as C<$sepchr>.
1465
1466=cut
1467
1468sub add_separator {
1469 my ($self, $sep) = @_;
1470
1471 $sep ||= "=";
1472
1473 $self->add_item ({
1474 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1475 text => "",
1476 render => sub { $sep x $self->{term}->ncol },
1477 activate => sub { },
1478 });
1479}
1480
1481=item $popup->add_button ($text, $cb)
1482
1483Adds a clickable button to the popup. C<$cb> is called whenever it is
1484selected.
1485
1486=cut
1487
1164sub add_button { 1488sub add_button {
1165 my ($self, $text, $cb) = @_; 1489 my ($self, $text, $cb) = @_;
1166 1490
1167 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb}); 1491 $self->add_item ({ type => "button", text => $text, activate => $cb});
1168} 1492}
1493
1494=item $popup->add_toggle ($text, $cb, $initial_value)
1495
1496Adds a toggle/checkbox item to the popup. Teh callback gets called
1497whenever it gets toggled, with a boolean indicating its value as its first
1498argument.
1499
1500=cut
1169 1501
1170sub add_toggle { 1502sub add_toggle {
1171 my ($self, $text, $cb, $value) = @_; 1503 my ($self, $text, $cb, $value) = @_;
1172 1504
1173 my $item; $item = { 1505 my $item; $item = {
1174 type => "button", 1506 type => "button",
1175 text => " $text", 1507 text => " $text",
1176 value => $value, 1508 value => $value,
1177 render => sub { ($_[0]{value} ? "* " : " ") . $text }, 1509 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1178 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, 1510 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1179 }; 1511 };
1180 1512
1181 $self->add_item ($item); 1513 $self->add_item ($item);
1182} 1514}
1515
1516=item $popup->show
1517
1518Displays the popup (which is initially hidden).
1519
1520=cut
1183 1521
1184sub show { 1522sub show {
1185 my ($self) = @_; 1523 my ($self) = @_;
1186 1524
1187 local $urxvt::popup::self = $self; 1525 local $urxvt::popup::self = $self;
1188 1526
1527 my $env = $self->{term}->env;
1528 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1529 delete $env->{LC_ALL};
1530 $env->{LC_CTYPE} = $self->{term}->locale;
1531
1532 urxvt::term->new ($env, $self->{term}->resource ("name"),
1189 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1533 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1190 "--transient-for" => $self->{term}->parent, 1534 "--transient-for" => $self->{term}->parent,
1535 "-display" => $self->{term}->display_id,
1191 "-pe" => "urxvt-popup") 1536 "-pe" => "urxvt-popup")
1192 or die "unable to create popup window\n"; 1537 or die "unable to create popup window\n";
1193} 1538}
1194 1539
1195sub DESTROY { 1540sub DESTROY {
1196 my ($self) = @_; 1541 my ($self) = @_;
1197 1542
1198 delete $self->{term}{_destroy}{$self}; 1543 delete $self->{term}{_destroy}{$self};
1199 $self->{term}->ungrab; 1544 $self->{term}->ungrab;
1200} 1545}
1546
1547=back
1201 1548
1202=head2 The C<urxvt::timer> Class 1549=head2 The C<urxvt::timer> Class
1203 1550
1204This class implements timer watchers/events. Time is represented as a 1551This class implements timer watchers/events. Time is represented as a
1205fractional number of seconds since the epoch. Example: 1552fractional number of seconds since the epoch. Example:
1258 1605
1259 $term->{socket} = ... 1606 $term->{socket} = ...
1260 $term->{iow} = urxvt::iow 1607 $term->{iow} = urxvt::iow
1261 ->new 1608 ->new
1262 ->fd (fileno $term->{socket}) 1609 ->fd (fileno $term->{socket})
1263 ->events (1) # wait for read data 1610 ->events (urxvt::EVENT_READ)
1264 ->start 1611 ->start
1265 ->cb (sub { 1612 ->cb (sub {
1266 my ($iow, $revents) = @_; 1613 my ($iow, $revents) = @_;
1267 # $revents must be 1 here, no need to check 1614 # $revents must be 1 here, no need to check
1268 sysread $term->{socket}, my $buf, 8192 1615 sysread $term->{socket}, my $buf, 8192
1285 1632
1286Set the filedescriptor (not handle) to watch. 1633Set the filedescriptor (not handle) to watch.
1287 1634
1288=item $iow = $iow->events ($eventmask) 1635=item $iow = $iow->events ($eventmask)
1289 1636
1290Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1637Set the event mask to watch. The only allowed values are
1291data, Bit #1 (value C<2>) enables watching for write data. 1638C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1639together, or C<urxvt::EVENT_NONE>.
1292 1640
1293=item $iow = $iow->start 1641=item $iow = $iow->start
1294 1642
1295Start watching for requested events on the given handle. 1643Start watching for requested events on the given handle.
1296 1644
1311 1659
1312=item == 0 - fatal messages 1660=item == 0 - fatal messages
1313 1661
1314=item >= 3 - script loading and management 1662=item >= 3 - script loading and management
1315 1663
1316=item >=10 - all events received 1664=item >=10 - all called hooks
1665
1666=item >=11 - hook reutrn values
1317 1667
1318=back 1668=back
1319 1669
1320=head1 AUTHOR 1670=head1 AUTHOR
1321 1671

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines