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.245 by root, Mon Dec 22 09:10:12 2014 UTC vs.
Revision 1.272 by root, Thu Dec 29 01:10:08 2022 UTC

4 4
5urxvtperl - rxvt-unicode's embedded perl interpreter 5urxvtperl - rxvt-unicode's embedded perl interpreter
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 # create a file grab_test in $HOME: 9 # create a file grab_test in some directory:
10 10
11 sub on_sel_grab { 11 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection; 12 warn "you selected ", $_[0]->selection;
13 () 13 ()
14 } 14 }
15 15
16 # start a urxvt using it: 16 # start a urxvt instance using it:
17 17
18 urxvt --perl-lib $HOME -pe grab_test 18 urxvt --perl-lib path/to/somedirectory -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Every time a terminal object gets created, extension scripts specified via 22Every time a terminal object gets created, extension scripts specified via
23the C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict "vars"' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict qw(vars subs)' and 'use utf8'
26thus must be encoded as UTF-8. 26environment, and thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in urxvtd, where 28Each script will only ever be loaded once, even in urxvtd, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31You can disable the embedded perl interpreter by setting both "perl-ext" 31You can disable the embedded perl interpreter by setting both "perl-ext"
45 45
46 URxvt.perl-ext-common: default,selection-autotransform 46 URxvt.perl-ext-common: default,selection-autotransform
47 47
48Extensions may add additional resources and C<actions>, i.e., methods 48Extensions may add additional resources and C<actions>, i.e., methods
49which can be bound to a key and invoked by the user. An extension can 49which can be bound to a key and invoked by the user. An extension can
50define the resources it support and also default bindings for one or 50define the resources it support using so called META comments,
51more actions it provides using so called META comments, described
52below. Similarly to builtin resources, extension resources can also be 51described below. Similarly to builtin resources, extension resources
53specified on the command line as long options (with C<.> replaced by 52can also be specified on the command line as long options (with C<.>
54C<->), in which case the corresponding extension is loaded 53replaced by C<->), in which case the corresponding extension is loaded
55automatically. For this to work the extension B<must> define META 54automatically. For this to work the extension B<must> define META
56comments for its resources. 55comments for its resources.
57 56
58=head1 API DOCUMENTATION 57=head1 API DOCUMENTATION
59 58
71terminal is destroyed. 70terminal is destroyed.
72 71
73Argument names also often indicate the type of a parameter. Here are some 72Argument names also often indicate the type of a parameter. Here are some
74hints on what they mean: 73hints on what they mean:
75 74
76=over 4 75=over
77 76
78=item $text 77=item $text
79 78
80Rxvt-unicode's special way of encoding text, where one "unicode" character 79Rxvt-unicode's special way of encoding text, where one "unicode" character
81always represents one screen cell. See L<ROW_t> for a discussion of this format. 80always represents one screen cell. See L<ROW_t> for a discussion of this format.
115Additional methods only supported for extension objects are described in 114Additional methods only supported for extension objects are described in
116the C<urxvt::extension> section below. 115the C<urxvt::extension> section below.
117 116
118=head2 META comments 117=head2 META comments
119 118
120rxvt-unicode recognizes special comments in extensions that define 119Rxvt-unicode recognizes special meta comments in extensions that define
121different types of metadata: 120different types of metadata. These comments are scanned whenever a
121terminal is created and are typically used to autoload extensions when
122their resources or command line parameters are used.
122 123
124Currently, it recognises these comments below. Individual components are
125separated by colons (C<:>), and should not contain colons themselves -
126there is also currently no escaping mechanism provided for this.
127
123=over 4 128=over
124 129
125=item #:META:RESOURCE:name:type:desc 130=item #:META:RESOURCE:name:type:desc
126 131
127The RESOURCE comment defines a resource used by the extension, where 132The RESOURCE comment defines a resource used by the extension, where
128C<name> is the resource name, C<type> is the resource type, C<boolean> 133C<name> is the resource name, C<type> is the resource type, C<boolean>
129or C<string>, and C<desc> is the resource description. 134or C<string>, and C<desc> is the resource description.
130 135
131=item #:META:BINDING:sym:action 136The extension will be autoloaded when this resource is specified or used
137as a command line parameter.
132 138
133The BINDING comment defines a default binding for an action provided 139Example: matcher provides the C<matcher.launcher> resource by having this
134by the extension, where C<sym> is the key combination that triggers 140comment:
135the action, whose format is defined in the description of the 141
136B<keysym> resource in the urxvt(1) manpage, and C<action> is the name 142 #:META:RESOURCE:%.launcher:string:default launcher command
137of the action method. 143
144Example: load this extension when the C<-tr> command line option or
145resource name is used.
146
147 #:META:RESOURCE:tr:boolean:set root pixmap as background
148
149=item #:META:OSC:number:desc
150
151The OSC comment specifies an OSC sequence, where C<number> is the
152numerical OSC code and C<desc> is a short description that is currently
153unused.
154
155This will cause the extension to be autoloaded when the OSC sequence is
156used for the first time.
157
158Note that autoloading carries some extra responsibilities with it:
159although the terminal cannot really protect itself against malicious
160sources of command sequences, therefore relying on the programs running
161I<inside> to sanitize data that they output, it is very common for
162programs to emit command sequences from untrusted sources.
163
164While this means that extensions should, as a defense-in-depth mechanism,
165always consider whether OSC sequences are safe, autoloading automatically
166exposes any autoloaded extension in all terminal windows, so extra care
167should be taken.
168
169Example: the background extension registers OSC C<20> like this:
170
171 #:META:OSC:20:change/query background image
172
173=item #:META:OSC_PERL:prefix:desc
174
175The same as the OSC comment, but for the Perl OSC sequence (C<777>). The
176C<prefix> should be unique among extensions, of course, which is most
177easily arranged by using the extension name, although this is not
178required.
179
180Example: the overlay-osc extension registers its Perl OSC like this:
181
182 #:META:OSC_PERL:overlay:man overlay-osc
138 183
139=back 184=back
140 185
141=head2 Hooks 186=head2 Hooks
142 187
150hooks returns true, then the event counts as being I<consumed>, and the 195hooks returns true, then the event counts as being I<consumed>, and the
151relevant action might not be carried out by the C++ code. 196relevant action might not be carried out by the C++ code.
152 197
153I<< When in doubt, return a false value (preferably C<()>). >> 198I<< When in doubt, return a false value (preferably C<()>). >>
154 199
155=over 4 200=over
201
202=item on_attach $term
203
204Called when an extension package is attached to a running terminal
205instance. Must return true in all cases, and runs with the same
206limitations as C<on_init>.
207
208Unlike C<on_init> or C<on_start>, this is called when the extension is
209attached to a terminal, regardless of whether the extension is loaded
210before or after the terminal is started. Extensions that need to do
211something before they work can do it in this callback, as opposed to e.g.
212C<on_init>, which might not be called.
156 213
157=item on_init $term 214=item on_init $term
158 215
159Called after a new terminal object has been initialized, but before 216Called after a new terminal object has been initialized, but before
160windows are created or the command gets run. Most methods are unsafe to 217windows are created or the command gets run. Most methods are unsafe to
242 299
243C<on_osc_seq_perl> should be used for new behaviour. 300C<on_osc_seq_perl> should be used for new behaviour.
244 301
245=item on_osc_seq_perl $term, $args, $resp 302=item on_osc_seq_perl $term, $args, $resp
246 303
247Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 304Called whenever the B<ESC ] 777 ; prefix ; string ST> command sequence
248operating system command) is processed. Cursor position and other state 305(OSC = operating system command) is processed. Cursor position and other
249information is up-to-date when this happens. For interoperability, the 306state information is up-to-date when this happens. For interoperability,
250string should start with the extension name (sans -osc) and a semicolon, 307the argument should start with the extension name (sans -osc) or some
251to distinguish it from commands for other extensions, and this might be 308other suitable prefix, and a semicolon, to distinguish it from commands
252enforced in the future. 309for other extensions.
253 310
254For example, C<overlay-osc> uses this: 311For example, C<overlay-osc> uses this:
255 312
256 sub on_osc_seq_perl { 313 sub on_osc_seq_perl {
257 my ($self, $osc, $resp) = @_; 314 my ($self, $osc, $resp) = @_;
402=cut 459=cut
403 460
404package urxvt; 461package urxvt;
405 462
406use utf8; 463use utf8;
407use strict 'vars'; 464use strict qw(vars subs);
408use Carp (); 465use Carp ();
409use Scalar::Util (); 466use Scalar::Util ();
410use List::Util (); 467use List::Util ();
411 468
412our $VERSION = 1; 469our $VERSION = 1;
424 481
425our $NOCHAR = chr 0xffff; 482our $NOCHAR = chr 0xffff;
426 483
427=head2 Variables in the C<urxvt> Package 484=head2 Variables in the C<urxvt> Package
428 485
429=over 4 486=over
430 487
431=item $urxvt::LIBDIR 488=item $urxvt::LIBDIR
432 489
433The rxvt-unicode library directory, where, among other things, the perl 490The rxvt-unicode library directory, where, among other things, the perl
434modules and scripts are stored. 491modules and scripts are stored.
464 521
465=back 522=back
466 523
467=head2 Functions in the C<urxvt> Package 524=head2 Functions in the C<urxvt> Package
468 525
469=over 4 526=over
470 527
471=item urxvt::fatal $errormessage 528=item urxvt::fatal $errormessage
472 529
473Fatally aborts execution with the given error message (which should 530Fatally aborts execution with the given error message (which should
474include a trailing newline). Avoid at all costs! The only time this 531include a trailing newline). Avoid at all costs! The only time this
519CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, 576CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
520SelectionNotify, ColormapNotify, ClientMessage, MappingNotify 577SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
521 578
522Various constants for use in X calls and event processing. 579Various constants for use in X calls and event processing.
523 580
581=item urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo, PrivMode_relOrigin,
582PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP,
583PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys,
584PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11,
585PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress,
586PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
587PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8,
588PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report,
589PrivMode_Default
590
591Constants for checking DEC private modes.
592
524=back 593=back
525 594
526=head2 RENDITION 595=head2 RENDITION
527 596
528Rendition bitsets contain information about colour, font, font styles and 597Rendition bitsets contain information about colour, font, font styles and
531The following "macros" deal with changes in rendition sets. You should 600The following "macros" deal with changes in rendition sets. You should
532never just create a bitset, you should always modify an existing one, 601never just create a bitset, you should always modify an existing one,
533as they contain important information required for correct operation of 602as they contain important information required for correct operation of
534rxvt-unicode. 603rxvt-unicode.
535 604
536=over 4 605=over
537 606
538=item $rend = urxvt::DEFAULT_RSTYLE 607=item $rend = urxvt::DEFAULT_RSTYLE
539 608
540Returns the default rendition, as used when the terminal is starting up or 609Returns the default rendition, as used when the terminal is starting up or
541being reset. Useful as a base to start when creating renditions. 610being reset. Useful as a base to start when creating renditions.
595sub parse_resource { 664sub parse_resource {
596 my ($term, $name, $isarg, $longopt, $flag, $value) = @_; 665 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
597 666
598 $term->scan_extensions; 667 $term->scan_extensions;
599 668
669 # iterating over all resources has quadratic time overhead
670 # overall, maybe this could be optimised?
600 my $r = $term->{meta}{resource}; 671 my $r = $term->{meta}{resource};
601 keys %$r; # reset iterator 672 keys %$r; # reset iterator
602 while (my ($k, $v) = each %$r) { 673 while (my ($k, $v) = each %$r) {
603 my $pattern = $k; 674 my $pattern = $k;
604 $pattern =~ y/./-/ if $isarg; 675 $pattern =~ y/./-/ if $isarg;
611 if ($pattern eq $prefix) { 682 if ($pattern eq $prefix) {
612 $name = "$urxvt::RESCLASS.$k$suffix"; 683 $name = "$urxvt::RESCLASS.$k$suffix";
613 684
614 push @{ $term->{perl_ext_3} }, $v->[0]; 685 push @{ $term->{perl_ext_3} }, $v->[0];
615 686
687 return 1 unless $isarg;
688
616 if ($v->[1] eq "boolean") { 689 if ($v->[1] eq "boolean") {
617 $term->put_option_db ($name, $flag ? "true" : "false"); 690 $term->put_option_db ($name, $flag ? "true" : "false");
618 return 1; 691 return 1;
619 } else { 692 } else {
620 $term->put_option_db ($name, $value); 693 $term->put_option_db ($name, $value);
652 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type; 725 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type;
653 } 726 }
654 } 727 }
655} 728}
656 729
657my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 730my $verbosity = $ENV{URXVT_PERL_VERBOSITY} // 2;
658 731
659sub verbose { 732sub verbose {
660 my ($level, $msg) = @_; 733 my ($level, $msg) = @_;
661 warn "$msg\n" if $level <= $verbosity; 734 warn "$msg\n" if $level <= $verbosity;
662} 735}
679 752
680 open my $fh, "<:raw", $path 753 open my $fh, "<:raw", $path
681 or die "$path: $!"; 754 or die "$path: $!";
682 755
683 my $source = 756 my $source =
684 "package $pkg; use strict 'vars'; use utf8; no warnings 'utf8';\n" 757 "package $pkg; use strict qw(vars subs); use utf8; no warnings 'utf8';\n"
685 . "#line 1 \"$path\"\n{\n" 758 . "#line 1 \"$path\"\n{\n"
686 . (do { local $/; <$fh> }) 759 . (do { local $/; <$fh> })
687 . "\n};\n1"; 760 . "\n};\n1";
688 761
689 eval $source 762 eval $source
699sub invoke { 772sub invoke {
700 local $TERM = shift; 773 local $TERM = shift;
701 my $htype = shift; 774 my $htype = shift;
702 775
703 if ($htype == HOOK_INIT) { 776 if ($htype == HOOK_INIT) {
704 my @dirs = $TERM->perl_libdirs;
705
706 $TERM->scan_extensions; 777 $TERM->scan_extensions;
707 778
708 my %ext_arg; 779 my %ext_arg;
709 780
710 { 781 {
715 @TERM_EXT = (); 786 @TERM_EXT = ();
716 $TERM->register_package ($_) for @pkg; 787 $TERM->register_package ($_) for @pkg;
717 } 788 }
718 789
719 for ( 790 for (
791 @{ delete $TERM->{perl_ext_3} },
720 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2), 792 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
721 @{ delete $TERM->{perl_ext_3} }
722 ) { 793 ) {
723 if ($_ eq "default") { 794 if ($_ eq "default") {
724 795
725 $ext_arg{$_} = [] 796 $ext_arg{$_} = []
726 for
727 qw(selection option-popup selection-popup readline), 797 for qw(selection option-popup selection-popup readline searchable-scrollback confirm-paste);
728 map $_->[0], values %{ $TERM->{meta}{binding} };
729 798
730 for ($TERM->_keysym_resources) { 799 for ($TERM->_keysym_resources) {
731 next if /^(?:string|command|builtin|builtin-string|perl)/; 800 next if /^(?:string|command|builtin|builtin-string|perl)/;
732 next unless /^([A-Za-z0-9_\-]+):/; 801 next unless /^([A-Za-z0-9_\-]+):/;
733 802
734 my $ext = $1; 803 my $ext = $1;
735 804
736 $ext_arg{$ext} = []; 805 $ext_arg{$ext} = [];
737 } 806 }
738 807
739 } elsif (/^-(.*)$/) { 808 } elsif (/^-(.*)$/) { # remove from set
740 delete $ext_arg{$1}; 809 delete $ext_arg{$1};
741 810
742 } elsif (/^([^<]+)<(.*)>$/) { 811 } elsif (/^\/(.*)$/) { # prohibit loading
812 undef $TERM->{ext_prohibit}{$1};
813
814 } elsif (/^([^<]+)(?:<(.*)>)?$/) { # add to set, clear prohibit status
815 delete $TERM->{ext_prohibit}{$1};
743 push @{ $ext_arg{$1} }, $2; 816 push @{ $ext_arg{$1} }, defined $2 ? $2 : ();
744 817
745 } else { 818 } else {
746 $ext_arg{$_} ||= []; 819 verbose 2, "cannot parse extension specification '$_', ignoring.";
747 } 820 }
748 } 821 }
749 822
750 # now register default key bindings 823 $TERM->set_should_invoke (HOOK_OSC_SEQ , +1) if $TERM->{meta}{autoload_osc};
824 $TERM->set_should_invoke (HOOK_OSC_SEQ_PERL, +1) if $TERM->{meta}{autoload_osc_perl};
825
751 for my $ext (sort keys %ext_arg) { 826 for my $ext (sort keys %ext_arg) {
752 while (my ($k, $v) = each %{ $TERM->{meta}{ext}{$ext}{binding} }) { 827 my $path = $TERM->extension_path ($ext);
753 $TERM->bind_action ($k, "$v->[0]:$v->[1]"); 828
829 if (defined $path) {
830 $TERM->autoload_extension ($ext, $ext_arg{$ext});
831 } else {
832 verbose 2, "perl extension '$ext' not found in perl library search path";
754 } 833 }
755 } 834 }
756 835
757 for my $ext (sort keys %ext_arg) {
758 my @files = grep -f $_, map "$_/$ext", @dirs;
759
760 if (@files) {
761 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
762 } else {
763 warn "perl extension '$ext' not found in perl library search path\n";
764 }
765 }
766
767 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval"); 836 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
768 warn $@ if $@; 837 warn $@ if $@;
838 }
839
840 if ($htype == HOOK_OSC_SEQ) {
841 if (my $exts = delete $TERM->{meta}{autoload_osc}{$_[0]}) {
842 $TERM->autoload_extension ($_->[0]) for @$exts;
843 }
844 } elsif ($htype == HOOK_OSC_SEQ_PERL) {
845 if ($_[0] =~ /^([^;]+)/ and (my $exts = delete $TERM->{meta}{autoload_osc_perl}{$1})) {
846 $TERM->autoload_extension ($_->[0]) for @$exts;
847 }
769 } 848 }
770 849
771 $retval = undef; 850 $retval = undef;
772 851
773 if (my $cb = $TERM->{_hook}[$htype]) { 852 if (my $cb = $TERM->{_hook}[$htype]) {
853 932
854The methods (And data members) documented below can be called on extension 933The methods (And data members) documented below can be called on extension
855objects, in addition to call methods documented for the <urxvt::term> 934objects, in addition to call methods documented for the <urxvt::term>
856class. 935class.
857 936
858=over 4 937=over
859 938
860=item $urxvt_term = $self->{term} 939=item $urxvt_term = $self->{term}
861 940
862Returns the C<urxvt::term> object associated with this instance of the 941Returns the C<urxvt::term> object associated with this instance of the
863extension. This member I<must not> be changed in any way. 942extension. This member I<must not> be changed in any way.
981 } 1060 }
982 1061
983 bless \%disable, "urxvt::extension::on_disable" 1062 bless \%disable, "urxvt::extension::on_disable"
984} 1063}
985 1064
1065=item $self->bind_action ($hotkey, $action)
1066
986=item $self->x_resource ($pattern) 1067=item $self->x_resource ($pattern)
987 1068
988=item $self->x_resource_boolean ($pattern) 1069=item $self->x_resource_boolean ($pattern)
989 1070
990These methods support an additional C<%> prefix when called on an 1071These methods support an additional C<%> prefix for C<$action> or
991extension object - see the description of these methods in the 1072C<$pattern> when called on an extension object, compared to the
1073C<urxvt::term> methods of the same name - see the description of these
992C<urxvt::term> class for details. 1074methods in the C<urxvt::term> class for details.
993 1075
994=cut 1076=cut
1077
1078sub bind_action {
1079 my ($self, $hotkey, $action) = @_;
1080 $action =~ s/^%:/$_[0]{_name}:/;
1081 $self->{term}->bind_action ($hotkey, $action)
1082}
995 1083
996sub x_resource { 1084sub x_resource {
997 my ($self, $name) = @_; 1085 my ($self, $name) = @_;
998 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 1086 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
999 $self->{term}->x_resource ($name) 1087 $self->{term}->x_resource ($name)
1095 1183
1096package urxvt::term; 1184package urxvt::term;
1097 1185
1098=head2 The C<urxvt::term> Class 1186=head2 The C<urxvt::term> Class
1099 1187
1100=over 4 1188=over
1101 1189
1102=cut 1190=cut
1103 1191
1104# find on_xxx subs in the package and register them 1192# find on_xxx subs in the package and register them
1105# as hooks 1193# as hooks
1106sub register_package { 1194sub register_package {
1107 my ($self, $pkg, $argv) = @_; 1195 my ($self, $pkg, $argv) = @_;
1196
1197 return if $self->{_pkg}{$pkg};
1108 1198
1109 no strict 'refs'; 1199 no strict 'refs';
1110 1200
1111 urxvt::verbose 6, "register package $pkg to $self"; 1201 urxvt::verbose 6, "register package $pkg to $self";
1112 1202
1124 for my $name (@HOOKNAME) { 1214 for my $name (@HOOKNAME) {
1125 if (my $ref = $pkg->can ("on_" . lc $name)) { 1215 if (my $ref = $pkg->can ("on_" . lc $name)) {
1126 $proxy->enable ($name => $ref); 1216 $proxy->enable ($name => $ref);
1127 } 1217 }
1128 } 1218 }
1219
1220 if (my $attach_hook = $pkg->can ("on_attach")) {
1221 $attach_hook->($proxy)
1222 or urxvt::verbose 1, "$pkg->on_attach returned false, extension failed to attach";
1223 }
1224}
1225
1226# map extension name to filesystem path
1227sub extension_path {
1228 (grep -f $_, map "$_/$_[1]", $_[0]->perl_libdirs)[0]
1229}
1230
1231# load an extension by name
1232sub load_extension_file {
1233 my ($self, $path, $argv) = @_;
1234
1235 $self->register_package (urxvt::extension_package $path, $argv);
1236}
1237
1238# autoload an extension unless loading it is prohibited
1239sub autoload_extension {
1240 my ($self, $name, $argv) = @_;
1241
1242 return if exists $self->{ext_prohibit}{$name};
1243
1244 my $path = $self->extension_path ($name)
1245 // return urxvt::verbose 2, "perl extension '$name' not found in perl library search path (during autoload)";
1246
1247 $self->load_extension_file ($path, $argv);
1129} 1248}
1130 1249
1131sub perl_libdirs { 1250sub perl_libdirs {
1132 map { split /:/ } 1251 map { split /:/ }
1133 $_[0]->resource ("perl_lib"), 1252 $_[0]->resource ("perl_lib"),
1140sub scan_extensions { 1259sub scan_extensions {
1141 my ($self) = @_; 1260 my ($self) = @_;
1142 1261
1143 return if exists $self->{meta}; 1262 return if exists $self->{meta};
1144 1263
1145 my @libdirs = perl_libdirs $self; 1264 my @urxvtdirs = perl_libdirs $self;
1265# my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC;
1146 1266
1147# return if $self->{meta_libdirs} eq join "\x00", @libdirs;#d#
1148
1149# $self->{meta_libdirs} = join "\x00", @libdirs;#d#
1150 $self->{meta} = \my %meta; 1267 $self->{meta} = \my %allmeta;
1151 1268
1152 # first gather extensions 1269 # first gather extensions
1153 for my $dir (reverse @libdirs) { 1270
1271 my $gather = sub {
1272 my ($dir, $core) = @_;
1273
1154 opendir my $fh, $dir 1274 opendir my $fh, $dir
1155 or next; 1275 or return;
1276
1156 for my $ext (readdir $fh) { 1277 for my $ext (readdir $fh) {
1157 $ext !~ /^\./ 1278 $ext !~ /^\./
1158 and open my $fh, "<", "$dir/$ext"
1159 or next; 1279 or next;
1160 1280
1281 open my $fh, "<", "$dir/$ext"
1282 or next;
1283
1284 -f $fh
1285 or next;
1286
1287 $ext =~ s/\.uext$// or $core
1288 or next;
1289
1161 my %ext = (dir => $dir); 1290 my %meta = (dir => $dir);
1162 1291
1163 while (<$fh>) { 1292 while (<$fh>) {
1164 if (/^#:META:(?:X_)?RESOURCE:(.*)/) { 1293 if (/^#:META:(?:X_)?RESOURCE:(.*)/) {
1165 my ($pattern, $type, $desc) = split /:/, $1; 1294 my ($pattern, $type, $desc) = split /:/, $1;
1166 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name 1295 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1167 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1296 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1168 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n"; 1297 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1169 } else { 1298 } else {
1170 $ext{resource}{$pattern} = [$ext, $type, $desc]; 1299 $meta{resource}{$pattern} = [$ext, $type, $desc];
1171 } 1300 }
1301
1172 } elsif (/^#:META:BINDING:(.*)/) { 1302 } elsif (/^#:META:OSC:([0-9]+):(.*)/) {
1173 my ($keysym, $action) = split /:/, $1; 1303 push @{$allmeta{autoload_osc}{$1}}, [$ext, $2];
1174 $ext{binding}{$keysym} = [$ext, $action]; 1304
1305 } elsif (/^#:META:OSC_PERL:([^:]+):(.*)/) {
1306 push @{$allmeta{autoload_osc_perl}{$1}}, [$ext, $2];
1307
1175 } elsif (/^\s*(?:#|$)/) { 1308 } elsif (/^\s*(?:#|$)/) {
1176 # skip other comments and empty lines 1309 # skip other comments and empty lines
1310
1177 } else { 1311 } else {
1178 last; # stop parsing on first non-empty non-comment line 1312 last; # stop parsing on first non-empty non-comment line
1179 } 1313 }
1180 } 1314 }
1181 1315
1182 $meta{ext}{$ext} = \%ext; 1316 $allmeta{ext}{$ext} = \%meta;
1183 } 1317 }
1184 } 1318 };
1185 1319
1320# $gather->($_, 0) for @cpandirs;
1321 $gather->($_, 1) for @urxvtdirs;
1322
1186 # and now merge resources and bindings 1323 # and now merge resources
1324
1325 $allmeta{resource} = \my %resource;
1326
1187 while (my ($k, $v) = each %{ $meta{ext} }) { 1327 while (my ($k, $v) = each %{ $allmeta{ext} }) {
1188 #TODO: should check for extensions overriding each other 1328 #TODO: should check for extensions overriding each other
1189 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} }); 1329 %resource = (%resource, %{ $v->{resource} });
1190 %{ $meta{binding} } = (%{ $meta{binding} }, %{ $v->{binding} });
1191 } 1330 }
1192} 1331}
1193 1332
1194=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1333=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1195 1334
1225Works like the combination of the C<fork>/C<exec> builtins, which executes 1364Works like the combination of the C<fork>/C<exec> builtins, which executes
1226("starts") programs in the background. This function takes care of setting 1365("starts") programs in the background. This function takes care of setting
1227the user environment before exec'ing the command (e.g. C<PATH>) and should 1366the user environment before exec'ing the command (e.g. C<PATH>) and should
1228be preferred over explicit calls to C<exec> or C<system>. 1367be preferred over explicit calls to C<exec> or C<system>.
1229 1368
1369It also sets the C<URXVT_EXT_WINDOWID> environment variable to the window
1370ID of the terminal (C<< $self->parent >>), similar to the C<WINDOWID>
1371variable set for the process spawned inside the terminal.
1372
1230Returns the pid of the subprocess or C<undef> on error. 1373Returns the pid of the subprocess or C<undef> on error.
1231 1374
1232=cut 1375=cut
1233 1376
1234sub exec_async { 1377sub exec_async {
1237 my $pid = fork; 1380 my $pid = fork;
1238 1381
1239 return $pid 1382 return $pid
1240 if !defined $pid or $pid; 1383 if !defined $pid or $pid;
1241 1384
1385 %ENV = (
1242 %ENV = %{ $self->env }; 1386 %{ $self->env },
1387 URXVT_EXT_WINDOWID => $self->parent,
1388 );
1243 1389
1244 exec @_; 1390 exec @_;
1245 urxvt::_exit 255; 1391 urxvt::_exit 255;
1246} 1392}
1247 1393
1258 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell 1404 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1259 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs 1405 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1260 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right 1406 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1261 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen 1407 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1262 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords 1408 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1263 urgentOnBell utmpInhibit visualBell 1409 urgentOnBell utmpInhibit visualBell disablePasteBrackets
1264 1410
1265=item $value = $term->resource ($name[, $newval]) 1411=item $value = $term->resource ($name[, $newval])
1266 1412
1267Returns the current resource value associated with a given name and 1413Returns the current resource value associated with a given name and
1268optionally sets a new value. Setting values is most useful in the C<init> 1414optionally sets a new value. Setting values is most useful in the C<init>
1294 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1440 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1295 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1441 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1296 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1442 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1297 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll 1443 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1298 term_name title transient_for transparent tripleclickwords urgentOnBell 1444 term_name title transient_for transparent tripleclickwords urgentOnBell
1299 utmpInhibit visualBell 1445 utmpInhibit visualBell rewrapMode disablePasteBrackets
1300 1446
1301=cut 1447=cut
1302 1448
1303sub resource($$;$) { 1449sub resource($$;$) {
1304 my ($self, $name) = (shift, shift); 1450 my ($self, $name) = (shift, shift);
1341 my $res = &x_resource; 1487 my $res = &x_resource;
1342 1488
1343 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1489 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1344} 1490}
1345 1491
1492=item $action = $term->lookup_keysym ($keysym, $state)
1493
1494Returns the action bound to key combination C<($keysym, $state)>,
1495if a binding for it exists, and C<undef> otherwise.
1496
1346=item $success = $term->bind_action ($key, $octets) 1497=item $success = $term->bind_action ($key, $action)
1347 1498
1348Adds a key binding exactly as specified via a C<keysym> resource. See the 1499Adds a key binding exactly as specified via a C<keysym> resource. See the
1349C<keysym> resource in the urxvt(1) manpage. 1500C<keysym> resource in the urxvt(1) manpage.
1501
1502To add default bindings for actions, an extension should call C<<
1503->bind_action >> in its C<init> hook for every such binding. Doing it
1504in the C<init> hook allows users to override or remove the binding
1505again.
1506
1507Example: the C<searchable-scrollback> by default binds itself
1508on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1509$term->bind_action >>.
1510
1511 sub init {
1512 my ($self) = @_;
1513
1514 $self->bind_action ("M-s" => "%:start");
1515 }
1350 1516
1351=item $rend = $term->rstyle ([$new_rstyle]) 1517=item $rend = $term->rstyle ([$new_rstyle])
1352 1518
1353Return and optionally change the current rendition. Text that is output by 1519Return and optionally change the current rendition. Text that is output by
1354the terminal application will use this style. 1520the terminal application will use this style.
1431This method returns an urxvt::overlay object. The overlay will be visible 1597This method returns an urxvt::overlay object. The overlay will be visible
1432as long as the perl object is referenced. 1598as long as the perl object is referenced.
1433 1599
1434The methods currently supported on C<urxvt::overlay> objects are: 1600The methods currently supported on C<urxvt::overlay> objects are:
1435 1601
1436=over 4 1602=over
1437 1603
1438=item $overlay->set ($x, $y, $text[, $rend]) 1604=item $overlay->set ($x, $y, $text[, $rend])
1439 1605
1440Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1606Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1441text in rxvt-unicode's special encoding and an array of rendition values 1607text in rxvt-unicode's special encoding and an array of rendition values
1485Returns the number of screen-cells this string would need. Correctly 1651Returns the number of screen-cells this string would need. Correctly
1486accounts for wide and combining characters. 1652accounts for wide and combining characters.
1487 1653
1488=item $octets = $term->locale_encode ($string) 1654=item $octets = $term->locale_encode ($string)
1489 1655
1490Convert the given text string into the corresponding locale encoding. 1656Convert the given text string into the corresponding locale
1657encoding. Returns C<undef> if C<$string> is C<undef>.
1491 1658
1492=item $string = $term->locale_decode ($octets) 1659=item $string = $term->locale_decode ($octets)
1493 1660
1494Convert the given locale-encoded octets into a perl string. 1661Convert the given locale-encoded octets into a perl string. Returns
1662C<undef> if C<$octets> is C<undef>.
1495 1663
1496=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) 1664=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1497 1665
1498XORs the rendition values in the given span with the provided value 1666XORs the rendition values in the given span with the provided value
1499(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in 1667(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1592 1760
1593=item $term->key_release ($state, $keycode[, $time]) 1761=item $term->key_release ($state, $keycode[, $time])
1594 1762
1595Deliver various fake events to to terminal. 1763Deliver various fake events to to terminal.
1596 1764
1597=item $window_width = $term->width 1765=item $window_width = $term->width ([$new_value])
1598 1766
1599=item $window_height = $term->height 1767=item $window_height = $term->height ([$new_value])
1600 1768
1601=item $font_width = $term->fwidth 1769=item $font_width = $term->fwidth ([$new_value])
1602 1770
1603=item $font_height = $term->fheight 1771=item $font_height = $term->fheight ([$new_value])
1604 1772
1605=item $font_ascent = $term->fbase 1773=item $font_ascent = $term->fbase ([$new_value])
1606 1774
1607=item $terminal_rows = $term->nrow 1775=item $terminal_rows = $term->nrow ([$new_value])
1608 1776
1609=item $terminal_columns = $term->ncol 1777=item $terminal_columns = $term->ncol ([$new_value])
1610 1778
1611=item $has_focus = $term->focus 1779=item $has_focus = $term->focus ([$new_value])
1612 1780
1613=item $is_mapped = $term->mapped 1781=item $is_mapped = $term->mapped ([$new_value])
1614 1782
1615=item $max_scrollback = $term->saveLines 1783=item $max_scrollback = $term->saveLines ([$new_value])
1616 1784
1617=item $nrow_plus_saveLines = $term->total_rows 1785=item $nrow_plus_saveLines = $term->total_rows ([$new_value])
1618 1786
1619=item $topmost_scrollback_row = $term->top_row 1787=item $topmost_scrollback_row = $term->top_row ([$new_value])
1620 1788
1621Return various integers describing terminal characteristics. 1789Return various integers describing terminal characteristics. If an
1790argument is given, changes the value and returns the previous one.
1622 1791
1623=item $x_display = $term->display_id 1792=item $x_display = $term->display_id
1624 1793
1625Return the DISPLAY used by rxvt-unicode. 1794Return the DISPLAY used by rxvt-unicode.
1626 1795
1663 1832
1664=item $cursor_is_hidden = $term->hidden_cursor 1833=item $cursor_is_hidden = $term->hidden_cursor
1665 1834
1666Returns whether the cursor is currently hidden or not. 1835Returns whether the cursor is currently hidden or not.
1667 1836
1837=item $priv_modes = $term->priv_modes
1838
1839Returns a bitset with the state of DEC private modes.
1840
1841Example:
1842
1843 if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
1844 # mouse reporting is turned on
1845 }
1846
1668=item $view_start = $term->view_start ([$newvalue]) 1847=item $view_start = $term->view_start ([$newvalue])
1669 1848
1670Returns the row number of the topmost displayed line. Maximum value is 1849Returns the row number of the topmost displayed line and changes it,
1671C<0>, which displays the normal terminal contents. Lower values scroll 1850if an argument is given. Values greater than or equal to C<0> display
1672this many lines into the scrollback buffer. 1851the terminal contents. Lower values scroll this many lines into the
1852scrollback buffer.
1673 1853
1674=item $term->want_refresh 1854=item $term->want_refresh
1675 1855
1676Requests a screen refresh. At the next opportunity, rxvt-unicode will 1856Requests a screen refresh. At the next opportunity, rxvt-unicode will
1677compare the on-screen display with its stored representation. If they 1857compare the on-screen display with its stored representation. If they
1678differ, it redraws the differences. 1858differ, it redraws the differences.
1679 1859
1680Used after changing terminal contents to display them. 1860Used after changing terminal contents to display them.
1861
1862=item $term->refresh_check
1863
1864Checks if a refresh has been requested and, if so, schedules one.
1681 1865
1682=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1866=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1683 1867
1684Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >> 1868Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1685is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost 1869is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1731 1915
1732Create and return a new C<urxvt::line> object that stores information 1916Create and return a new C<urxvt::line> object that stores information
1733about the logical line that row C<$row_number> is part of. It supports the 1917about the logical line that row C<$row_number> is part of. It supports the
1734following methods: 1918following methods:
1735 1919
1736=over 4 1920=over
1737 1921
1738=item $text = $line->t ([$new_text]) 1922=item $text = $line->t ([$new_text])
1739 1923
1740Returns or replaces the full text of the line, similar to C<ROW_t> 1924Returns or replaces the full text of the line, similar to C<ROW_t>
1741 1925
1837 $offset / $self->{ncol} + $self->{beg}, 2021 $offset / $self->{ncol} + $self->{beg},
1838 $offset % $self->{ncol} 2022 $offset % $self->{ncol}
1839 ) 2023 )
1840} 2024}
1841 2025
1842=item $text = $term->special_encode $string 2026=item $text = $term->special_encode ($string)
1843 2027
1844Converts a perl string into the special encoding used by rxvt-unicode, 2028Converts a perl string into the special encoding used by rxvt-unicode,
1845where one character corresponds to one screen cell. See 2029where one character corresponds to one screen cell. See
1846C<< $term->ROW_t >> for details. 2030C<< $term->ROW_t >> for details.
1847 2031
1848=item $string = $term->special_decode $text 2032=item $string = $term->special_decode ($text)
1849 2033
1850Converts rxvt-unicodes text representation into a perl string. See 2034Converts rxvt-unicode's text representation into a perl string. See
1851C<< $term->ROW_t >> for details. 2035C<< $term->ROW_t >> for details.
1852 2036
1853=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 2037=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1854 2038
1855=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 2039=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1921 2105
1922package urxvt::popup; 2106package urxvt::popup;
1923 2107
1924=head2 The C<urxvt::popup> Class 2108=head2 The C<urxvt::popup> Class
1925 2109
1926=over 4 2110=over
1927 2111
1928=cut 2112=cut
1929 2113
1930sub add_item { 2114sub add_item {
1931 my ($self, $item) = @_; 2115 my ($self, $item) = @_;
2067 ->cb (sub { 2251 ->cb (sub {
2068 $term->{overlay}->set (0, 0, 2252 $term->{overlay}->set (0, 0,
2069 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2253 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
2070 }); 2254 });
2071 2255
2072=over 4 2256=over
2073 2257
2074=item $timer = new urxvt::timer 2258=item $timer = new urxvt::timer
2075 2259
2076Create a new timer object in started state. It is scheduled to fire 2260Create a new timer object in started state. It is scheduled to fire
2077immediately. 2261immediately.
2126 sysread $term->{socket}, my $buf, 8192 2310 sysread $term->{socket}, my $buf, 8192
2127 or end-of-file; 2311 or end-of-file;
2128 }); 2312 });
2129 2313
2130 2314
2131=over 4 2315=over
2132 2316
2133=item $iow = new urxvt::iow 2317=item $iow = new urxvt::iow
2134 2318
2135Create a new io watcher object in stopped state. 2319Create a new io watcher object in stopped state.
2136 2320
2163 2347
2164This class implements idle watchers, that get called automatically when 2348This class implements idle watchers, that get called automatically when
2165the process is idle. They should return as fast as possible, after doing 2349the process is idle. They should return as fast as possible, after doing
2166some useful work. 2350some useful work.
2167 2351
2168=over 4 2352=over
2169 2353
2170=item $iw = new urxvt::iw 2354=item $iw = new urxvt::iw
2171 2355
2172Create a new idle watcher object in stopped state. 2356Create a new idle watcher object in stopped state.
2173 2357
2198 ->cb (sub { 2382 ->cb (sub {
2199 my ($pw, $exit_status) = @_; 2383 my ($pw, $exit_status) = @_;
2200 ... 2384 ...
2201 }); 2385 });
2202 2386
2203=over 4 2387=over
2204 2388
2205=item $pw = new urxvt::pw 2389=item $pw = new urxvt::pw
2206 2390
2207Create a new process watcher in stopped state. 2391Create a new process watcher in stopped state.
2208 2392
2225=head2 URXVT_PERL_VERBOSITY 2409=head2 URXVT_PERL_VERBOSITY
2226 2410
2227This variable controls the verbosity level of the perl extension. Higher 2411This variable controls the verbosity level of the perl extension. Higher
2228numbers indicate more verbose output. 2412numbers indicate more verbose output.
2229 2413
2230=over 4 2414=over
2231 2415
2232=item == 0 - fatal messages 2416=item == 0 - fatal messages only
2417
2418=item >= 2 - general warnings (default level)
2233 2419
2234=item >= 3 - script loading and management 2420=item >= 3 - script loading and management
2235 2421
2236=item >=10 - all called hooks 2422=item >=10 - all called hooks
2237 2423

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines