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.244 by sf-exg, Mon Oct 13 12:17:48 2014 UTC vs.
Revision 1.270 by root, Fri Nov 26 18:49:47 2021 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
1258 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell 1397 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1259 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs 1398 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1260 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right 1399 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1261 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen 1400 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1262 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords 1401 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1263 urgentOnBell utmpInhibit visualBell 1402 urgentOnBell utmpInhibit visualBell disablePasteBrackets
1264 1403
1265=item $value = $term->resource ($name[, $newval]) 1404=item $value = $term->resource ($name[, $newval])
1266 1405
1267Returns the current resource value associated with a given name and 1406Returns the current resource value associated with a given name and
1268optionally sets a new value. Setting values is most useful in the C<init> 1407optionally sets a new value. Setting values is most useful in the C<init>
1294 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1433 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1295 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1434 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1296 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1435 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1297 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll 1436 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1298 term_name title transient_for transparent tripleclickwords urgentOnBell 1437 term_name title transient_for transparent tripleclickwords urgentOnBell
1299 utmpInhibit visualBell 1438 utmpInhibit visualBell rewrapMode disablePasteBrackets
1300 1439
1301=cut 1440=cut
1302 1441
1303sub resource($$;$) { 1442sub resource($$;$) {
1304 my ($self, $name) = (shift, shift); 1443 my ($self, $name) = (shift, shift);
1341 my $res = &x_resource; 1480 my $res = &x_resource;
1342 1481
1343 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1482 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1344} 1483}
1345 1484
1485=item $action = $term->lookup_keysym ($keysym, $state)
1486
1487Returns the action bound to key combination C<($keysym, $state)>,
1488if a binding for it exists, and C<undef> otherwise.
1489
1346=item $success = $term->bind_action ($key, $octets) 1490=item $success = $term->bind_action ($key, $action)
1347 1491
1348Adds a key binding exactly as specified via a C<keysym> resource. See the 1492Adds a key binding exactly as specified via a C<keysym> resource. See the
1349C<keysym> resource in the urxvt(1) manpage. 1493C<keysym> resource in the urxvt(1) manpage.
1494
1495To add default bindings for actions, an extension should call C<<
1496->bind_action >> in its C<init> hook for every such binding. Doing it
1497in the C<init> hook allows users to override or remove the binding
1498again.
1499
1500Example: the C<searchable-scrollback> by default binds itself
1501on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1502$term->bind_action >>.
1503
1504 sub init {
1505 my ($self) = @_;
1506
1507 $self->bind_action ("M-s" => "%:start");
1508 }
1350 1509
1351=item $rend = $term->rstyle ([$new_rstyle]) 1510=item $rend = $term->rstyle ([$new_rstyle])
1352 1511
1353Return and optionally change the current rendition. Text that is output by 1512Return and optionally change the current rendition. Text that is output by
1354the terminal application will use this style. 1513the terminal application will use this style.
1431This method returns an urxvt::overlay object. The overlay will be visible 1590This method returns an urxvt::overlay object. The overlay will be visible
1432as long as the perl object is referenced. 1591as long as the perl object is referenced.
1433 1592
1434The methods currently supported on C<urxvt::overlay> objects are: 1593The methods currently supported on C<urxvt::overlay> objects are:
1435 1594
1436=over 4 1595=over
1437 1596
1438=item $overlay->set ($x, $y, $text[, $rend]) 1597=item $overlay->set ($x, $y, $text[, $rend])
1439 1598
1440Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1599Similar 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 1600text in rxvt-unicode's special encoding and an array of rendition values
1485Returns the number of screen-cells this string would need. Correctly 1644Returns the number of screen-cells this string would need. Correctly
1486accounts for wide and combining characters. 1645accounts for wide and combining characters.
1487 1646
1488=item $octets = $term->locale_encode ($string) 1647=item $octets = $term->locale_encode ($string)
1489 1648
1490Convert the given text string into the corresponding locale encoding. 1649Convert the given text string into the corresponding locale
1650encoding. Returns C<undef> if C<$string> is C<undef>.
1491 1651
1492=item $string = $term->locale_decode ($octets) 1652=item $string = $term->locale_decode ($octets)
1493 1653
1494Convert the given locale-encoded octets into a perl string. 1654Convert the given locale-encoded octets into a perl string. Returns
1655C<undef> if C<$octets> is C<undef>.
1495 1656
1496=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) 1657=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1497 1658
1498XORs the rendition values in the given span with the provided value 1659XORs 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 1660(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1512 1673
1513=item $term->scr_add_lines ($string) 1674=item $term->scr_add_lines ($string)
1514 1675
1515Write the given text string to the screen, as if output by the application 1676Write the given text string to the screen, as if output by the application
1516running inside the terminal. It may not contain command sequences (escape 1677running inside the terminal. It may not contain command sequences (escape
1517codes), but is free to use line feeds, carriage returns and tabs. The 1678codes - see C<cmd_parse> for that), but is free to use line feeds,
1518string is a normal text string, not in locale-dependent encoding. 1679carriage returns and tabs. The string is a normal text string, not in
1680locale-dependent encoding.
1519 1681
1520Normally its not a good idea to use this function, as programs might be 1682Normally its not a good idea to use this function, as programs might be
1521confused by changes in cursor position or scrolling. Its useful inside a 1683confused by changes in cursor position or scrolling. Its useful inside a
1522C<on_add_lines> hook, though. 1684C<on_add_lines> hook, though.
1523 1685
1531locale-specific encoding of the terminal and can contain command sequences 1693locale-specific encoding of the terminal and can contain command sequences
1532(escape codes) that will be interpreted. 1694(escape codes) that will be interpreted.
1533 1695
1534=item $term->tt_write ($octets) 1696=item $term->tt_write ($octets)
1535 1697
1536Write the octets given in C<$octets> to the tty (i.e. as program input). To 1698Write the octets given in C<$octets> to the tty (i.e. as user input
1699to the program, see C<cmd_parse> for the opposite direction). To pass
1537pass characters instead of octets, you should convert your strings first 1700characters instead of octets, you should convert your strings first to the
1538to the locale-specific encoding using C<< $term->locale_encode >>. 1701locale-specific encoding using C<< $term->locale_encode >>.
1539 1702
1540=item $term->tt_write_user_input ($octets) 1703=item $term->tt_write_user_input ($octets)
1541 1704
1542Like C<tt_write>, but should be used when writing strings in response to 1705Like C<tt_write>, but should be used when writing strings in response to
1543the user pressing a key, to invoke the additional actions requested by 1706the user pressing a key, to invoke the additional actions requested by
1590 1753
1591=item $term->key_release ($state, $keycode[, $time]) 1754=item $term->key_release ($state, $keycode[, $time])
1592 1755
1593Deliver various fake events to to terminal. 1756Deliver various fake events to to terminal.
1594 1757
1595=item $window_width = $term->width 1758=item $window_width = $term->width ([$new_value])
1596 1759
1597=item $window_height = $term->height 1760=item $window_height = $term->height ([$new_value])
1598 1761
1599=item $font_width = $term->fwidth 1762=item $font_width = $term->fwidth ([$new_value])
1600 1763
1601=item $font_height = $term->fheight 1764=item $font_height = $term->fheight ([$new_value])
1602 1765
1603=item $font_ascent = $term->fbase 1766=item $font_ascent = $term->fbase ([$new_value])
1604 1767
1605=item $terminal_rows = $term->nrow 1768=item $terminal_rows = $term->nrow ([$new_value])
1606 1769
1607=item $terminal_columns = $term->ncol 1770=item $terminal_columns = $term->ncol ([$new_value])
1608 1771
1609=item $has_focus = $term->focus 1772=item $has_focus = $term->focus ([$new_value])
1610 1773
1611=item $is_mapped = $term->mapped 1774=item $is_mapped = $term->mapped ([$new_value])
1612 1775
1613=item $max_scrollback = $term->saveLines 1776=item $max_scrollback = $term->saveLines ([$new_value])
1614 1777
1615=item $nrow_plus_saveLines = $term->total_rows 1778=item $nrow_plus_saveLines = $term->total_rows ([$new_value])
1616 1779
1617=item $topmost_scrollback_row = $term->top_row 1780=item $topmost_scrollback_row = $term->top_row ([$new_value])
1618 1781
1619Return various integers describing terminal characteristics. 1782Return various integers describing terminal characteristics. If an
1783argument is given, changes the value and returns the previous one.
1620 1784
1621=item $x_display = $term->display_id 1785=item $x_display = $term->display_id
1622 1786
1623Return the DISPLAY used by rxvt-unicode. 1787Return the DISPLAY used by rxvt-unicode.
1624 1788
1661 1825
1662=item $cursor_is_hidden = $term->hidden_cursor 1826=item $cursor_is_hidden = $term->hidden_cursor
1663 1827
1664Returns whether the cursor is currently hidden or not. 1828Returns whether the cursor is currently hidden or not.
1665 1829
1830=item $priv_modes = $term->priv_modes
1831
1832Returns a bitset with the state of DEC private modes.
1833
1834Example:
1835
1836 if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
1837 # mouse reporting is turned on
1838 }
1839
1666=item $view_start = $term->view_start ([$newvalue]) 1840=item $view_start = $term->view_start ([$newvalue])
1667 1841
1668Returns the row number of the topmost displayed line. Maximum value is 1842Returns the row number of the topmost displayed line and changes it,
1669C<0>, which displays the normal terminal contents. Lower values scroll 1843if an argument is given. Values greater than or equal to C<0> display
1670this many lines into the scrollback buffer. 1844the terminal contents. Lower values scroll this many lines into the
1845scrollback buffer.
1671 1846
1672=item $term->want_refresh 1847=item $term->want_refresh
1673 1848
1674Requests a screen refresh. At the next opportunity, rxvt-unicode will 1849Requests a screen refresh. At the next opportunity, rxvt-unicode will
1675compare the on-screen display with its stored representation. If they 1850compare the on-screen display with its stored representation. If they
1676differ, it redraws the differences. 1851differ, it redraws the differences.
1677 1852
1678Used after changing terminal contents to display them. 1853Used after changing terminal contents to display them.
1854
1855=item $term->refresh_check
1856
1857Checks if a refresh has been requested and, if so, schedules one.
1679 1858
1680=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1859=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1681 1860
1682Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >> 1861Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1683is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost 1862is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1729 1908
1730Create and return a new C<urxvt::line> object that stores information 1909Create and return a new C<urxvt::line> object that stores information
1731about the logical line that row C<$row_number> is part of. It supports the 1910about the logical line that row C<$row_number> is part of. It supports the
1732following methods: 1911following methods:
1733 1912
1734=over 4 1913=over
1735 1914
1736=item $text = $line->t ([$new_text]) 1915=item $text = $line->t ([$new_text])
1737 1916
1738Returns or replaces the full text of the line, similar to C<ROW_t> 1917Returns or replaces the full text of the line, similar to C<ROW_t>
1739 1918
1843where one character corresponds to one screen cell. See 2022where one character corresponds to one screen cell. See
1844C<< $term->ROW_t >> for details. 2023C<< $term->ROW_t >> for details.
1845 2024
1846=item $string = $term->special_decode $text 2025=item $string = $term->special_decode $text
1847 2026
1848Converts rxvt-unicodes text representation into a perl string. See 2027Converts rxvt-unicode's text representation into a perl string. See
1849C<< $term->ROW_t >> for details. 2028C<< $term->ROW_t >> for details.
1850 2029
1851=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) 2030=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1852 2031
1853=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) 2032=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1919 2098
1920package urxvt::popup; 2099package urxvt::popup;
1921 2100
1922=head2 The C<urxvt::popup> Class 2101=head2 The C<urxvt::popup> Class
1923 2102
1924=over 4 2103=over
1925 2104
1926=cut 2105=cut
1927 2106
1928sub add_item { 2107sub add_item {
1929 my ($self, $item) = @_; 2108 my ($self, $item) = @_;
2065 ->cb (sub { 2244 ->cb (sub {
2066 $term->{overlay}->set (0, 0, 2245 $term->{overlay}->set (0, 0,
2067 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2246 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
2068 }); 2247 });
2069 2248
2070=over 4 2249=over
2071 2250
2072=item $timer = new urxvt::timer 2251=item $timer = new urxvt::timer
2073 2252
2074Create a new timer object in started state. It is scheduled to fire 2253Create a new timer object in started state. It is scheduled to fire
2075immediately. 2254immediately.
2124 sysread $term->{socket}, my $buf, 8192 2303 sysread $term->{socket}, my $buf, 8192
2125 or end-of-file; 2304 or end-of-file;
2126 }); 2305 });
2127 2306
2128 2307
2129=over 4 2308=over
2130 2309
2131=item $iow = new urxvt::iow 2310=item $iow = new urxvt::iow
2132 2311
2133Create a new io watcher object in stopped state. 2312Create a new io watcher object in stopped state.
2134 2313
2161 2340
2162This class implements idle watchers, that get called automatically when 2341This class implements idle watchers, that get called automatically when
2163the process is idle. They should return as fast as possible, after doing 2342the process is idle. They should return as fast as possible, after doing
2164some useful work. 2343some useful work.
2165 2344
2166=over 4 2345=over
2167 2346
2168=item $iw = new urxvt::iw 2347=item $iw = new urxvt::iw
2169 2348
2170Create a new idle watcher object in stopped state. 2349Create a new idle watcher object in stopped state.
2171 2350
2196 ->cb (sub { 2375 ->cb (sub {
2197 my ($pw, $exit_status) = @_; 2376 my ($pw, $exit_status) = @_;
2198 ... 2377 ...
2199 }); 2378 });
2200 2379
2201=over 4 2380=over
2202 2381
2203=item $pw = new urxvt::pw 2382=item $pw = new urxvt::pw
2204 2383
2205Create a new process watcher in stopped state. 2384Create a new process watcher in stopped state.
2206 2385
2223=head2 URXVT_PERL_VERBOSITY 2402=head2 URXVT_PERL_VERBOSITY
2224 2403
2225This variable controls the verbosity level of the perl extension. Higher 2404This variable controls the verbosity level of the perl extension. Higher
2226numbers indicate more verbose output. 2405numbers indicate more verbose output.
2227 2406
2228=over 4 2407=over
2229 2408
2230=item == 0 - fatal messages 2409=item == 0 - fatal messages only
2410
2411=item >= 2 - general warnings (default level)
2231 2412
2232=item >= 3 - script loading and management 2413=item >= 3 - script loading and management
2233 2414
2234=item >=10 - all called hooks 2415=item >=10 - all called hooks
2235 2416

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines