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.227 by root, Sun Mar 31 20:30:32 2013 UTC vs.
Revision 1.249 by root, Fri Dec 26 21:26:37 2014 UTC

43 43
44Or by adding them to the resource for extensions loaded by default: 44Or by adding them to the resource for extensions loaded by default:
45 45
46 URxvt.perl-ext-common: default,selection-autotransform 46 URxvt.perl-ext-common: default,selection-autotransform
47 47
48Extensions that add command line parameters or resources on their own are 48Extensions may add additional resources and C<actions>, i.e., methods
49loaded automatically when used. 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
51more actions it provides using so called META comments, described
52below. Similarly to builtin resources, extension resources can also be
53specified on the command line as long options (with C<.> replaced by
54C<->), in which case the corresponding extension is loaded
55automatically. For this to work the extension B<must> define META
56comments for its resources.
50 57
51=head1 API DOCUMENTATION 58=head1 API DOCUMENTATION
52 59
53=head2 General API Considerations 60=head2 General API Considerations
54 61
106C<urxvt::term> class on this object. 113C<urxvt::term> class on this object.
107 114
108Additional methods only supported for extension objects are described in 115Additional methods only supported for extension objects are described in
109the C<urxvt::extension> section below. 116the C<urxvt::extension> section below.
110 117
118=head2 META comments
119
120Rxvt-unicode recognizes special meta comments in extensions that define
121different types of metadata.
122
123Currently, it recxognises only one such comment:
124
125=over 4
126
127=item #:META:RESOURCE:name:type:desc
128
129The RESOURCE comment defines a resource used by the extension, where
130C<name> is the resource name, C<type> is the resource type, C<boolean>
131or C<string>, and C<desc> is the resource description.
132
133=back
134
111=head2 Hooks 135=head2 Hooks
112 136
113The following subroutines can be declared in extension files, and will be 137The following subroutines can be declared in extension files, and will be
114called whenever the relevant event happens. 138called whenever the relevant event happens.
115 139
281 305
282=item on_refresh_end $term 306=item on_refresh_end $term
283 307
284Called just after the screen gets redrawn. See C<on_refresh_begin>. 308Called just after the screen gets redrawn. See C<on_refresh_begin>.
285 309
310=item on_action $term, $string
311
312Called whenever an action is invoked for the corresponding extension
313(e.g. via a C<extension:string> builtin action bound to a key, see
314description of the B<keysym> resource in the urxvt(1) manpage). The
315event is simply the action string. Note that an action event is always
316associated to a single extension.
317
286=item on_user_command $term, $string 318=item on_user_command $term, $string *DEPRECATED*
287 319
288Called whenever a user-configured event is being activated (e.g. via 320Called whenever a user-configured event is being activated (e.g. via
289a C<perl:string> action bound to a key, see description of the B<keysym> 321a C<perl:string> action bound to a key, see description of the B<keysym>
290resource in the urxvt(1) manpage). 322resource in the urxvt(1) manpage).
291 323
292The event is simply the action string. This interface is assumed to change 324The event is simply the action string. This interface is going away in
293slightly in the future. 325preference to the C<on_action> hook.
294
295=item on_register_command $term, $keysym, $modifiermask, $string
296
297Called after parsing a keysym resource but before registering the
298associated binding. If this hook returns TRUE the binding is not
299registered. It can be used to modify a binding by calling
300C<register_command>.
301 326
302=item on_resize_all_windows $term, $new_width, $new_height 327=item on_resize_all_windows $term, $new_width, $new_height
303 328
304Called just after the new window size has been calculated, but before 329Called just after the new window size has been calculated, but before
305windows are actually being resized or hints are being set. If this hook 330windows are actually being resized or hints are being set. If this hook
306returns TRUE, setting of the window hints is being skipped. 331returns a true value, setting of the window hints is being skipped.
307 332
308=item on_x_event $term, $event 333=item on_x_event $term, $event
309 334
310Called on every X event received on the vt window (and possibly other 335Called on every X event received on the vt window (and possibly other
311windows). Should only be used as a last resort. Most event structure 336windows). Should only be used as a last resort. Most event structure
350manpage), with the additional members C<row> and C<col>, which are the 375manpage), with the additional members C<row> and C<col>, which are the
351(real, not screen-based) row and column under the mouse cursor. 376(real, not screen-based) row and column under the mouse cursor.
352 377
353C<on_key_press> additionally receives the string rxvt-unicode would 378C<on_key_press> additionally receives the string rxvt-unicode would
354output, if any, in locale-specific encoding. 379output, if any, in locale-specific encoding.
355
356subwindow.
357 380
358=item on_client_message $term, $event 381=item on_client_message $term, $event
359 382
360=item on_wm_protocols $term, $event 383=item on_wm_protocols $term, $event
361 384
564no warnings 'utf8'; 587no warnings 'utf8';
565 588
566sub parse_resource { 589sub parse_resource {
567 my ($term, $name, $isarg, $longopt, $flag, $value) = @_; 590 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
568 591
569 $name =~ y/-/./ if $isarg;
570
571 $term->scan_meta; 592 $term->scan_extensions;
572 593
573 my $r = $term->{meta}{resource}; 594 my $r = $term->{meta}{resource};
574 keys %$r; # reste iterator 595 keys %$r; # reset iterator
575 while (my ($pattern, $v) = each %$r) { 596 while (my ($k, $v) = each %$r) {
576 if ( 597 my $pattern = $k;
598 $pattern =~ y/./-/ if $isarg;
599 my $prefix = $name;
600 my $suffix;
577 $pattern =~ /\.$/ 601 if ($pattern =~ /\-$/) {
578 ? $pattern eq substr $name, 0, length $pattern 602 $prefix = substr $name, 0, length $pattern;
579 : $pattern eq $name 603 $suffix = substr $name, length $pattern;
580 ) { 604 }
605 if ($pattern eq $prefix) {
581 $name = "$urxvt::RESCLASS.$name"; 606 $name = "$urxvt::RESCLASS.$k$suffix";
582 607
583 push @{ $term->{perl_ext_3} }, $v->[0]; 608 push @{ $term->{perl_ext_3} }, $v->[0];
584 609
585 if ($v->[1] eq "boolean") { 610 if ($v->[1] eq "boolean") {
586 $term->put_option_db ($name, $flag ? "true" : "false"); 611 $term->put_option_db ($name, $flag ? "true" : "false");
596} 621}
597 622
598sub usage { 623sub usage {
599 my ($term, $usage_type) = @_; 624 my ($term, $usage_type) = @_;
600 625
601 $term->scan_meta; 626 $term->scan_extensions;
602 627
603 my $r = $term->{meta}{resource}; 628 my $r = $term->{meta}{resource};
604 629
605 for my $pattern (sort keys %$r) { 630 for my $pattern (sort keys %$r) {
606 my ($ext, $type, $desc) = @{ $r->{$pattern} }; 631 my ($ext, $type, $desc) = @{ $r->{$pattern} };
667# called by the rxvt core 692# called by the rxvt core
668sub invoke { 693sub invoke {
669 local $TERM = shift; 694 local $TERM = shift;
670 my $htype = shift; 695 my $htype = shift;
671 696
672 if ($htype == 0) { # INIT 697 if ($htype == HOOK_INIT) {
673 my @dirs = $TERM->perl_libdirs; 698 my @dirs = $TERM->perl_libdirs;
699
700 $TERM->scan_extensions;
674 701
675 my %ext_arg; 702 my %ext_arg;
676 703
677 { 704 {
678 my @init = @TERM_INIT; 705 my @init = @TERM_INIT;
682 @TERM_EXT = (); 709 @TERM_EXT = ();
683 $TERM->register_package ($_) for @pkg; 710 $TERM->register_package ($_) for @pkg;
684 } 711 }
685 712
686 for ( 713 for (
714 (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
687 @{ delete $TERM->{perl_ext_3} }, 715 @{ delete $TERM->{perl_ext_3} }
688 grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2
689 ) { 716 ) {
690 if ($_ eq "default") { 717 if ($_ eq "default") {
718
719 $ext_arg{$_} = []
691 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); 720 for qw(selection option-popup selection-popup readline searchable-scrollback);
721
722 for ($TERM->_keysym_resources) {
723 next if /^(?:string|command|builtin|builtin-string|perl)/;
724 next unless /^([A-Za-z0-9_\-]+):/;
725
726 my $ext = $1;
727
728 $ext_arg{$ext} = [];
729 }
730
692 } elsif (/^-(.*)$/) { 731 } elsif (/^-(.*)$/) {
693 delete $ext_arg{$1}; 732 delete $ext_arg{$1};
733
694 } elsif (/^([^<]+)<(.*)>$/) { 734 } elsif (/^([^<]+)<(.*)>$/) {
695 push @{ $ext_arg{$1} }, $2; 735 push @{ $ext_arg{$1} }, $2;
736
696 } else { 737 } else {
697 $ext_arg{$_} ||= []; 738 $ext_arg{$_} ||= [];
698 } 739 }
699 } 740 }
700 741
716 757
717 if (my $cb = $TERM->{_hook}[$htype]) { 758 if (my $cb = $TERM->{_hook}[$htype]) {
718 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 759 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
719 if $verbosity >= 10; 760 if $verbosity >= 10;
720 761
762 if ($htype == HOOK_ACTION) {
763 # this hook is only sent to the extension with the name
764 # matching the first arg
765 my $pkg = shift;
766 $pkg =~ y/-/_/;
767 $pkg = "urxvt::ext::$pkg";
768
769 $cb = $cb->{$pkg}
770 or return undef; #TODO: maybe warn user?
771
772 $cb = { $pkg => $cb };
773 }
774
721 for my $pkg (keys %$cb) { 775 for my $pkg (keys %$cb) {
722 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) }; 776 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
723 $retval ||= $retval_; 777 $retval ||= $retval_;
724 778
725 if ($@) { 779 if ($@) {
730 784
731 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 785 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
732 if $verbosity >= 11; 786 if $verbosity >= 11;
733 } 787 }
734 788
735 if ($htype == 1) { # DESTROY 789 if ($htype == HOOK_DESTROY) {
736 # clear package objects 790 # clear package objects
737 %$_ = () for values %{ $TERM->{_pkg} }; 791 %$_ = () for values %{ $TERM->{_pkg} };
738 792
739 # clear package 793 # clear package
740 %$TERM = (); 794 %$TERM = ();
827} 881}
828 882
829=item $self->enable ($hook_name => $cb[, $hook_name => $cb..]) 883=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
830 884
831Dynamically enable the given hooks (named without the C<on_> prefix) for 885Dynamically enable the given hooks (named without the C<on_> prefix) for
832this extension, replacing any previous hook. This is useful when you want 886this extension, replacing any hook previously installed via C<enable> in
833to overwrite time-critical hooks only temporarily. 887this extension.
888
889This is useful when you want to overwrite time-critical hooks only
890temporarily.
834 891
835To install additional callbacks for the same hook, you can use the C<on> 892To install additional callbacks for the same hook, you can use the C<on>
836method of the C<urxvt::term> class. 893method of the C<urxvt::term> class.
837 894
838=item $self->disable ($hook_name[, $hook_name..]) 895=item $self->disable ($hook_name[, $hook_name..])
909 } 966 }
910 967
911 bless \%disable, "urxvt::extension::on_disable" 968 bless \%disable, "urxvt::extension::on_disable"
912} 969}
913 970
971=item $self->bind_action ($hotkey, $action)
972
914=item $self->x_resource ($pattern) 973=item $self->x_resource ($pattern)
915 974
916=item $self->x_resource_boolean ($pattern) 975=item $self->x_resource_boolean ($pattern)
917 976
918These methods support an additional C<%> prefix when called on an 977These methods support an additional C<%> prefix for C<$action> or
919extension object - see the description of these methods in the 978C<$pattern> when called on an extension object, compared to the
979C<urxvt::term> methods of the same name - see the description of these
920C<urxvt::term> class for details. 980methods in the C<urxvt::term> class for details.
921 981
922=cut 982=cut
983
984sub bind_action {
985 my ($self, $hotkey, $action) = @_;
986 $action =~ s/^%:/$_[0]{_name}:/;
987 $self->{term}->bind_action ($hotkey, $action)
988}
923 989
924sub x_resource { 990sub x_resource {
925 my ($self, $name) = @_; 991 my ($self, $name) = @_;
926 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 992 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
927 $self->{term}->x_resource ($name) 993 $self->{term}->x_resource ($name)
1062 $ENV{URXVT_PERL_LIB}, 1128 $ENV{URXVT_PERL_LIB},
1063 "$ENV{HOME}/.urxvt/ext", 1129 "$ENV{HOME}/.urxvt/ext",
1064 "$LIBDIR/perl" 1130 "$LIBDIR/perl"
1065} 1131}
1066 1132
1067sub scan_meta { 1133# scan for available extensions and collect their metadata
1134sub scan_extensions {
1068 my ($self) = @_; 1135 my ($self) = @_;
1136
1137 return if exists $self->{meta};
1138
1069 my @libdirs = perl_libdirs $self; 1139 my @urxvtdirs = perl_libdirs $self;
1140 my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC;
1070 1141
1071 return if $self->{meta_libdirs} eq join "\x00", @libdirs;
1072
1073 my %meta;
1074
1075 $self->{meta_libdirs} = join "\x00", @libdirs;
1076 $self->{meta} = \%meta; 1142 $self->{meta} = \my %meta;
1077 1143
1078 for my $dir (reverse @libdirs) { 1144 # first gather extensions
1145
1146 my $gather = sub {
1147 my ($dir, $core) = @_;
1148
1079 opendir my $fh, $dir 1149 opendir my $fh, $dir
1080 or next; 1150 or return;
1151
1081 for my $ext (readdir $fh) { 1152 for my $ext (readdir $fh) {
1082 $ext !~ /^\./ 1153 $ext !~ /^\./
1083 and open my $fh, "<", "$dir/$ext"
1084 or next; 1154 or next;
1085 1155
1156 open my $fh, "<", "$dir/$ext"
1157 or next;
1158
1159 -f $fh
1160 or next;
1161
1162 $ext =~ s/\.uext$// or $core
1163 or next;
1164
1165 my %ext = (dir => $dir);
1166
1086 while (<$fh>) { 1167 while (<$fh>) {
1087 if (/^#:META:X_RESOURCE:(.*)/) { 1168 if (/^#:META:(?:X_)?RESOURCE:(.*)/) {
1088 my ($pattern, $type, $desc) = split /:/, $1; 1169 my ($pattern, $type, $desc) = split /:/, $1;
1089 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name 1170 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1090 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { 1171 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1091 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n"; 1172 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1092 } else { 1173 } else {
1093 $meta{resource}{$pattern} = [$ext, $type, $desc]; 1174 $ext{resource}{$pattern} = [$ext, $type, $desc];
1094 } 1175 }
1095 } elsif (/^\s*(?:#|$)/) { 1176 } elsif (/^\s*(?:#|$)/) {
1096 # skip other comments and empty lines 1177 # skip other comments and empty lines
1097 } else { 1178 } else {
1098 last; # stop parsing on first non-empty non-comment line 1179 last; # stop parsing on first non-empty non-comment line
1099 } 1180 }
1100 } 1181 }
1182
1183 $meta{ext}{$ext} = \%ext;
1101 } 1184 }
1185 };
1186
1187 $gather->($_, 0) for @cpandirs;
1188 $gather->($_, 1) for @urxvtdirs;
1189
1190 # and now merge resources
1191 while (my ($k, $v) = each %{ $meta{ext} }) {
1192 #TODO: should check for extensions overriding each other
1193 %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} });
1102 } 1194 }
1103} 1195}
1104 1196
1105=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1197=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1106 1198
1222Returns the X-Resource for the given pattern, excluding the program or 1314Returns the X-Resource for the given pattern, excluding the program or
1223class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1315class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1224same value as used by this instance of rxvt-unicode. Returns C<undef> if no 1316same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1225resource with that pattern exists. 1317resource with that pattern exists.
1226 1318
1227Extensions that define extra resource or command line arguments also need 1319Extensions that define extra resources also need to call this method
1228to call this method to access their values. 1320to access their values.
1229 1321
1230If the method is called on an extension object (basically, from an 1322If the method is called on an extension object (basically, from an
1231extension), then the special prefix C<%.> will be replaced by the name of 1323extension), then the special prefix C<%.> will be replaced by the name of
1232the extension and a dot, and the lone string C<%> will be replaced by the 1324the extension and a dot, and the lone string C<%> will be replaced by the
1233extension name itself. This makes it possible to code extensions so you 1325extension name itself. This makes it possible to code extensions so you
1234can rename them and get a new set of commandline switches and resources 1326can rename them and get a new set of resources without having to change
1235without having to change the actual code. 1327the actual code.
1236 1328
1237This method should only be called during the C<on_start> hook, as there is 1329This method should only be called during the C<on_start> hook, as there is
1238only one resource database per display, and later invocations might return 1330only one resource database per display, and later invocations might return
1239the wrong resources. 1331the wrong resources.
1240 1332
1252 my $res = &x_resource; 1344 my $res = &x_resource;
1253 1345
1254 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 1346 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1255} 1347}
1256 1348
1257=item $success = $term->parse_keysym ($key, $octets) 1349=item $success = $term->bind_action ($key, $action)
1258 1350
1259Adds a key binding exactly as specified via a resource. See the 1351Adds a key binding exactly as specified via a C<keysym> resource. See the
1260C<keysym> resource in the urxvt(1) manpage. 1352C<keysym> resource in the urxvt(1) manpage.
1261 1353
1262=item $term->register_command ($keysym, $modifiermask, $string) 1354To add default bindings for an extension, the extension should call C<<
1355->bind_action >> on it's C<init> hook for every such binding. Doing it
1356in the C<init> hook allows users the override or remove the the binding
1357again.
1263 1358
1264Adds a key binding. This is a lower level api compared to 1359Example: the C<searchable-scrollback> by default binds itself
1265C<parse_keysym>, as it expects a parsed key description, and can be 1360on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
1266used only inside either the C<on_init> hook, to add a binding, or the 1361$term->bind_action >>.
1267C<on_register_command> hook, to modify a parsed binding. 1362
1363 sub init {
1364 my ($self) = @_;
1365
1366 $self->bind_action ("M-s" => "%:start");
1367 }
1268 1368
1269=item $rend = $term->rstyle ([$new_rstyle]) 1369=item $rend = $term->rstyle ([$new_rstyle])
1270 1370
1271Return and optionally change the current rendition. Text that is output by 1371Return and optionally change the current rendition. Text that is output by
1272the terminal application will use this style. 1372the terminal application will use this style.
1430 1530
1431=item $term->scr_add_lines ($string) 1531=item $term->scr_add_lines ($string)
1432 1532
1433Write the given text string to the screen, as if output by the application 1533Write the given text string to the screen, as if output by the application
1434running inside the terminal. It may not contain command sequences (escape 1534running inside the terminal. It may not contain command sequences (escape
1435codes), but is free to use line feeds, carriage returns and tabs. The 1535codes - see C<cmd_parse> for that), but is free to use line feeds,
1436string is a normal text string, not in locale-dependent encoding. 1536carriage returns and tabs. The string is a normal text string, not in
1537locale-dependent encoding.
1437 1538
1438Normally its not a good idea to use this function, as programs might be 1539Normally its not a good idea to use this function, as programs might be
1439confused by changes in cursor position or scrolling. Its useful inside a 1540confused by changes in cursor position or scrolling. Its useful inside a
1440C<on_add_lines> hook, though. 1541C<on_add_lines> hook, though.
1441 1542
1449locale-specific encoding of the terminal and can contain command sequences 1550locale-specific encoding of the terminal and can contain command sequences
1450(escape codes) that will be interpreted. 1551(escape codes) that will be interpreted.
1451 1552
1452=item $term->tt_write ($octets) 1553=item $term->tt_write ($octets)
1453 1554
1454Write the octets given in C<$octets> to the tty (i.e. as program input). To 1555Write the octets given in C<$octets> to the tty (i.e. as user input
1556to the program, see C<cmd_parse> for the opposite direction). To pass
1455pass characters instead of octets, you should convert your strings first 1557characters instead of octets, you should convert your strings first to the
1456to the locale-specific encoding using C<< $term->locale_encode >>. 1558locale-specific encoding using C<< $term->locale_encode >>.
1559
1560=item $term->tt_write_user_input ($octets)
1561
1562Like C<tt_write>, but should be used when writing strings in response to
1563the user pressing a key, to invoke the additional actions requested by
1564the user for that case (C<tt_write> doesn't do that).
1565
1566The typical use case would be inside C<on_action> hooks.
1457 1567
1458=item $term->tt_paste ($octets) 1568=item $term->tt_paste ($octets)
1459 1569
1460Write the octets given in C<$octets> to the tty as a paste, converting NL to 1570Write the octets given in C<$octets> to the tty as a paste, converting NL to
1461CR and bracketing the data with control sequences if bracketed paste mode 1571CR and bracketing the data with control sequences if bracketed paste mode

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines