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.249 by root, Fri Dec 26 21:26:37 2014 UTC vs.
Revision 1.271 by root, Fri Dec 9 05:06:46 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.
… …
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 meta 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
123Currently, it recxognises only one such comment: 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.
124 127
125=over 4 128=over
126 129
127=item #:META:RESOURCE:name:type:desc 130=item #:META:RESOURCE:name:type:desc
128 131
129The RESOURCE comment defines a resource used by the extension, where 132The RESOURCE comment defines a resource used by the extension, where
130C<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>
131or C<string>, and C<desc> is the resource description. 134or C<string>, and C<desc> is the resource description.
132 135
136The extension will be autoloaded when this resource is specified or used
137as a command line parameter.
138
139Example: matcher provides the C<matcher.launcher> resource by having this
140comment:
141
142 #:META:RESOURCE:%.launcher:string:default launcher command
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
183
133=back 184=back
134 185
135=head2 Hooks 186=head2 Hooks
136 187
137The following subroutines can be declared in extension files, and will be 188The following subroutines can be declared in extension files, and will be
… …
144hooks 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
145relevant action might not be carried out by the C++ code. 196relevant action might not be carried out by the C++ code.
146 197
147I<< When in doubt, return a false value (preferably C<()>). >> 198I<< When in doubt, return a false value (preferably C<()>). >>
148 199
149=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.
150 213
151=item on_init $term 214=item on_init $term
152 215
153Called after a new terminal object has been initialized, but before 216Called after a new terminal object has been initialized, but before
154windows 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
… …
236 299
237C<on_osc_seq_perl> should be used for new behaviour. 300C<on_osc_seq_perl> should be used for new behaviour.
238 301
239=item on_osc_seq_perl $term, $args, $resp 302=item on_osc_seq_perl $term, $args, $resp
240 303
241Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 304Called whenever the B<ESC ] 777 ; prefix ; string ST> command sequence
242operating system command) is processed. Cursor position and other state 305(OSC = operating system command) is processed. Cursor position and other
243information is up-to-date when this happens. For interoperability, the 306state information is up-to-date when this happens. For interoperability,
244string should start with the extension name (sans -osc) and a semicolon, 307the argument should start with the extension name (sans -osc) or some
245to distinguish it from commands for other extensions, and this might be 308other suitable prefix, and a semicolon, to distinguish it from commands
246enforced in the future. 309for other extensions.
247 310
248For example, C<overlay-osc> uses this: 311For example, C<overlay-osc> uses this:
249 312
250 sub on_osc_seq_perl { 313 sub on_osc_seq_perl {
251 my ($self, $osc, $resp) = @_; 314 my ($self, $osc, $resp) = @_;
… …
396=cut 459=cut
397 460
398package urxvt; 461package urxvt;
399 462
400use utf8; 463use utf8;
401use strict 'vars'; 464use strict qw(vars subs);
402use Carp (); 465use Carp ();
403use Scalar::Util (); 466use Scalar::Util ();
404use List::Util (); 467use List::Util ();
405 468
406our $VERSION = 1; 469our $VERSION = 1;
… …
418 481
419our $NOCHAR = chr 0xffff; 482our $NOCHAR = chr 0xffff;
420 483
421=head2 Variables in the C<urxvt> Package 484=head2 Variables in the C<urxvt> Package
422 485
423=over 4 486=over
424 487
425=item $urxvt::LIBDIR 488=item $urxvt::LIBDIR
426 489
427The rxvt-unicode library directory, where, among other things, the perl 490The rxvt-unicode library directory, where, among other things, the perl
428modules and scripts are stored. 491modules and scripts are stored.
… …
458 521
459=back 522=back
460 523
461=head2 Functions in the C<urxvt> Package 524=head2 Functions in the C<urxvt> Package
462 525
463=over 4 526=over
464 527
465=item urxvt::fatal $errormessage 528=item urxvt::fatal $errormessage
466 529
467Fatally aborts execution with the given error message (which should 530Fatally aborts execution with the given error message (which should
468include a trailing newline). Avoid at all costs! The only time this 531include a trailing newline). Avoid at all costs! The only time this
… …
513CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, 576CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
514SelectionNotify, ColormapNotify, ClientMessage, MappingNotify 577SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
515 578
516Various constants for use in X calls and event processing. 579Various constants for use in X calls and event processing.
517 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
518=back 593=back
519 594
520=head2 RENDITION 595=head2 RENDITION
521 596
522Rendition bitsets contain information about colour, font, font styles and 597Rendition bitsets contain information about colour, font, font styles and
… …
525The following "macros" deal with changes in rendition sets. You should 600The following "macros" deal with changes in rendition sets. You should
526never just create a bitset, you should always modify an existing one, 601never just create a bitset, you should always modify an existing one,
527as they contain important information required for correct operation of 602as they contain important information required for correct operation of
528rxvt-unicode. 603rxvt-unicode.
529 604
530=over 4 605=over
531 606
532=item $rend = urxvt::DEFAULT_RSTYLE 607=item $rend = urxvt::DEFAULT_RSTYLE
533 608
534Returns 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
535being reset. Useful as a base to start when creating renditions. 610being reset. Useful as a base to start when creating renditions.
… …
589sub parse_resource { 664sub parse_resource {
590 my ($term, $name, $isarg, $longopt, $flag, $value) = @_; 665 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
591 666
592 $term->scan_extensions; 667 $term->scan_extensions;
593 668
669 # iterating over all resources has quadratic time overhead
670 # overall, maybe this could be optimised?
594 my $r = $term->{meta}{resource}; 671 my $r = $term->{meta}{resource};
595 keys %$r; # reset iterator 672 keys %$r; # reset iterator
596 while (my ($k, $v) = each %$r) { 673 while (my ($k, $v) = each %$r) {
597 my $pattern = $k; 674 my $pattern = $k;
598 $pattern =~ y/./-/ if $isarg; 675 $pattern =~ y/./-/ if $isarg;
… …
605 if ($pattern eq $prefix) { 682 if ($pattern eq $prefix) {
606 $name = "$urxvt::RESCLASS.$k$suffix"; 683 $name = "$urxvt::RESCLASS.$k$suffix";
607 684
608 push @{ $term->{perl_ext_3} }, $v->[0]; 685 push @{ $term->{perl_ext_3} }, $v->[0];
609 686
687 return 1 unless $isarg;
688
610 if ($v->[1] eq "boolean") { 689 if ($v->[1] eq "boolean") {
611 $term->put_option_db ($name, $flag ? "true" : "false"); 690 $term->put_option_db ($name, $flag ? "true" : "false");
612 return 1; 691 return 1;
613 } else { 692 } else {
614 $term->put_option_db ($name, $value); 693 $term->put_option_db ($name, $value);
… …
646 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type; 725 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type;
647 } 726 }
648 } 727 }
649} 728}
650 729
651my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 730my $verbosity = $ENV{URXVT_PERL_VERBOSITY} // 2;
652 731
653sub verbose { 732sub verbose {
654 my ($level, $msg) = @_; 733 my ($level, $msg) = @_;
655 warn "$msg\n" if $level <= $verbosity; 734 warn "$msg\n" if $level <= $verbosity;
656} 735}
… …
673 752
674 open my $fh, "<:raw", $path 753 open my $fh, "<:raw", $path
675 or die "$path: $!"; 754 or die "$path: $!";
676 755
677 my $source = 756 my $source =
678 "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"
679 . "#line 1 \"$path\"\n{\n" 758 . "#line 1 \"$path\"\n{\n"
680 . (do { local $/; <$fh> }) 759 . (do { local $/; <$fh> })
681 . "\n};\n1"; 760 . "\n};\n1";
682 761
683 eval $source 762 eval $source
… …
693sub invoke { 772sub invoke {
694 local $TERM = shift; 773 local $TERM = shift;
695 my $htype = shift; 774 my $htype = shift;
696 775
697 if ($htype == HOOK_INIT) { 776 if ($htype == HOOK_INIT) {
698 my @dirs = $TERM->perl_libdirs;
699
700 $TERM->scan_extensions; 777 $TERM->scan_extensions;
701 778
702 my %ext_arg; 779 my %ext_arg;
703 780
704 { 781 {
… …
709 @TERM_EXT = (); 786 @TERM_EXT = ();
710 $TERM->register_package ($_) for @pkg; 787 $TERM->register_package ($_) for @pkg;
711 } 788 }
712 789
713 for ( 790 for (
791 @{ delete $TERM->{perl_ext_3} },
714 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2), 792 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
715 @{ delete $TERM->{perl_ext_3} }
716 ) { 793 ) {
717 if ($_ eq "default") { 794 if ($_ eq "default") {
718 795
719 $ext_arg{$_} = [] 796 $ext_arg{$_} = []
720 for qw(selection option-popup selection-popup readline searchable-scrollback); 797 for qw(selection option-popup selection-popup readline searchable-scrollback confirm-paste);
721 798
722 for ($TERM->_keysym_resources) { 799 for ($TERM->_keysym_resources) {
723 next if /^(?:string|command|builtin|builtin-string|perl)/; 800 next if /^(?:string|command|builtin|builtin-string|perl)/;
724 next unless /^([A-Za-z0-9_\-]+):/; 801 next unless /^([A-Za-z0-9_\-]+):/;
725 802
726 my $ext = $1; 803 my $ext = $1;
727 804
728 $ext_arg{$ext} = []; 805 $ext_arg{$ext} = [];
729 } 806 }
730 807
731 } elsif (/^-(.*)$/) { 808 } elsif (/^-(.*)$/) { # remove from set
732 delete $ext_arg{$1}; 809 delete $ext_arg{$1};
733 810
734 } 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};
735 push @{ $ext_arg{$1} }, $2; 816 push @{ $ext_arg{$1} }, defined $2 ? $2 : ();
736 817
737 } else { 818 } else {
738 $ext_arg{$_} ||= []; 819 verbose 2, "cannot parse extension specification '$_', ignoring.";
739 } 820 }
740 } 821 }
741 822
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
742 for my $ext (sort keys %ext_arg) { 826 for my $ext (sort keys %ext_arg) {
743 my @files = grep -f $_, map "$_/$ext", @dirs; 827 my $path = $TERM->extension_path ($ext);
744 828
745 if (@files) { 829 if (defined $path) {
746 $TERM->register_package (extension_package $files[0], $ext_arg{$ext}); 830 $TERM->autoload_extension ($ext, $ext_arg{$ext});
747 } else { 831 } else {
748 warn "perl extension '$ext' not found in perl library search path\n"; 832 verbose 2, "perl extension '$ext' not found in perl library search path";
749 } 833 }
750 } 834 }
751 835
752 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");
753 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 }
754 } 848 }
755 849
756 $retval = undef; 850 $retval = undef;
757 851
758 if (my $cb = $TERM->{_hook}[$htype]) { 852 if (my $cb = $TERM->{_hook}[$htype]) {
… …
838 932
839The methods (And data members) documented below can be called on extension 933The methods (And data members) documented below can be called on extension
840objects, in addition to call methods documented for the <urxvt::term> 934objects, in addition to call methods documented for the <urxvt::term>
841class. 935class.
842 936
843=over 4 937=over
844 938
845=item $urxvt_term = $self->{term} 939=item $urxvt_term = $self->{term}
846 940
847Returns the C<urxvt::term> object associated with this instance of the 941Returns the C<urxvt::term> object associated with this instance of the
848extension. This member I<must not> be changed in any way. 942extension. This member I<must not> be changed in any way.
… …
1089 1183
1090package urxvt::term; 1184package urxvt::term;
1091 1185
1092=head2 The C<urxvt::term> Class 1186=head2 The C<urxvt::term> Class
1093 1187
1094=over 4 1188=over
1095 1189
1096=cut 1190=cut
1097 1191
1098# find on_xxx subs in the package and register them 1192# find on_xxx subs in the package and register them
1099# as hooks 1193# as hooks
1100sub register_package { 1194sub register_package {
1101 my ($self, $pkg, $argv) = @_; 1195 my ($self, $pkg, $argv) = @_;
1196
1197 return if $self->{_pkg}{$pkg};
1102 1198
1103 no strict 'refs'; 1199 no strict 'refs';
1104 1200
1105 urxvt::verbose 6, "register package $pkg to $self"; 1201 urxvt::verbose 6, "register package $pkg to $self";
1106 1202
… …
1118 for my $name (@HOOKNAME) { 1214 for my $name (@HOOKNAME) {
1119 if (my $ref = $pkg->can ("on_" . lc $name)) { 1215 if (my $ref = $pkg->can ("on_" . lc $name)) {
1120 $proxy->enable ($name => $ref); 1216 $proxy->enable ($name => $ref);
1121 } 1217 }
1122 } 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);
1123} 1248}
1124 1249
1125sub perl_libdirs { 1250sub perl_libdirs {
1126 map { split /:/ } 1251 map { split /:/ }
1127 $_[0]->resource ("perl_lib"), 1252 $_[0]->resource ("perl_lib"),
… …
1135 my ($self) = @_; 1260 my ($self) = @_;
1136 1261
1137 return if exists $self->{meta}; 1262 return if exists $self->{meta};
1138 1263
1139 my @urxvtdirs = perl_libdirs $self; 1264 my @urxvtdirs = perl_libdirs $self;
1140 my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC; 1265# my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC;
1141 1266
1142 $self->{meta} = \my %meta; 1267 $self->{meta} = \my %allmeta;
1143 1268
1144 # first gather extensions 1269 # first gather extensions
1145 1270
1146 my $gather = sub { 1271 my $gather = sub {
1147 my ($dir, $core) = @_; 1272 my ($dir, $core) = @_;
… …
1160 or next; 1285 or next;
1161 1286
1162 $ext =~ s/\.uext$// or $core 1287 $ext =~ s/\.uext$// or $core
1163 or next; 1288 or next;
1164 1289
1165 my %ext = (dir => $dir); 1290 my %meta = (dir => $dir);
1166 1291
1167 while (<$fh>) { 1292 while (<$fh>) {
1168 if (/^#:META:(?:X_)?RESOURCE:(.*)/) { 1293 if (/^#:META:(?:X_)?RESOURCE:(.*)/) {
1169 my ($pattern, $type, $desc) = split /:/, $1; 1294 my ($pattern, $type, $desc) = split /:/, $1;
1170 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name 1295 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1171 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1296 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1172 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";
1173 } else { 1298 } else {
1174 $ext{resource}{$pattern} = [$ext, $type, $desc]; 1299 $meta{resource}{$pattern} = [$ext, $type, $desc];
1175 } 1300 }
1301
1302 } elsif (/^#:META:OSC:([0-9]+):(.*)/) {
1303 push @{$allmeta{autoload_osc}{$1}}, [$ext, $2];
1304
1305 } elsif (/^#:META:OSC_PERL:([^:]+):(.*)/) {
1306 push @{$allmeta{autoload_osc_perl}{$1}}, [$ext, $2];
1307
1176 } elsif (/^\s*(?:#|$)/) { 1308 } elsif (/^\s*(?:#|$)/) {
1177 # skip other comments and empty lines 1309 # skip other comments and empty lines
1310
1178 } else { 1311 } else {
1179 last; # stop parsing on first non-empty non-comment line 1312 last; # stop parsing on first non-empty non-comment line
1180 } 1313 }
1181 } 1314 }
1182 1315
1183 $meta{ext}{$ext} = \%ext; 1316 $allmeta{ext}{$ext} = \%meta;
1184 } 1317 }
1185 }; 1318 };
1186 1319
1187 $gather->($_, 0) for @cpandirs; 1320# $gather->($_, 0) for @cpandirs;
1188 $gather->($_, 1) for @urxvtdirs; 1321 $gather->($_, 1) for @urxvtdirs;
1189 1322
1190 # and now merge resources 1323 # and now merge resources
1324
1325 $allmeta{resource} = \my %resource;
1326
1191 while (my ($k, $v) = each %{ $meta{ext} }) { 1327 while (my ($k, $v) = each %{ $allmeta{ext} }) {
1192 #TODO: should check for extensions overriding each other 1328 #TODO: should check for extensions overriding each other
1193 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} }); 1329 %resource = (%resource, %{ $v->{resource} });
1194 } 1330 }
1195} 1331}
1196 1332
1197=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1333=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1198 1334
… …
1228Works 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
1229("starts") programs in the background. This function takes care of setting 1365("starts") programs in the background. This function takes care of setting
1230the 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
1231be preferred over explicit calls to C<exec> or C<system>. 1367be preferred over explicit calls to C<exec> or C<system>.
1232 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
1233Returns the pid of the subprocess or C<undef> on error. 1373Returns the pid of the subprocess or C<undef> on error.
1234 1374
1235=cut 1375=cut
1236 1376
1237sub exec_async { 1377sub exec_async {
… …
1240 my $pid = fork; 1380 my $pid = fork;
1241 1381
1242 return $pid 1382 return $pid
1243 if !defined $pid or $pid; 1383 if !defined $pid or $pid;
1244 1384
1385 %ENV = (
1245 %ENV = %{ $self->env }; 1386 %{ $self->env },
1387 URXVT_EXT_WINDOWID => $self->parent,
1388 );
1246 1389
1247 exec @_; 1390 exec @_;
1248 urxvt::_exit 255; 1391 urxvt::_exit 255;
1249} 1392}
1250 1393
… …
1261 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell 1404 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1262 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs 1405 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1263 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right 1406 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1264 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen 1407 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1265 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords 1408 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1266 urgentOnBell utmpInhibit visualBell 1409 urgentOnBell utmpInhibit visualBell disablePasteBrackets
1267 1410
1268=item $value = $term->resource ($name[, $newval]) 1411=item $value = $term->resource ($name[, $newval])
1269 1412
1270Returns the current resource value associated with a given name and 1413Returns the current resource value associated with a given name and
1271optionally 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>
… …
1297 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1440 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1298 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1441 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1299 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1442 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1300 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll 1443 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1301 term_name title transient_for transparent tripleclickwords urgentOnBell 1444 term_name title transient_for transparent tripleclickwords urgentOnBell
1302 utmpInhibit visualBell 1445 utmpInhibit visualBell rewrapMode disablePasteBrackets
1303 1446
1304=cut 1447=cut
1305 1448
1306sub resource($$;$) { 1449sub resource($$;$) {
1307 my ($self, $name) = (shift, shift); 1450 my ($self, $name) = (shift, shift);
… …
1344 my $res = &x_resource; 1487 my $res = &x_resource;
1345 1488
1346 $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
1347} 1490}
1348 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
1349=item $success = $term->bind_action ($key, $action) 1497=item $success = $term->bind_action ($key, $action)
1350 1498
1351Adds 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
1352C<keysym> resource in the urxvt(1) manpage. 1500C<keysym> resource in the urxvt(1) manpage.
1353 1501
1354To add default bindings for an extension, the extension should call C<< 1502To add default bindings for actions, an extension should call C<<
1355->bind_action >> on it's C<init> hook for every such binding. Doing it 1503->bind_action >> in its C<init> hook for every such binding. Doing it
1356in the C<init> hook allows users the override or remove the the binding 1504in the C<init> hook allows users to override or remove the binding
1357again. 1505again.
1358 1506
1359Example: the C<searchable-scrollback> by default binds itself 1507Example: the C<searchable-scrollback> by default binds itself
1360on C<Meta-s>, using C<< $self->bind_action >>, which calls C<< 1508on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1361$term->bind_action >>. 1509$term->bind_action >>.
… …
1449This method returns an urxvt::overlay object. The overlay will be visible 1597This method returns an urxvt::overlay object. The overlay will be visible
1450as long as the perl object is referenced. 1598as long as the perl object is referenced.
1451 1599
1452The methods currently supported on C<urxvt::overlay> objects are: 1600The methods currently supported on C<urxvt::overlay> objects are:
1453 1601
1454=over 4 1602=over
1455 1603
1456=item $overlay->set ($x, $y, $text[, $rend]) 1604=item $overlay->set ($x, $y, $text[, $rend])
1457 1605
1458Similar 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
1459text 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
… …
1503Returns the number of screen-cells this string would need. Correctly 1651Returns the number of screen-cells this string would need. Correctly
1504accounts for wide and combining characters. 1652accounts for wide and combining characters.
1505 1653
1506=item $octets = $term->locale_encode ($string) 1654=item $octets = $term->locale_encode ($string)
1507 1655
1508Convert 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>.
1509 1658
1510=item $string = $term->locale_decode ($octets) 1659=item $string = $term->locale_decode ($octets)
1511 1660
1512Convert 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>.
1513 1663
1514=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])
1515 1665
1516XORs the rendition values in the given span with the provided value 1666XORs the rendition values in the given span with the provided value
1517(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
… …
1610 1760
1611=item $term->key_release ($state, $keycode[, $time]) 1761=item $term->key_release ($state, $keycode[, $time])
1612 1762
1613Deliver various fake events to to terminal. 1763Deliver various fake events to to terminal.
1614 1764
1615=item $window_width = $term->width 1765=item $window_width = $term->width ([$new_value])
1616 1766
1617=item $window_height = $term->height 1767=item $window_height = $term->height ([$new_value])
1618 1768
1619=item $font_width = $term->fwidth 1769=item $font_width = $term->fwidth ([$new_value])
1620 1770
1621=item $font_height = $term->fheight 1771=item $font_height = $term->fheight ([$new_value])
1622 1772
1623=item $font_ascent = $term->fbase 1773=item $font_ascent = $term->fbase ([$new_value])
1624 1774
1625=item $terminal_rows = $term->nrow 1775=item $terminal_rows = $term->nrow ([$new_value])
1626 1776
1627=item $terminal_columns = $term->ncol 1777=item $terminal_columns = $term->ncol ([$new_value])
1628 1778
1629=item $has_focus = $term->focus 1779=item $has_focus = $term->focus ([$new_value])
1630 1780
1631=item $is_mapped = $term->mapped 1781=item $is_mapped = $term->mapped ([$new_value])
1632 1782
1633=item $max_scrollback = $term->saveLines 1783=item $max_scrollback = $term->saveLines ([$new_value])
1634 1784
1635=item $nrow_plus_saveLines = $term->total_rows 1785=item $nrow_plus_saveLines = $term->total_rows ([$new_value])
1636 1786
1637=item $topmost_scrollback_row = $term->top_row 1787=item $topmost_scrollback_row = $term->top_row ([$new_value])
1638 1788
1639Return various integers describing terminal characteristics. 1789Return various integers describing terminal characteristics. If an
1790argument is given, changes the value and returns the previous one.
1640 1791
1641=item $x_display = $term->display_id 1792=item $x_display = $term->display_id
1642 1793
1643Return the DISPLAY used by rxvt-unicode. 1794Return the DISPLAY used by rxvt-unicode.
1644 1795
… …
1681 1832
1682=item $cursor_is_hidden = $term->hidden_cursor 1833=item $cursor_is_hidden = $term->hidden_cursor
1683 1834
1684Returns whether the cursor is currently hidden or not. 1835Returns whether the cursor is currently hidden or not.
1685 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
1686=item $view_start = $term->view_start ([$newvalue]) 1847=item $view_start = $term->view_start ([$newvalue])
1687 1848
1688Returns the row number of the topmost displayed line. Maximum value is 1849Returns the row number of the topmost displayed line and changes it,
1689C<0>, which displays the normal terminal contents. Lower values scroll 1850if an argument is given. Values greater than or equal to C<0> display
1690this many lines into the scrollback buffer. 1851the terminal contents. Lower values scroll this many lines into the
1852scrollback buffer.
1691 1853
1692=item $term->want_refresh 1854=item $term->want_refresh
1693 1855
1694Requests a screen refresh. At the next opportunity, rxvt-unicode will 1856Requests a screen refresh. At the next opportunity, rxvt-unicode will
1695compare the on-screen display with its stored representation. If they 1857compare the on-screen display with its stored representation. If they
1696differ, it redraws the differences. 1858differ, it redraws the differences.
1697 1859
1698Used 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.
1699 1865
1700=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1866=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1701 1867
1702Returns 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 >>
1703is 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
… …
1749 1915
1750Create and return a new C<urxvt::line> object that stores information 1916Create and return a new C<urxvt::line> object that stores information
1751about 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
1752following methods: 1918following methods:
1753 1919
1754=over 4 1920=over
1755 1921
1756=item $text = $line->t ([$new_text]) 1922=item $text = $line->t ([$new_text])
1757 1923
1758Returns 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>
1759 1925
… …
1863where one character corresponds to one screen cell. See 2029where one character corresponds to one screen cell. See
1864C<< $term->ROW_t >> for details. 2030C<< $term->ROW_t >> for details.
1865 2031
1866=item $string = $term->special_decode $text 2032=item $string = $term->special_decode $text
1867 2033
1868Converts rxvt-unicodes text representation into a perl string. See 2034Converts rxvt-unicode's text representation into a perl string. See
1869C<< $term->ROW_t >> for details. 2035C<< $term->ROW_t >> for details.
1870 2036
1871=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 2037=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1872 2038
1873=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 2039=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
… …
1939 2105
1940package urxvt::popup; 2106package urxvt::popup;
1941 2107
1942=head2 The C<urxvt::popup> Class 2108=head2 The C<urxvt::popup> Class
1943 2109
1944=over 4 2110=over
1945 2111
1946=cut 2112=cut
1947 2113
1948sub add_item { 2114sub add_item {
1949 my ($self, $item) = @_; 2115 my ($self, $item) = @_;
… …
2085 ->cb (sub { 2251 ->cb (sub {
2086 $term->{overlay}->set (0, 0, 2252 $term->{overlay}->set (0, 0,
2087 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2253 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
2088 }); 2254 });
2089 2255
2090=over 4 2256=over
2091 2257
2092=item $timer = new urxvt::timer 2258=item $timer = new urxvt::timer
2093 2259
2094Create 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
2095immediately. 2261immediately.
… …
2144 sysread $term->{socket}, my $buf, 8192 2310 sysread $term->{socket}, my $buf, 8192
2145 or end-of-file; 2311 or end-of-file;
2146 }); 2312 });
2147 2313
2148 2314
2149=over 4 2315=over
2150 2316
2151=item $iow = new urxvt::iow 2317=item $iow = new urxvt::iow
2152 2318
2153Create a new io watcher object in stopped state. 2319Create a new io watcher object in stopped state.
2154 2320
… …
2181 2347
2182This class implements idle watchers, that get called automatically when 2348This class implements idle watchers, that get called automatically when
2183the 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
2184some useful work. 2350some useful work.
2185 2351
2186=over 4 2352=over
2187 2353
2188=item $iw = new urxvt::iw 2354=item $iw = new urxvt::iw
2189 2355
2190Create a new idle watcher object in stopped state. 2356Create a new idle watcher object in stopped state.
2191 2357
… …
2216 ->cb (sub { 2382 ->cb (sub {
2217 my ($pw, $exit_status) = @_; 2383 my ($pw, $exit_status) = @_;
2218 ... 2384 ...
2219 }); 2385 });
2220 2386
2221=over 4 2387=over
2222 2388
2223=item $pw = new urxvt::pw 2389=item $pw = new urxvt::pw
2224 2390
2225Create a new process watcher in stopped state. 2391Create a new process watcher in stopped state.
2226 2392
… …
2243=head2 URXVT_PERL_VERBOSITY 2409=head2 URXVT_PERL_VERBOSITY
2244 2410
2245This variable controls the verbosity level of the perl extension. Higher 2411This variable controls the verbosity level of the perl extension. Higher
2246numbers indicate more verbose output. 2412numbers indicate more verbose output.
2247 2413
2248=over 4 2414=over
2249 2415
2250=item == 0 - fatal messages 2416=item == 0 - fatal messages only
2417
2418=item >= 2 - general warnings (default level)
2251 2419
2252=item >= 3 - script loading and management 2420=item >= 3 - script loading and management
2253 2421
2254=item >=10 - all called hooks 2422=item >=10 - all called hooks
2255 2423

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines