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.220 by root, Tue Jun 19 18:17:56 2012 UTC vs.
Revision 1.229 by root, Sat Apr 26 18:53:51 2014 UTC

1=encoding utf8 1=encoding utf8
2 2
3=head1 NAME 3=head1 NAME
4 4
5@@RXVT_NAME@@perl - 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 $HOME:
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 @@RXVT_NAME@@ using it: 16 # start a urxvt using it:
17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 urxvt --perl-lib $HOME -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 "vars"' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in 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"
32and "perl-ext-common" resources to the empty string. 32and "perl-ext-common" resources to the empty string.
33 33
34=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
35 35
36A number of extensions are delivered with this release. You can find them 36A number of extensions are delivered with this release. You can find them
37in F<@@RXVT_LIBDIR@@/urxvt/perl/>, and the documentation can be viewed 37in F<< <libdir>/urxvt/perl/ >>, and the documentation can be viewed using
38using F<< man urxvt-<EXTENSIONNAME> >>. 38F<< man urxvt-<EXTENSIONNAME> >>.
39 39
40You can activate them like this: 40You can activate them like this:
41 41
42 @@RXVT_NAME@@ -pe <extensionname> 42 urxvt -pe <extensionname>
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
… …
103internal use. 103internal use.
104 104
105Although it isn't a C<urxvt::term> object, you can call all methods of the 105Although it isn't a C<urxvt::term> object, you can call all methods of the
106C<urxvt::term> class on this object. 106C<urxvt::term> class on this object.
107 107
108It has the following methods and data members: 108Additional methods only supported for extension objects are described in
109 109the C<urxvt::extension> section below.
110=over 4
111
112=item $urxvt_term = $self->{term}
113
114Returns the C<urxvt::term> object associated with this instance of the
115extension. This member I<must not> be changed in any way.
116
117=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
118
119Dynamically enable the given hooks (named without the C<on_> prefix) for
120this extension, replacing any previous hook. This is useful when you want
121to overwrite time-critical hooks only temporarily.
122
123To install additional callbacks for the same hook, you cna use the C<on>
124method of the C<urxvt::term> class.
125
126=item $self->disable ($hook_name[, $hook_name..])
127
128Dynamically disable the given hooks.
129
130=item $self->x_resource ($pattern)
131
132=item $self->x_resource_boolean ($pattern)
133
134These methods support an additional C<%> prefix when called on an
135extension object - see the description of these methods in the
136C<urxvt::term> class for details.
137
138=back
139 110
140=head2 Hooks 111=head2 Hooks
141 112
142The following subroutines can be declared in extension files, and will be 113The following subroutines can be declared in extension files, and will be
143called whenever the relevant event happens. 114called whenever the relevant event happens.
… …
310 281
311=item on_refresh_end $term 282=item on_refresh_end $term
312 283
313Called just after the screen gets redrawn. See C<on_refresh_begin>. 284Called just after the screen gets redrawn. See C<on_refresh_begin>.
314 285
315=item on_user_command $term, $string 286=item on_user_command $term, $string *DEPRECATED*
316 287
317Called whenever a user-configured event is being activated (e.g. via 288Called whenever a user-configured event is being activated (e.g. via
318a C<perl:string> action bound to a key, see description of the B<keysym> 289a C<perl:string> action bound to a key, see description of the B<keysym>
319resource in the @@RXVT_NAME@@(1) manpage). 290resource in the urxvt(1) manpage).
320 291
321The event is simply the action string. This interface is assumed to change 292The event is simply the action string. This interface is going away in
322slightly in the future. 293preference to the C<< ->register_keysym_action >> method.
323 294
324=item on_register_command $term, $keysym, $modifiermask, $string 295=item on_register_command $term, $keysym, $modifiermask, $string
325 296
326Called after parsing a keysym resource but before registering the 297Called after parsing a keysym resource but before registering the
327associated binding. If this hook returns TRUE the binding is not 298associated binding. If this hook returns a true value the binding
328registered. It can be used to modify a binding by calling 299is not registered. It can be used to modify a binding by calling
329C<register_command>. 300C<register_command>.
330 301
331=item on_resize_all_windows $term, $new_width, $new_height 302=item on_resize_all_windows $term, $new_width, $new_height
332 303
333Called just after the new window size has been calculated, but before 304Called just after the new window size has been calculated, but before
334windows are actually being resized or hints are being set. If this hook 305windows are actually being resized or hints are being set. If this hook
335returns TRUE, setting of the window hints is being skipped. 306returns a true value, setting of the window hints is being skipped.
336 307
337=item on_x_event $term, $event 308=item on_x_event $term, $event
338 309
339Called on every X event received on the vt window (and possibly other 310Called on every X event received on the vt window (and possibly other
340windows). Should only be used as a last resort. Most event structure 311windows). Should only be used as a last resort. Most event structure
… …
598 $name =~ y/-/./ if $isarg; 569 $name =~ y/-/./ if $isarg;
599 570
600 $term->scan_meta; 571 $term->scan_meta;
601 572
602 my $r = $term->{meta}{resource}; 573 my $r = $term->{meta}{resource};
603 keys %$r; # reste iterator 574 keys %$r; # reset iterator
604 while (my ($pattern, $v) = each %$r) { 575 while (my ($pattern, $v) = each %$r) {
605 if ( 576 if (
606 $pattern =~ /\.$/ 577 $pattern =~ /\.$/
607 ? $pattern eq substr $name, 0, length $pattern 578 ? $pattern eq substr $name, 0, length $pattern
608 : $pattern eq $name 579 : $pattern eq $name
… …
801 ($mask, @color{qw(fg bg)}, \@failed) 772 ($mask, @color{qw(fg bg)}, \@failed)
802} 773}
803 774
804package urxvt::term::extension; 775package urxvt::term::extension;
805 776
806sub enable { 777=head2 The C<urxvt::term::extension> class
807 my ($self, %hook) = @_;
808 my $pkg = $self->{_pkg};
809 778
810 while (my ($name, $cb) = each %hook) { 779Each extension attached to a terminal object is represented by
811 my $htype = $HOOKTYPE{uc $name}; 780a C<urxvt::term::extension> object.
812 defined $htype
813 or Carp::croak "unsupported hook type '$name'";
814 781
815 $self->set_should_invoke ($htype, +1) 782You can use these objects, which are passed to all callbacks to store any
816 unless exists $self->{term}{_hook}[$htype]{$pkg}; 783state related to the terminal and extension instance.
817 784
818 $self->{term}{_hook}[$htype]{$pkg} = $cb; 785The methods (And data members) documented below can be called on extension
819 } 786objects, in addition to call methods documented for the <urxvt::term>
820} 787class.
821 788
822sub disable { 789=over 4
823 my ($self, @hook) = @_;
824 my $pkg = $self->{_pkg};
825 790
826 for my $name (@hook) { 791=item $urxvt_term = $self->{term}
827 my $htype = $HOOKTYPE{uc $name};
828 defined $htype
829 or Carp::croak "unsupported hook type '$name'";
830 792
831 $self->set_should_invoke ($htype, -1) 793Returns the C<urxvt::term> object associated with this instance of the
832 if delete $self->{term}{_hook}[$htype]{$pkg}; 794extension. This member I<must not> be changed in any way.
833 } 795
834} 796=cut
835 797
836our $AUTOLOAD; 798our $AUTOLOAD;
837 799
838sub AUTOLOAD { 800sub AUTOLOAD {
839 $AUTOLOAD =~ /:([^:]+)$/ 801 $AUTOLOAD =~ /:([^:]+)$/
… …
852 814
853sub DESTROY { 815sub DESTROY {
854 # nop 816 # nop
855} 817}
856 818
857# urxvt::destroy_hook 819# urxvt::destroy_hook (basically a cheap Guard:: implementation)
858 820
859sub urxvt::destroy_hook::DESTROY { 821sub urxvt::destroy_hook::DESTROY {
860 ${$_[0]}->(); 822 ${$_[0]}->();
861} 823}
862 824
863sub urxvt::destroy_hook(&) { 825sub urxvt::destroy_hook(&) {
864 bless \shift, urxvt::destroy_hook:: 826 bless \shift, urxvt::destroy_hook::
865} 827}
828
829=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
830
831Dynamically enable the given hooks (named without the C<on_> prefix) for
832this extension, replacing any hook previously installed via C<enable> in
833this extension.
834
835This is useful when you want to overwrite time-critical hooks only
836temporarily.
837
838To install additional callbacks for the same hook, you can use the C<on>
839method of the C<urxvt::term> class.
840
841=item $self->disable ($hook_name[, $hook_name..])
842
843Dynamically disable the given hooks.
844
845=cut
846
847sub enable {
848 my ($self, %hook) = @_;
849 my $pkg = $self->{_pkg};
850
851 while (my ($name, $cb) = each %hook) {
852 my $htype = $HOOKTYPE{uc $name};
853 defined $htype
854 or Carp::croak "unsupported hook type '$name'";
855
856 $self->set_should_invoke ($htype, +1)
857 unless exists $self->{term}{_hook}[$htype]{$pkg};
858
859 $self->{term}{_hook}[$htype]{$pkg} = $cb;
860 }
861}
862
863sub disable {
864 my ($self, @hook) = @_;
865 my $pkg = $self->{_pkg};
866
867 for my $name (@hook) {
868 my $htype = $HOOKTYPE{uc $name};
869 defined $htype
870 or Carp::croak "unsupported hook type '$name'";
871
872 $self->set_should_invoke ($htype, -1)
873 if delete $self->{term}{_hook}[$htype]{$pkg};
874 }
875}
876
877=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
878
879Similar to the C<enable> enable, but installs additional callbacks for
880the given hook(s) (that is, it doesn't replace existing callbacks), and
881returns a guard object. When the guard object is destroyed the callbacks
882are disabled again.
883
884=cut
885
886sub urxvt::extension::on_disable::DESTROY {
887 my $disable = shift;
888
889 my $term = delete $disable->{""};
890
891 while (my ($htype, $id) = each %$disable) {
892 delete $term->{_hook}[$htype]{$id};
893 $term->set_should_invoke ($htype, -1);
894 }
895}
896
897sub on {
898 my ($self, %hook) = @_;
899
900 my $term = $self->{term};
901
902 my %disable = ( "" => $term );
903
904 while (my ($name, $cb) = each %hook) {
905 my $htype = $HOOKTYPE{uc $name};
906 defined $htype
907 or Carp::croak "unsupported hook type '$name'";
908
909 $term->set_should_invoke ($htype, +1);
910 $term->{_hook}[$htype]{ $disable{$htype} = $cb+0 }
911 = sub { shift; $cb->($self, @_) }; # very ugly indeed
912 }
913
914 bless \%disable, "urxvt::extension::on_disable"
915}
916
917=item $self->x_resource ($pattern)
918
919=item $self->x_resource_boolean ($pattern)
920
921These methods support an additional C<%> prefix when called on an
922extension object - see the description of these methods in the
923C<urxvt::term> class for details.
924
925=cut
866 926
867sub x_resource { 927sub x_resource {
868 my ($self, $name) = @_; 928 my ($self, $name) = @_;
869 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 929 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
870 $self->{term}->x_resource ($name) 930 $self->{term}->x_resource ($name)
… …
873sub x_resource_boolean { 933sub x_resource_boolean {
874 my ($self, $name) = @_; 934 my ($self, $name) = @_;
875 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 935 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
876 $self->{term}->x_resource_boolean ($name) 936 $self->{term}->x_resource_boolean ($name)
877} 937}
938
939=back
940
941=cut
878 942
879package urxvt::anyevent; 943package urxvt::anyevent;
880 944
881=head2 The C<urxvt::anyevent> Class 945=head2 The C<urxvt::anyevent> Class
882 946
… …
1016 1080
1017 for my $dir (reverse @libdirs) { 1081 for my $dir (reverse @libdirs) {
1018 opendir my $fh, $dir 1082 opendir my $fh, $dir
1019 or next; 1083 or next;
1020 for my $ext (readdir $fh) { 1084 for my $ext (readdir $fh) {
1021 $ext ne "." 1085 $ext !~ /^\./
1022 and $ext ne ".."
1023 and open my $fh, "<", "$dir/$ext" 1086 and open my $fh, "<", "$dir/$ext"
1024 or next; 1087 or next;
1025 1088
1026 while (<$fh>) { 1089 while (<$fh>) {
1027 if (/^#:META:X_RESOURCE:(.*)/) { 1090 if (/^#:META:X_RESOURCE:(.*)/) {
… …
1066} 1129}
1067 1130
1068=item $term->destroy 1131=item $term->destroy
1069 1132
1070Destroy the terminal object (close the window, free resources 1133Destroy the terminal object (close the window, free resources
1071etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1134etc.). Please note that urxvt will not exit as long as any event
1072watchers (timers, io watchers) are still active. 1135watchers (timers, io watchers) are still active.
1073
1074=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
1075
1076Similar to the extension method C<enable>, but installs additional
1077callbacks for the givne hook(s) (existing ones are not replaced), and
1078returns a guard object. When the guard object is destroyed the callbacks
1079are disabled again.
1080
1081Note that these callbacks receive the normal paramaters, but the first
1082argument (normally the extension) is currently undefined.
1083
1084=cut
1085
1086sub urxvt::term::on_disable::DESTROY {
1087 my $disable = shift;
1088
1089 my $self = delete $disable->{""};
1090
1091 while (my ($htype, $id) = each %$disable) {
1092 delete $self->{_hook}[$htype]{$id};
1093 $self->set_should_invoke ($htype, -1);
1094 }
1095}
1096
1097sub on {
1098 my ($self, %hook) = @_;
1099
1100 my %disable = ( "" => $self );
1101
1102 while (my ($name, $cb) = each %hook) {
1103 my $htype = $HOOKTYPE{uc $name};
1104 defined $htype
1105 or Carp::croak "unsupported hook type '$name'";
1106
1107 my $id = $cb+0;
1108
1109 $self->set_should_invoke ($htype, +1);
1110 $disable{$htype} = $id;
1111 $self->{_hook}[$htype]{$id} = $cb;
1112 }
1113
1114 bless \%disable, "urxvt::term::on_disable"
1115}
1116 1136
1117=item $term->exec_async ($cmd[, @args]) 1137=item $term->exec_async ($cmd[, @args])
1118 1138
1119Works like the combination of the C<fork>/C<exec> builtins, which executes 1139Works like the combination of the C<fork>/C<exec> builtins, which executes
1120("starts") programs in the background. This function takes care of setting 1140("starts") programs in the background. This function takes care of setting
… …
1238} 1258}
1239 1259
1240=item $success = $term->parse_keysym ($key, $octets) 1260=item $success = $term->parse_keysym ($key, $octets)
1241 1261
1242Adds a key binding exactly as specified via a resource. See the 1262Adds a key binding exactly as specified via a resource. See the
1243C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1263C<keysym> resource in the urxvt(1) manpage.
1244 1264
1245=item $term->register_command ($keysym, $modifiermask, $string) 1265=item $term->register_command ($keysym, $modifiermask, $string)
1246 1266
1247Adds a key binding. This is a lower level api compared to 1267Adds a key binding. This is a lower level api compared to
1248C<parse_keysym>, as it expects a parsed key description, and can be 1268C<parse_keysym>, as it expects a parsed key description, and can be
… …
1678} 1698}
1679 1699
1680sub urxvt::line::t { 1700sub urxvt::line::t {
1681 my ($self) = @_; 1701 my ($self) = @_;
1682 1702
1683 if (@_ > 1) 1703 if (@_ > 1) {
1684 {
1685 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1704 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1686 for $self->{beg} .. $self->{end}; 1705 for $self->{beg} .. $self->{end};
1687 } 1706 }
1688 1707
1689 defined wantarray && 1708 defined wantarray &&
1690 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1709 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1691 0, $self->{len} 1710 0, $self->{len}
1692} 1711}
1693 1712
1694sub urxvt::line::r { 1713sub urxvt::line::r {
1695 my ($self) = @_; 1714 my ($self) = @_;
1696 1715
1697 if (@_ > 1) 1716 if (@_ > 1) {
1698 {
1699 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1717 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1700 for $self->{beg} .. $self->{end}; 1718 for $self->{beg} .. $self->{end};
1701 } 1719 }
1702 1720
1703 if (defined wantarray) { 1721 if (defined wantarray) {
1704 my $rend = [ 1722 my $rend = [
1705 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1723 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1706 ]; 1724 ];

Diff Legend

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