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.218 by root, Sun Jun 10 17:31:53 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 vewiwed 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
48Extensions that add command line parameters or resources on their own are 48Extensions that add command line parameters or resources on their own are
49laoded automatically when used. 49loaded automatically when used.
50 50
51=head1 API DOCUMENTATION 51=head1 API DOCUMENTATION
52 52
53=head2 General API Considerations 53=head2 General API Considerations
54 54
… …
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
123=item $self->disable ($hook_name[, $hook_name..])
124
125Dynamically disable the given hooks.
126
127=back
128 110
129=head2 Hooks 111=head2 Hooks
130 112
131The following subroutines can be declared in extension files, and will be 113The following subroutines can be declared in extension files, and will be
132called whenever the relevant event happens. 114called whenever the relevant event happens.
… …
299 281
300=item on_refresh_end $term 282=item on_refresh_end $term
301 283
302Called just after the screen gets redrawn. See C<on_refresh_begin>. 284Called just after the screen gets redrawn. See C<on_refresh_begin>.
303 285
304=item on_user_command $term, $string 286=item on_user_command $term, $string *DEPRECATED*
305 287
306Called whenever a user-configured event is being activated (e.g. via 288Called whenever a user-configured event is being activated (e.g. via
307a 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>
308resource in the @@RXVT_NAME@@(1) manpage). 290resource in the urxvt(1) manpage).
309 291
310The 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
311slightly in the future. 293preference to the C<< ->register_keysym_action >> method.
312 294
313=item on_register_command $term, $keysym, $modifiermask, $string 295=item on_register_command $term, $keysym, $modifiermask, $string
314 296
315Called after parsing a keysym resource but before registering the 297Called after parsing a keysym resource but before registering the
316associated binding. If this hook returns TRUE the binding is not 298associated binding. If this hook returns a true value the binding
317registered. It can be used to modify a binding by calling 299is not registered. It can be used to modify a binding by calling
318C<register_command>. 300C<register_command>.
319 301
320=item on_resize_all_windows $term, $new_width, $new_height 302=item on_resize_all_windows $term, $new_width, $new_height
321 303
322Called just after the new window size has been calculated, but before 304Called just after the new window size has been calculated, but before
323windows 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
324returns TRUE, setting of the window hints is being skipped. 306returns a true value, setting of the window hints is being skipped.
325 307
326=item on_x_event $term, $event 308=item on_x_event $term, $event
327 309
328Called 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
329windows). Should only be used as a last resort. Most event structure 311windows). Should only be used as a last resort. Most event structure
… …
587 $name =~ y/-/./ if $isarg; 569 $name =~ y/-/./ if $isarg;
588 570
589 $term->scan_meta; 571 $term->scan_meta;
590 572
591 my $r = $term->{meta}{resource}; 573 my $r = $term->{meta}{resource};
592 keys %$r; # reste iterator 574 keys %$r; # reset iterator
593 while (my ($pattern, $v) = each %$r) { 575 while (my ($pattern, $v) = each %$r) {
594 if ( 576 if (
595 $pattern =~ /\.$/ 577 $pattern =~ /\.$/
596 ? $pattern eq substr $name, 0, length $pattern 578 ? $pattern eq substr $name, 0, length $pattern
597 : $pattern eq $name 579 : $pattern eq $name
… …
735 if (my $cb = $TERM->{_hook}[$htype]) { 717 if (my $cb = $TERM->{_hook}[$htype]) {
736 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 718 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
737 if $verbosity >= 10; 719 if $verbosity >= 10;
738 720
739 for my $pkg (keys %$cb) { 721 for my $pkg (keys %$cb) {
740 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) }; 722 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
741 $retval ||= $retval_; 723 $retval ||= $retval_;
742 724
743 if ($@) { 725 if ($@) {
744 $TERM->ungrab; # better to lose the grab than the session 726 $TERM->ungrab; # better to lose the grab than the session
745 warn $@; 727 warn $@;
… …
790 ($mask, @color{qw(fg bg)}, \@failed) 772 ($mask, @color{qw(fg bg)}, \@failed)
791} 773}
792 774
793package urxvt::term::extension; 775package urxvt::term::extension;
794 776
795sub enable { 777=head2 The C<urxvt::term::extension> class
796 my ($self, %hook) = @_;
797 my $pkg = $self->{_pkg};
798 778
799 while (my ($name, $cb) = each %hook) { 779Each extension attached to a terminal object is represented by
800 my $htype = $HOOKTYPE{uc $name}; 780a C<urxvt::term::extension> object.
801 defined $htype
802 or Carp::croak "unsupported hook type '$name'";
803 781
804 $self->set_should_invoke ($htype, +1) 782You can use these objects, which are passed to all callbacks to store any
805 unless exists $self->{term}{_hook}[$htype]{$pkg}; 783state related to the terminal and extension instance.
806 784
807 $self->{term}{_hook}[$htype]{$pkg} = $cb; 785The methods (And data members) documented below can be called on extension
808 } 786objects, in addition to call methods documented for the <urxvt::term>
809} 787class.
810 788
811sub disable { 789=over 4
812 my ($self, @hook) = @_;
813 my $pkg = $self->{_pkg};
814 790
815 for my $name (@hook) { 791=item $urxvt_term = $self->{term}
816 my $htype = $HOOKTYPE{uc $name};
817 defined $htype
818 or Carp::croak "unsupported hook type '$name'";
819 792
820 $self->set_should_invoke ($htype, -1) 793Returns the C<urxvt::term> object associated with this instance of the
821 if delete $self->{term}{_hook}[$htype]{$pkg}; 794extension. This member I<must not> be changed in any way.
822 } 795
823} 796=cut
824 797
825our $AUTOLOAD; 798our $AUTOLOAD;
826 799
827sub AUTOLOAD { 800sub AUTOLOAD {
828 $AUTOLOAD =~ /:([^:]+)$/ 801 $AUTOLOAD =~ /:([^:]+)$/
… …
841 814
842sub DESTROY { 815sub DESTROY {
843 # nop 816 # nop
844} 817}
845 818
846# urxvt::destroy_hook 819# urxvt::destroy_hook (basically a cheap Guard:: implementation)
847 820
848sub urxvt::destroy_hook::DESTROY { 821sub urxvt::destroy_hook::DESTROY {
849 ${$_[0]}->(); 822 ${$_[0]}->();
850} 823}
851 824
852sub urxvt::destroy_hook(&) { 825sub urxvt::destroy_hook(&) {
853 bless \shift, urxvt::destroy_hook:: 826 bless \shift, urxvt::destroy_hook::
854} 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
855 926
856sub x_resource { 927sub x_resource {
857 my ($self, $name) = @_; 928 my ($self, $name) = @_;
858 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 929 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
859 $self->{term}->x_resource ($name) 930 $self->{term}->x_resource ($name)
… …
862sub x_resource_boolean { 933sub x_resource_boolean {
863 my ($self, $name) = @_; 934 my ($self, $name) = @_;
864 $name =~ s/^%(\.|$)/$_[0]{_name}$1/; 935 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
865 $self->{term}->x_resource_boolean ($name) 936 $self->{term}->x_resource_boolean ($name)
866} 937}
938
939=back
940
941=cut
867 942
868package urxvt::anyevent; 943package urxvt::anyevent;
869 944
870=head2 The C<urxvt::anyevent> Class 945=head2 The C<urxvt::anyevent> Class
871 946
… …
1005 1080
1006 for my $dir (reverse @libdirs) { 1081 for my $dir (reverse @libdirs) {
1007 opendir my $fh, $dir 1082 opendir my $fh, $dir
1008 or next; 1083 or next;
1009 for my $ext (readdir $fh) { 1084 for my $ext (readdir $fh) {
1010 $ext ne "." 1085 $ext !~ /^\./
1011 and $ext ne ".."
1012 and open my $fh, "<", "$dir/$ext" 1086 and open my $fh, "<", "$dir/$ext"
1013 or next; 1087 or next;
1014 1088
1015 while (<$fh>) { 1089 while (<$fh>) {
1016 if (/^#:META:X_RESOURCE:(.*)/) { 1090 if (/^#:META:X_RESOURCE:(.*)/) {
… …
1055} 1129}
1056 1130
1057=item $term->destroy 1131=item $term->destroy
1058 1132
1059Destroy the terminal object (close the window, free resources 1133Destroy the terminal object (close the window, free resources
1060etc.). 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
1061watchers (timers, io watchers) are still active. 1135watchers (timers, io watchers) are still active.
1062 1136
1063=item $term->exec_async ($cmd[, @args]) 1137=item $term->exec_async ($cmd[, @args])
1064 1138
1065Works 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
… …
1121 1195
1122Here is a likely non-exhaustive list of resource names, not all of which 1196Here is a likely non-exhaustive list of resource names, not all of which
1123are supported in every build, please see the source file F</src/rsinc.h> 1197are supported in every build, please see the source file F</src/rsinc.h>
1124to see the actual list: 1198to see the actual list:
1125 1199
1126 answerbackstring backgroundPixmap backspace_key blendtype blurradius 1200 answerbackstring backgroundPixmap backspace_key blurradius
1127 boldFont boldItalicFont borderLess buffered chdir color cursorBlink 1201 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1128 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth 1202 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1129 fade font geometry hold iconName iconfile imFont imLocale inputMethod 1203 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1130 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont 1204 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1131 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier 1205 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
… …
1156Extensions that define extra resource or command line arguments also need 1230Extensions that define extra resource or command line arguments also need
1157to call this method to access their values. 1231to call this method to access their values.
1158 1232
1159If the method is called on an extension object (basically, from an 1233If the method is called on an extension object (basically, from an
1160extension), then the special prefix C<%.> will be replaced by the name of 1234extension), then the special prefix C<%.> will be replaced by the name of
1161the extension and a dot, and the lone string C<%> will be replcaed by the 1235the extension and a dot, and the lone string C<%> will be replaced by the
1162extension name itself. This makes it possible to code extensions so you 1236extension name itself. This makes it possible to code extensions so you
1163can rename them and get a new set of commandline switches and resources 1237can rename them and get a new set of commandline switches and resources
1164without having to change the actual code. 1238without having to change the actual code.
1165 1239
1166This method should only be called during the C<on_start> hook, as there is 1240This method should only be called during the C<on_start> hook, as there is
… …
1184} 1258}
1185 1259
1186=item $success = $term->parse_keysym ($key, $octets) 1260=item $success = $term->parse_keysym ($key, $octets)
1187 1261
1188Adds a key binding exactly as specified via a resource. See the 1262Adds a key binding exactly as specified via a resource. See the
1189C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1263C<keysym> resource in the urxvt(1) manpage.
1190 1264
1191=item $term->register_command ($keysym, $modifiermask, $string) 1265=item $term->register_command ($keysym, $modifiermask, $string)
1192 1266
1193Adds a key binding. This is a lower level api compared to 1267Adds a key binding. This is a lower level api compared to
1194C<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
… …
1624} 1698}
1625 1699
1626sub urxvt::line::t { 1700sub urxvt::line::t {
1627 my ($self) = @_; 1701 my ($self) = @_;
1628 1702
1629 if (@_ > 1) 1703 if (@_ > 1) {
1630 {
1631 $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})
1632 for $self->{beg} .. $self->{end}; 1705 for $self->{beg} .. $self->{end};
1633 } 1706 }
1634 1707
1635 defined wantarray && 1708 defined wantarray &&
1636 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1709 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1637 0, $self->{len} 1710 0, $self->{len}
1638} 1711}
1639 1712
1640sub urxvt::line::r { 1713sub urxvt::line::r {
1641 my ($self) = @_; 1714 my ($self) = @_;
1642 1715
1643 if (@_ > 1) 1716 if (@_ > 1) {
1644 {
1645 $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})
1646 for $self->{beg} .. $self->{end}; 1718 for $self->{beg} .. $self->{end};
1647 } 1719 }
1648 1720
1649 if (defined wantarray) { 1721 if (defined wantarray) {
1650 my $rend = [ 1722 my $rend = [
1651 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1723 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1652 ]; 1724 ];

Diff Legend

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