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.122 by root, Sat Jan 21 08:07:38 2006 UTC vs.
Revision 1.131 by root, Sun Jan 29 20:51:28 2006 UTC

… …
66contain at least one pair of capturing parentheses, which will be used for 66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything 67the match. For example, the followign adds a regex that matches everything
68between two vertical bars: 68between two vertical bars:
69 69
70 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71
72Another example: Programs I use often output "absolute path: " at the
73beginning of a line when they process multiple files. The following
74pattern matches the filename (note, there is a single space at the very
75end):
76
77 URxvt.selection.pattern-0: ^(/[^:]+):\
71 78
72You can look at the source of the selection extension to see more 79You can look at the source of the selection extension to see more
73interesting uses, such as parsing a line from beginning to end. 80interesting uses, such as parsing a line from beginning to end.
74 81
75This extension also offers following bindable keyboard commands: 82This extension also offers following bindable keyboard commands:
… …
127bottom. C<Escape> leaves search mode and returns to the point where search 134bottom. C<Escape> leaves search mode and returns to the point where search
128was started, while C<Enter> or C<Return> stay at the current position and 135was started, while C<Enter> or C<Return> stay at the current position and
129additionally stores the first match in the current line into the primary 136additionally stores the first match in the current line into the primary
130selection. 137selection.
131 138
132=item selection-autotransform 139=item readline (enabled by default)
133
134This selection allows you to do automatic transforms on a selection
135whenever a selection is made.
136
137It works by specifying perl snippets (most useful is a single C<s///>
138operator) that modify C<$_> as resources:
139
140 URxvt.selection-autotransform.0: transform
141 URxvt.selection-autotransform.1: transform
142 ...
143
144For example, the following will transform selections of the form
145C<filename:number>, often seen in compiler messages, into C<vi +$filename
146$word>:
147
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
149
150And this example matches the same,but replaces it with vi-commands you can
151paste directly into your (vi :) editor:
152
153 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
154
155Of course, this can be modified to suit your needs and your editor :)
156
157To expand the example above to typical perl error messages ("XXX at
158FILENAME line YYY."), you need a slightly more elaborate solution:
159
160 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
161 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
162
163The first line tells the selection code to treat the unchanging part of
164every error message as a selection pattern, and the second line transforms
165the message into vi commands to load the file.
166
167=item readline
168 140
169A support package that tries to make editing with readline easier. At the 141A support package that tries to make editing with readline easier. At the
170moment, it reacts to clicking with the left mouse button by trying to 142moment, it reacts to clicking with the left mouse button by trying to
171move the text cursor to this position. It does so by generating as many 143move the text cursor to this position. It does so by generating as many
172cursor-left or cursor-right keypresses as required (the this only works 144cursor-left or cursor-right keypresses as required (the this only works
… …
174 146
175To avoid too many false positives, this is only done when: 147To avoid too many false positives, this is only done when:
176 148
177=over 4 149=over 4
178 150
151=item - the tty is in ICANON state.
152
153=item - the text cursor is visible.
154
155=item - the primary screen is currently being displayed.
156
179=item - the mouse is on the same (multi-row-) line as the text cursor. 157=item - the mouse is on the same (multi-row-) line as the text cursor.
180
181=item - the primary screen is currently being displayed.
182
183=item - the text cursor is visible.
184 158
185=back 159=back
186 160
187The normal selection mechanism isn't disabled, so quick successive clicks 161The normal selection mechanism isn't disabled, so quick successive clicks
188might interfere with selection creation in harmless ways. 162might interfere with selection creation in harmless ways.
163
164=item selection-autotransform
165
166This selection allows you to do automatic transforms on a selection
167whenever a selection is made.
168
169It works by specifying perl snippets (most useful is a single C<s///>
170operator) that modify C<$_> as resources:
171
172 URxvt.selection-autotransform.0: transform
173 URxvt.selection-autotransform.1: transform
174 ...
175
176For example, the following will transform selections of the form
177C<filename:number>, often seen in compiler messages, into C<vi +$filename
178$word>:
179
180 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
181
182And this example matches the same,but replaces it with vi-commands you can
183paste directly into your (vi :) editor:
184
185 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
186
187Of course, this can be modified to suit your needs and your editor :)
188
189To expand the example above to typical perl error messages ("XXX at
190FILENAME line YYY."), you need a slightly more elaborate solution:
191
192 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
193 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
194
195The first line tells the selection code to treat the unchanging part of
196every error message as a selection pattern, and the second line transforms
197the message into vi commands to load the file.
189 198
190=item tabbed 199=item tabbed
191 200
192This transforms the terminal into a tabbar with additional terminals, that 201This transforms the terminal into a tabbar with additional terminals, that
193is, it implements what is commonly refered to as "tabbed terminal". The topmost line 202is, it implements what is commonly refered to as "tabbed terminal". The topmost line
… …
203Uses per-line display filtering (C<on_line_update>) to underline urls and 212Uses per-line display filtering (C<on_line_update>) to underline urls and
204make them clickable. When middle-clicked, the program specified in the 213make them clickable. When middle-clicked, the program specified in the
205resource C<urlLauncher> (default C<x-www-browser>) will be started with 214resource C<urlLauncher> (default C<x-www-browser>) will be started with
206the URL as first argument. 215the URL as first argument.
207 216
217=item xim-onthespot
218
219This (experimental) perl extension implements OnTheSpot editing. It does
220not work perfectly, and some input methods don't seem to work well with
221OnTheSpot editing in general, but it seems to work at leats for SCIM and
222kinput2.
223
224You enable it by specifying this extension and a preedit style of
225C<OnTheSpot>, i.e.:
226
227 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
228
208=item automove-background 229=item automove-background
209 230
210This is basically a one-line extension that dynamically changes the background pixmap offset 231This is basically a one-line extension that dynamically changes the background pixmap offset
211to the window position, in effect creating the same effect as pseudo transparency with 232to the window position, in effect creating the same effect as pseudo transparency with
212a custom pixmap. No scaling is supported in this mode. Exmaple: 233a custom pixmap. No scaling is supported in this mode. Exmaple:
… …
221 242
222=item digital-clock 243=item digital-clock
223 244
224Displays a digital clock using the built-in overlay. 245Displays a digital clock using the built-in overlay.
225 246
226=item example-refresh-hooks 247=item remote-clipboard
227 248
228Displays a very simple digital clock in the upper right corner of the 249Somewhat of a misnomer, this extension adds two menu entries to the
229window. Illustrates overwriting the refresh callbacks to create your own 250selection popup that allows one ti run external commands to store the
230overlays or changes. 251selection somewhere and fetch it again.
252
253We use it to implement a "distributed selection mechanism", which just
254means that one command uploads the file to a remote server, and another
255reads it.
256
257The commands can be set using the C<URxvt.remote-selection.store> and
258C<URxvt.remote-selection.fetch> resources. The first should read the
259selection to store from STDIN (always in UTF-8), the second should provide
260the selection data on STDOUT (also in UTF-8).
261
262The defaults (which are likely useless to you) use rsh and cat:
263
264 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
265 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
231 266
232=item selection-pastebin 267=item selection-pastebin
233 268
234This is a little rarely useful extension that Uploads the selection as 269This is a little rarely useful extension that Uploads the selection as
235textfile to a remote site (or does other things). (The implementation is 270textfile to a remote site (or does other things). (The implementation is
… …
255After a successful upload the selection will be replaced by the text given 290After a successful upload the selection will be replaced by the text given
256in the C<selection-pastebin-url> resource (again, the % is the placeholder 291in the C<selection-pastebin-url> resource (again, the % is the placeholder
257for the filename): 292for the filename):
258 293
259 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 294 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
295
296=item example-refresh-hooks
297
298Displays a very simple digital clock in the upper right corner of the
299window. Illustrates overwriting the refresh callbacks to create your own
300overlays or changes.
260 301
261=back 302=back
262 303
263=head1 API DOCUMENTATION 304=head1 API DOCUMENTATION
264 305
… …
361Called at the very end of initialisation of a new terminal, just before 402Called at the very end of initialisation of a new terminal, just before
362trying to map (display) the toplevel and returning to the mainloop. 403trying to map (display) the toplevel and returning to the mainloop.
363 404
364=item on_destroy $term 405=item on_destroy $term
365 406
366Called whenever something tries to destroy terminal, before doing anything 407Called whenever something tries to destroy terminal, when the terminal is
367yet. If this hook returns true, then destruction is skipped, but this is 408still fully functional (not for long, though).
368rarely a good idea.
369 409
370=item on_reset $term 410=item on_reset $term
371 411
372Called after the screen is "reset" for any reason, such as resizing or 412Called after the screen is "reset" for any reason, such as resizing or
373control sequences. Here is where you can react on changes to size-related 413control sequences. Here is where you can react on changes to size-related
… …
475 515
476=item on_refresh_end $term 516=item on_refresh_end $term
477 517
478Called just after the screen gets redrawn. See C<on_refresh_begin>. 518Called just after the screen gets redrawn. See C<on_refresh_begin>.
479 519
480=item on_keyboard_command $term, $string 520=item on_user_command $term, $string
481 521
482Called whenever the user presses a key combination that has a 522Called whenever the a user-configured event is being activated (e.g. via
483C<perl:string> action bound to it (see description of the B<keysym> 523a C<perl:string> action bound to a key, see description of the B<keysym>
484resource in the @@RXVT_NAME@@(1) manpage). 524resource in the @@RXVT_NAME@@(1) manpage).
525
526The event is simply the action string. This interface is assumed to change
527slightly in the future.
485 528
486=item on_x_event $term, $event 529=item on_x_event $term, $event
487 530
488Called on every X event received on the vt window (and possibly other 531Called on every X event received on the vt window (and possibly other
489windows). Should only be used as a last resort. Most event structure 532windows). Should only be used as a last resort. Most event structure
… …
561our $LIBDIR; 604our $LIBDIR;
562our $RESNAME; 605our $RESNAME;
563our $RESCLASS; 606our $RESCLASS;
564our $RXVTNAME; 607our $RXVTNAME;
565 608
566our $NOCHAR = chr 0xfffe; 609our $NOCHAR = chr 0xffff;
567 610
568=head2 Variables in the C<urxvt> Package 611=head2 Variables in the C<urxvt> Package
569 612
570=over 4 613=over 4
571 614
… …
623 666
624Using this function has the advantage that its output ends up in the 667Using this function has the advantage that its output ends up in the
625correct place, e.g. on stderr of the connecting urxvtc client. 668correct place, e.g. on stderr of the connecting urxvtc client.
626 669
627Messages have a size limit of 1023 bytes currently. 670Messages have a size limit of 1023 bytes currently.
671
672=item @terms = urxvt::termlist
673
674Returns all urxvt::term objects that exist in this process, regardless of
675wether they are started, being destroyed etc., so be careful. Only term
676objects that have perl extensions attached will be returned (because there
677is no urxvt::term objet associated with others).
628 678
629=item $time = urxvt::NOW 679=item $time = urxvt::NOW
630 680
631Returns the "current time" (as per the event loop). 681Returns the "current time" (as per the event loop).
632 682
… …
718 unless $msg =~ /\n$/; 768 unless $msg =~ /\n$/;
719 urxvt::warn ($msg); 769 urxvt::warn ($msg);
720 }; 770 };
721} 771}
722 772
773no warnings 'utf8';
774
723my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 775my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
724 776
725sub verbose { 777sub verbose {
726 my ($level, $msg) = @_; 778 my ($level, $msg) = @_;
727 warn "$msg\n" if $level <= $verbosity; 779 warn "$msg\n" if $level <= $verbosity;
… …
743 795
744 open my $fh, "<:raw", $path 796 open my $fh, "<:raw", $path
745 or die "$path: $!"; 797 or die "$path: $!";
746 798
747 my $source = 799 my $source =
748 "package $pkg; use strict; use utf8;\n" 800 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
749 . "#line 1 \"$path\"\n{\n" 801 . "#line 1 \"$path\"\n{\n"
750 . (do { local $/; <$fh> }) 802 . (do { local $/; <$fh> })
751 . "\n};\n1"; 803 . "\n};\n1";
752 804
753 eval $source 805 eval $source
… …
778 $TERM->register_package ($_) for @pkg; 830 $TERM->register_package ($_) for @pkg;
779 } 831 }
780 832
781 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 833 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
782 if ($_ eq "default") { 834 if ($_ eq "default") {
783 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 835 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
784 } elsif (/^-(.*)$/) { 836 } elsif (/^-(.*)$/) {
785 delete $ext_arg{$1}; 837 delete $ext_arg{$1};
786 } elsif (/^([^<]+)<(.*)>$/) { 838 } elsif (/^([^<]+)<(.*)>$/) {
787 push @{ $ext_arg{$1} }, $2; 839 push @{ $ext_arg{$1} }, $2;
788 } else { 840 } else {
… …
1011hash which defines the environment of the new terminal. 1063hash which defines the environment of the new terminal.
1012 1064
1013Croaks (and probably outputs an error message) if the new instance 1065Croaks (and probably outputs an error message) if the new instance
1014couldn't be created. Returns C<undef> if the new instance didn't 1066couldn't be created. Returns C<undef> if the new instance didn't
1015initialise perl, and the terminal object otherwise. The C<init> and 1067initialise perl, and the terminal object otherwise. The C<init> and
1016C<start> hooks will be called during this call. 1068C<start> hooks will be called before this call returns, and are free to
1069refer to global data (which is race free).
1017 1070
1018=cut 1071=cut
1019 1072
1020sub new { 1073sub new {
1021 my ($class, $env, @args) = @_; 1074 my ($class, $env, @args) = @_;
1022 1075
1076 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1077 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1078
1023 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1079 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1024} 1080}
1025 1081
1026=item $term->destroy 1082=item $term->destroy
1027 1083
1028Destroy the terminal object (close the window, free resources 1084Destroy the terminal object (close the window, free resources
… …
1308Replaces the event mask of the pty watcher by the given event mask. Can 1364Replaces the event mask of the pty watcher by the given event mask. Can
1309be used to suppress input and output handling to the pty/tty. See the 1365be used to suppress input and output handling to the pty/tty. See the
1310description of C<< urxvt::timer->events >>. Make sure to always restore 1366description of C<< urxvt::timer->events >>. Make sure to always restore
1311the previous value. 1367the previous value.
1312 1368
1369=item $fd = $term->pty_fd
1370
1371Returns the master file descriptor for the pty in use, or C<-1> if no pty
1372is used.
1373
1313=item $windowid = $term->parent 1374=item $windowid = $term->parent
1314 1375
1315Return the window id of the toplevel window. 1376Return the window id of the toplevel window.
1316 1377
1317=item $windowid = $term->vt 1378=item $windowid = $term->vt
… …
1416If C<$new_text> is specified, it will replace characters in the current 1477If C<$new_text> is specified, it will replace characters in the current
1417line, starting at column C<$start_col> (default C<0>), which is useful 1478line, starting at column C<$start_col> (default C<0>), which is useful
1418to replace only parts of a line. The font index in the rendition will 1479to replace only parts of a line. The font index in the rendition will
1419automatically be updated. 1480automatically be updated.
1420 1481
1421C<$text> is in a special encoding: tabs and wide characters that use 1482C<$text> is in a special encoding: tabs and wide characters that use more
1422more than one cell when displayed are padded with C<$urxvt::NOCHAR> 1483than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1423characters. Characters with combining characters and other characters that 1484characters. Characters with combining characters and other characters that
1424do not fit into the normal tetx encoding will be replaced with characters 1485do not fit into the normal tetx encoding will be replaced with characters
1425in the private use area. 1486in the private use area.
1426 1487
1427You have to obey this encoding when changing text. The advantage is 1488You have to obey this encoding when changing text. The advantage is
… …
1577=item $string = $term->special_decode $text 1638=item $string = $term->special_decode $text
1578 1639
1579Converts rxvt-unicodes text reprsentation into a perl string. See 1640Converts rxvt-unicodes text reprsentation into a perl string. See
1580C<< $term->ROW_t >> for details. 1641C<< $term->ROW_t >> for details.
1581 1642
1582=item $success = $term->grab_button ($button, $modifiermask) 1643=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1583 1644
1645=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1646
1584Registers a synchronous button grab. See the XGrabButton manpage. 1647Register/unregister a synchronous button grab. See the XGrabButton
1648manpage.
1585 1649
1586=item $success = $term->grab ($eventtime[, $sync]) 1650=item $success = $term->grab ($eventtime[, $sync])
1587 1651
1588Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1652Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1589synchronous (C<$sync> is true). Also remembers the grab timestampe. 1653synchronous (C<$sync> is true). Also remembers the grab timestampe.

Diff Legend

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