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.106 by root, Wed Jan 18 19:44:22 2006 UTC vs.
Revision 1.141 by root, Mon Jul 3 19:11:41 2006 UTC

34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
39 43
40=over 4 44=over 4
41 45
42=item selection (enabled by default) 46=item selection (enabled by default)
43 47
63the match. For example, the followign adds a regex that matches everything 67the match. For example, the followign adds a regex that matches everything
64between two vertical bars: 68between two vertical bars:
65 69
66 URxvt.selection.pattern-0: \\|([^|]+)\\| 70 URxvt.selection.pattern-0: \\|([^|]+)\\|
67 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: ^(/[^:]+):\
78
68You 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
69interesting uses, such as parsing a line from beginning to end. 80interesting uses, such as parsing a line from beginning to end.
70 81
71This extension also offers following bindable keyboard commands: 82This extension also offers following bindable keyboard commands:
72 83
83=item option-popup (enabled by default) 94=item option-popup (enabled by default)
84 95
85Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at 96Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
86runtime. 97runtime.
87 98
99Other extensions can extend this popup menu by pushing a code reference
100onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
101popup is being displayed.
102
103It's sole argument is the popup menu, which can be modified. It should
104either return nothing or a string, the initial boolean value and a code
105reference. The string will be used as button text and the code reference
106will be called when the toggle changes, with the new boolean value as
107first argument.
108
109The following will add an entry C<myoption> that changes
110C<$self->{myoption}>:
111
112 push @{ $self->{term}{option_popup_hook} }, sub {
113 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
114 };
115
88=item selection-popup (enabled by default) 116=item selection-popup (enabled by default)
89 117
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection 118Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl 119text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content. 120evaluation, web-browser starting etc.), depending on content.
93 121
94Other extensions can extend this popup menu by pushing a code reference onto 122Other extensions can extend this popup menu by pushing a code reference
95C<@urxvt::ext::selection_popup::hook>, that is called whenever the popup is displayed. 123onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
124popup is being displayed.
96 125
97It's sole argument is the popup menu, which can be modified. The selection 126It's sole argument is the popup menu, which can be modified. The selection
98is in C<$_>, which can be used to decide wether to add something or not. 127is in C<$_>, which can be used to decide wether to add something or not.
99It should either return nothing or a string and a code reference. The 128It should either return nothing or a string and a code reference. The
100string will be used as button text and the code reference will be called 129string will be used as button text and the code reference will be called
102 131
103The following will add an entry C<a to b> that transforms all C<a>s in 132The following will add an entry C<a to b> that transforms all C<a>s in
104the selection to C<b>s, but only if the selection currently contains any 133the selection to C<b>s, but only if the selection currently contains any
105C<a>s: 134C<a>s:
106 135
107 push urxvt::ext::selection_popup::hook, sub { 136 push @{ $self->{term}{selection_popup_hook} }, sub {
108 /a/ ? ("a to be" => sub { s/a/b/g } 137 /a/ ? ("a to be" => sub { s/a/b/g }
109 : () 138 : ()
110 }; 139 };
111 140
112=item searchable-scrollback<hotkey> (enabled by default) 141=item searchable-scrollback<hotkey> (enabled by default)
122bottom. C<Escape> leaves search mode and returns to the point where search 151bottom. C<Escape> leaves search mode and returns to the point where search
123was started, while C<Enter> or C<Return> stay at the current position and 152was started, while C<Enter> or C<Return> stay at the current position and
124additionally stores the first match in the current line into the primary 153additionally stores the first match in the current line into the primary
125selection. 154selection.
126 155
156=item readline (enabled by default)
157
158A support package that tries to make editing with readline easier. At
159the moment, it reacts to clicking shift-left mouse button by trying to
160move the text cursor to this position. It does so by generating as many
161cursor-left or cursor-right keypresses as required (the this only works
162for programs that correctly support wide characters).
163
164To avoid too many false positives, this is only done when:
165
166=over 4
167
168=item - the tty is in ICANON state.
169
170=item - the text cursor is visible.
171
172=item - the primary screen is currently being displayed.
173
174=item - the mouse is on the same (multi-row-) line as the text cursor.
175
176=back
177
178The normal selection mechanism isn't disabled, so quick successive clicks
179might interfere with selection creation in harmless ways.
180
127=item selection-autotransform 181=item selection-autotransform
128 182
129This selection allows you to do automatic transforms on a selection 183This selection allows you to do automatic transforms on a selection
130whenever a selection is made. 184whenever a selection is made.
131 185
143 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ 197 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
144 198
145And this example matches the same,but replaces it with vi-commands you can 199And this example matches the same,but replaces it with vi-commands you can
146paste directly into your (vi :) editor: 200paste directly into your (vi :) editor:
147 201
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/ 202 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
149 203
150Of course, this can be modified to suit your needs and your editor :) 204Of course, this can be modified to suit your needs and your editor :)
151 205
152To expand the example above to typical perl error messages ("XXX at 206To expand the example above to typical perl error messages ("XXX at
153FILENAME line YYY."), you need a slightly more elaborate solution: 207FILENAME line YYY."), you need a slightly more elaborate solution:
154 208
155 URxvt.selection.pattern-0: ( at .*? line \\d+\\.) 209 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
156 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/ 210 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
157 211
158The first line tells the selection code to treat the unchanging part of 212The first line tells the selection code to treat the unchanging part of
159every error message as a selection pattern, and the second line transforms 213every error message as a selection pattern, and the second line transforms
160the message into vi commands to load the file. 214the message into vi commands to load the file.
215
216=item tabbed
217
218This transforms the terminal into a tabbar with additional terminals, that
219is, it implements what is commonly refered to as "tabbed terminal". The topmost line
220displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
221button per tab.
222
223Clicking a button will activate that tab. Pressing B<Shift-Left> and
224B<Shift-Right> will switch to the tab left or right of the current one,
225while B<Shift-Down> creates a new tab.
226
227The tabbar itself can be configured similarly to a normal terminal, but
228with a resource class of C<URxvt.tabbed>. In addition, it supports the
229following four resources (shown with defaults):
230
231 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
232 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
233 URxvt.tabbed.tab-fg: <colour-index, default 0>
234 URxvt.tabbed.tab-bg: <colour-index, default 1>
235
236See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
237indices.
161 238
162=item mark-urls 239=item mark-urls
163 240
164Uses per-line display filtering (C<on_line_update>) to underline urls and 241Uses per-line display filtering (C<on_line_update>) to underline urls and
165make them clickable. When middle-clicked, the program specified in the 242make them clickable. When middle-clicked, the program specified in the
166resource C<urlLauncher> (default C<x-www-browser>) will be started with 243resource C<urlLauncher> (default C<x-www-browser>) will be started with
167the URL as first argument. 244the URL as first argument.
168 245
246=item xim-onthespot
247
248This (experimental) perl extension implements OnTheSpot editing. It does
249not work perfectly, and some input methods don't seem to work well with
250OnTheSpot editing in general, but it seems to work at leats for SCIM and
251kinput2.
252
253You enable it by specifying this extension and a preedit style of
254C<OnTheSpot>, i.e.:
255
256 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
257
169=item automove-background 258=item automove-background
170 259
171This is basically a one-line extension that dynamically changes the background pixmap offset 260This is basically a very small extension that dynamically changes the
172to the window position, in effect creating the same effect as pseudo transparency with 261background pixmap offset to the window position, in effect creating the
173a custom pixmap. No scaling is supported in this mode. Exmaple: 262same effect as pseudo transparency with a custom pixmap. No scaling is
263supported in this mode. Exmaple:
174 264
175 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background 265 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
176 266
177=item block-graphics-to-ascii 267=item block-graphics-to-ascii
178 268
179A not very useful example of filtering all text output to the terminal, 269A not very useful example of filtering all text output to the terminal
180by replacing all line-drawing characters (U+2500 .. U+259F) by a 270by replacing all line-drawing characters (U+2500 .. U+259F) by a
181similar-looking ascii character. 271similar-looking ascii character.
182 272
183=item digital-clock 273=item digital-clock
184 274
185Displays a digital clock using the built-in overlay. 275Displays a digital clock using the built-in overlay.
186 276
187=item example-refresh-hooks 277=item remote-clipboard
188 278
189Displays a very simple digital clock in the upper right corner of the 279Somewhat of a misnomer, this extension adds two menu entries to the
190window. Illustrates overwriting the refresh callbacks to create your own 280selection popup that allows one ti run external commands to store the
191overlays or changes. 281selection somewhere and fetch it again.
282
283We use it to implement a "distributed selection mechanism", which just
284means that one command uploads the file to a remote server, and another
285reads it.
286
287The commands can be set using the C<URxvt.remote-selection.store> and
288C<URxvt.remote-selection.fetch> resources. The first should read the
289selection to store from STDIN (always in UTF-8), the second should provide
290the selection data on STDOUT (also in UTF-8).
291
292The defaults (which are likely useless to you) use rsh and cat:
293
294 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
295 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
192 296
193=item selection-pastebin 297=item selection-pastebin
194 298
195This is a little rarely useful extension that Uploads the selection as 299This is a little rarely useful extension that Uploads the selection as
196textfile to a remote site (or does other things). (The implementation is 300textfile to a remote site (or does other things). (The implementation is
216After a successful upload the selection will be replaced by the text given 320After a successful upload the selection will be replaced by the text given
217in the C<selection-pastebin-url> resource (again, the % is the placeholder 321in the C<selection-pastebin-url> resource (again, the % is the placeholder
218for the filename): 322for the filename):
219 323
220 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% 324 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
325
326=item example-refresh-hooks
327
328Displays a very simple digital clock in the upper right corner of the
329window. Illustrates overwriting the refresh callbacks to create your own
330overlays or changes.
221 331
222=back 332=back
223 333
224=head1 API DOCUMENTATION 334=head1 API DOCUMENTATION
225 335
259 369
260=back 370=back
261 371
262=head2 Extension Objects 372=head2 Extension Objects
263 373
264Very perl extension is a perl class. A separate perl object is created 374Every perl extension is a perl class. A separate perl object is created
265for each terminal and each extension and passed as the first parameter to 375for each terminal and each extension and passed as the first parameter to
266hooks. So extensions can use their C<$self> object without having to think 376hooks. So extensions can use their C<$self> object without having to think
267about other extensions, with the exception of methods and members that 377about other extensions, with the exception of methods and members that
268begin with an underscore character C<_>: these are reserved for internal 378begin with an underscore character C<_>: these are reserved for internal
269use. 379use.
298called whenever the relevant event happens. 408called whenever the relevant event happens.
299 409
300The first argument passed to them is an extension oject as described in 410The first argument passed to them is an extension oject as described in
301the in the C<Extension Objects> section. 411the in the C<Extension Objects> section.
302 412
303B<All> of these hooks must return a boolean value. If it is true, then the 413B<All> of these hooks must return a boolean value. If any of the called
304event counts as being I<consumed>, and the invocation of other hooks is 414hooks returns true, then the event counts as being I<consumed>, and the
305skipped, and the relevant action might not be carried out by the C++ code. 415relevant action might not be carried out by the C++ code.
306 416
307I<< When in doubt, return a false value (preferably C<()>). >> 417I<< When in doubt, return a false value (preferably C<()>). >>
308 418
309=over 4 419=over 4
310 420
311=item on_init $term 421=item on_init $term
312 422
313Called after a new terminal object has been initialized, but before 423Called after a new terminal object has been initialized, but before
314windows are created or the command gets run. Most methods are unsafe to 424windows are created or the command gets run. Most methods are unsafe to
315call or deliver senseless data, as terminal size and other characteristics 425call or deliver senseless data, as terminal size and other characteristics
316have not yet been determined. You can safely query and change resources, 426have not yet been determined. You can safely query and change resources
317though. 427and options, though. For many purposes the C<on_start> hook is a better
428place.
429
430=item on_start $term
431
432Called at the very end of initialisation of a new terminal, just before
433trying to map (display) the toplevel and returning to the mainloop.
434
435=item on_destroy $term
436
437Called whenever something tries to destroy terminal, when the terminal is
438still fully functional (not for long, though).
318 439
319=item on_reset $term 440=item on_reset $term
320 441
321Called after the screen is "reset" for any reason, such as resizing or 442Called after the screen is "reset" for any reason, such as resizing or
322control sequences. Here is where you can react on changes to size-related 443control sequences. Here is where you can react on changes to size-related
323variables. 444variables.
324 445
325=item on_start $term 446=item on_child_start $term, $pid
326 447
327Called at the very end of initialisation of a new terminal, just before 448Called just after the child process has been C<fork>ed.
328returning to the mainloop. 449
450=item on_child_exit $term, $status
451
452Called just after the child process has exited. C<$status> is the status
453from C<waitpid>.
329 454
330=item on_sel_make $term, $eventtime 455=item on_sel_make $term, $eventtime
331 456
332Called whenever a selection has been made by the user, but before the 457Called whenever a selection has been made by the user, but before the
333selection text is copied, so changes to the beginning, end or type of the 458selection text is copied, so changes to the beginning, end or type of the
369 494
370It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 495It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
371$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 496$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
372number of lines that will be in the scrollback buffer. 497number of lines that will be in the scrollback buffer.
373 498
499=item on_osc_seq $term, $op, $args
500
501Called on every OSC sequence and can be used to suppress it or modify its
502behaviour. The default should be to return an empty list. A true value
503suppresses execution of the request completely. Make sure you don't get
504confused by recursive invocations when you output an osc sequence within
505this callback.
506
507C<on_osc_seq_perl> should be used for new behaviour.
508
374=item on_osc_seq $term, $string 509=item on_osc_seq_perl $term, $string
375 510
376Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 511Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
377operating system command) is processed. Cursor position and other state 512operating system command) is processed. Cursor position and other state
378information is up-to-date when this happens. For interoperability, the 513information is up-to-date when this happens. For interoperability, the
379string should start with the extension name and a colon, to distinguish 514string should start with the extension name and a colon, to distinguish
420 555
421=item on_refresh_end $term 556=item on_refresh_end $term
422 557
423Called just after the screen gets redrawn. See C<on_refresh_begin>. 558Called just after the screen gets redrawn. See C<on_refresh_begin>.
424 559
425=item on_keyboard_command $term, $string 560=item on_user_command $term, $string
426 561
427Called whenever the user presses a key combination that has a 562Called whenever the a user-configured event is being activated (e.g. via
428C<perl:string> action bound to it (see description of the B<keysym> 563a C<perl:string> action bound to a key, see description of the B<keysym>
429resource in the @@RXVT_NAME@@(1) manpage). 564resource in the @@RXVT_NAME@@(1) manpage).
565
566The event is simply the action string. This interface is assumed to change
567slightly in the future.
568
569=item on_resize_all_windows $tern, $new_width, $new_height
570
571Called just after the new window size has been calculcated, but before
572windows are actually being resized or hints are being set. If this hook
573returns TRUE, setting of the window hints is being skipped.
430 574
431=item on_x_event $term, $event 575=item on_x_event $term, $event
432 576
433Called on every X event received on the vt window (and possibly other 577Called on every X event received on the vt window (and possibly other
434windows). Should only be used as a last resort. Most event structure 578windows). Should only be used as a last resort. Most event structure
444Called wheneever the window loses keyboard focus, before rxvt-unicode does 588Called wheneever the window loses keyboard focus, before rxvt-unicode does
445focus out processing. 589focus out processing.
446 590
447=item on_configure_notify $term, $event 591=item on_configure_notify $term, $event
448 592
593=item on_property_notify $term, $event
594
449=item on_key_press $term, $event, $keysym, $octets 595=item on_key_press $term, $event, $keysym, $octets
450 596
451=item on_key_release $term, $event, $keysym 597=item on_key_release $term, $event, $keysym
452 598
453=item on_button_press $term, $event 599=item on_button_press $term, $event
462 608
463Called whenever the corresponding X event is received for the terminal If 609Called whenever the corresponding X event is received for the terminal If
464the hook returns true, then the even will be ignored by rxvt-unicode. 610the hook returns true, then the even will be ignored by rxvt-unicode.
465 611
466The event is a hash with most values as named by Xlib (see the XEvent 612The event is a hash with most values as named by Xlib (see the XEvent
467manpage), with the additional members C<row> and C<col>, which are the row 613manpage), with the additional members C<row> and C<col>, which are the
468and column under the mouse cursor. 614(real, not screen-based) row and column under the mouse cursor.
469 615
470C<on_key_press> additionally receives the string rxvt-unicode would 616C<on_key_press> additionally receives the string rxvt-unicode would
471output, if any, in locale-specific encoding. 617output, if any, in locale-specific encoding.
472 618
473subwindow. 619subwindow.
620
621=item on_client_message $term, $event
622
623=item on_wm_protocols $term, $event
624
625=item on_wm_delete_window $term, $event
626
627Called when various types of ClientMessage events are received (all with
628format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
474 629
475=back 630=back
476 631
477=cut 632=cut
478 633
484use Scalar::Util (); 639use Scalar::Util ();
485use List::Util (); 640use List::Util ();
486 641
487our $VERSION = 1; 642our $VERSION = 1;
488our $TERM; 643our $TERM;
644our @TERM_INIT;
645our @TERM_EXT;
489our @HOOKNAME; 646our @HOOKNAME;
490our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 647our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
491our %OPTION; 648our %OPTION;
492 649
493our $LIBDIR; 650our $LIBDIR;
494our $RESNAME; 651our $RESNAME;
495our $RESCLASS; 652our $RESCLASS;
496our $RXVTNAME; 653our $RXVTNAME;
497 654
655our $NOCHAR = chr 0xffff;
656
498=head2 Variables in the C<urxvt> Package 657=head2 Variables in the C<urxvt> Package
499 658
500=over 4 659=over 4
501 660
502=item $urxvt::LIBDIR 661=item $urxvt::LIBDIR
514 673
515=item $urxvt::TERM 674=item $urxvt::TERM
516 675
517The current terminal. This variable stores the current C<urxvt::term> 676The current terminal. This variable stores the current C<urxvt::term>
518object, whenever a callback/hook is executing. 677object, whenever a callback/hook is executing.
678
679=item @urxvt::TERM_INIT
680
681All coderefs in this array will be called as methods of the next newly
682created C<urxvt::term> object (during the C<on_init> phase). The array
683gets cleared before the codereferences that were in it are being executed,
684so coderefs can push themselves onto it again if they so desire.
685
686This complements to the perl-eval commandline option, but gets executed
687first.
688
689=item @urxvt::TERM_EXT
690
691Works similar to C<@TERM_INIT>, but contains perl package/class names, which
692get registered as normal extensions after calling the hooks in C<@TERM_INIT>
693but before other extensions. Gets cleared just like C<@TERM_INIT>.
519 694
520=back 695=back
521 696
522=head2 Functions in the C<urxvt> Package 697=head2 Functions in the C<urxvt> Package
523 698
537 712
538Using this function has the advantage that its output ends up in the 713Using this function has the advantage that its output ends up in the
539correct place, e.g. on stderr of the connecting urxvtc client. 714correct place, e.g. on stderr of the connecting urxvtc client.
540 715
541Messages have a size limit of 1023 bytes currently. 716Messages have a size limit of 1023 bytes currently.
717
718=item @terms = urxvt::termlist
719
720Returns all urxvt::term objects that exist in this process, regardless of
721wether they are started, being destroyed etc., so be careful. Only term
722objects that have perl extensions attached will be returned (because there
723is no urxvt::term objet associated with others).
542 724
543=item $time = urxvt::NOW 725=item $time = urxvt::NOW
544 726
545Returns the "current time" (as per the event loop). 727Returns the "current time" (as per the event loop).
546 728
604Return the foreground/background colour index, respectively. 786Return the foreground/background colour index, respectively.
605 787
606=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 788=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
607 789
608=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 790=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
791
792=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
609 793
610Replace the foreground/background colour in the rendition mask with the 794Replace the foreground/background colour in the rendition mask with the
611specified one. 795specified one.
612 796
613=item $value = urxvt::GET_CUSTOM $rend 797=item $value = urxvt::GET_CUSTOM $rend
630 my $msg = join "", @_; 814 my $msg = join "", @_;
631 $msg .= "\n" 815 $msg .= "\n"
632 unless $msg =~ /\n$/; 816 unless $msg =~ /\n$/;
633 urxvt::warn ($msg); 817 urxvt::warn ($msg);
634 }; 818 };
635
636 # %ENV is the original startup environment
637 delete $ENV{IFS};
638 delete $ENV{CDPATH};
639 delete $ENV{BASH_ENV};
640 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
641} 819}
820
821no warnings 'utf8';
642 822
643my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 823my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
644 824
645sub verbose { 825sub verbose {
646 my ($level, $msg) = @_; 826 my ($level, $msg) = @_;
650my %extension_pkg; 830my %extension_pkg;
651 831
652# load a single script into its own package, once only 832# load a single script into its own package, once only
653sub extension_package($) { 833sub extension_package($) {
654 my ($path) = @_; 834 my ($path) = @_;
655
656 no strict 'refs';
657 835
658 $extension_pkg{$path} ||= do { 836 $extension_pkg{$path} ||= do {
659 $path =~ /([^\/\\]+)$/; 837 $path =~ /([^\/\\]+)$/;
660 my $pkg = $1; 838 my $pkg = $1;
661 $pkg =~ s/[^[:word:]]/_/g; 839 $pkg =~ s/[^[:word:]]/_/g;
664 verbose 3, "loading extension '$path' into package '$pkg'"; 842 verbose 3, "loading extension '$path' into package '$pkg'";
665 843
666 open my $fh, "<:raw", $path 844 open my $fh, "<:raw", $path
667 or die "$path: $!"; 845 or die "$path: $!";
668 846
669 @{"$pkg\::ISA"} = urxvt::term::extension::;
670
671 my $source = 847 my $source =
672 "package $pkg; use strict; use utf8;\n" 848 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
673 . "#line 1 \"$path\"\n{\n" 849 . "#line 1 \"$path\"\n{\n"
674 . (do { local $/; <$fh> }) 850 . (do { local $/; <$fh> })
675 . "\n};\n1"; 851 . "\n};\n1";
676 852
677 eval $source 853 eval $source
691 if ($htype == 0) { # INIT 867 if ($htype == 0) { # INIT
692 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 868 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
693 869
694 my %ext_arg; 870 my %ext_arg;
695 871
872 {
873 my @init = @TERM_INIT;
874 @TERM_INIT = ();
875 $_->($TERM) for @init;
876 my @pkg = @TERM_EXT;
877 @TERM_EXT = ();
878 $TERM->register_package ($_) for @pkg;
879 }
880
696 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 881 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
697 if ($_ eq "default") { 882 if ($_ eq "default") {
698 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 883 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
699 } elsif (/^-(.*)$/) { 884 } elsif (/^-(.*)$/) {
700 delete $ext_arg{$1}; 885 delete $ext_arg{$1};
701 } elsif (/^([^<]+)<(.*)>$/) { 886 } elsif (/^([^<]+)<(.*)>$/) {
702 push @{ $ext_arg{$1} }, $2; 887 push @{ $ext_arg{$1} }, $2;
703 } else { 888 } else {
704 $ext_arg{$_} ||= []; 889 $ext_arg{$_} ||= [];
705 } 890 }
706 } 891 }
707 892
708 while (my ($ext, $argv) = each %ext_arg) { 893 for my $ext (sort keys %ext_arg) {
709 my @files = grep -f $_, map "$_/$ext", @dirs; 894 my @files = grep -f $_, map "$_/$ext", @dirs;
710 895
711 if (@files) { 896 if (@files) {
712 $TERM->register_package (extension_package $files[0], $argv); 897 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
713 } else { 898 } else {
714 warn "perl extension '$ext' not found in perl library search path\n"; 899 warn "perl extension '$ext' not found in perl library search path\n";
715 } 900 }
716 } 901 }
717 902
723 908
724 if (my $cb = $TERM->{_hook}[$htype]) { 909 if (my $cb = $TERM->{_hook}[$htype]) {
725 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 910 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
726 if $verbosity >= 10; 911 if $verbosity >= 10;
727 912
728 keys %$cb; 913 for my $pkg (keys %$cb) {
729
730 while (my ($pkg, $cb) = each %$cb) {
731 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 914 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
732 and last; 915 $retval ||= $retval_;
733 916
734 if ($@) { 917 if ($@) {
735 $TERM->ungrab; # better to lose the grab than the session 918 $TERM->ungrab; # better to lose the grab than the session
736 warn $@; 919 warn $@;
737 } 920 }
750 } 933 }
751 934
752 $retval 935 $retval
753} 936}
754 937
755sub exec_async(@) { 938sub SET_COLOR($$$) {
756 my $pid = fork; 939 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
757
758 return
759 if !defined $pid or $pid;
760
761 %ENV = %{ $TERM->env };
762
763 exec @_;
764 _exit 255;
765} 940}
766 941
767# urxvt::term::extension 942# urxvt::term::extension
768 943
769package urxvt::term::extension; 944package urxvt::term::extension;
908# find on_xxx subs in the package and register them 1083# find on_xxx subs in the package and register them
909# as hooks 1084# as hooks
910sub register_package { 1085sub register_package {
911 my ($self, $pkg, $argv) = @_; 1086 my ($self, $pkg, $argv) = @_;
912 1087
1088 no strict 'refs';
1089
1090 urxvt::verbose 6, "register package $pkg to $self";
1091
1092 @{"$pkg\::ISA"} = urxvt::term::extension::;
1093
913 my $proxy = bless { 1094 my $proxy = bless {
914 _pkg => $pkg, 1095 _pkg => $pkg,
915 argv => $argv, 1096 argv => $argv,
916 }, $pkg; 1097 }, $pkg;
917 Scalar::Util::weaken ($proxy->{term} = $self); 1098 Scalar::Util::weaken ($proxy->{term} = $self);
932hash which defines the environment of the new terminal. 1113hash which defines the environment of the new terminal.
933 1114
934Croaks (and probably outputs an error message) if the new instance 1115Croaks (and probably outputs an error message) if the new instance
935couldn't be created. Returns C<undef> if the new instance didn't 1116couldn't be created. Returns C<undef> if the new instance didn't
936initialise perl, and the terminal object otherwise. The C<init> and 1117initialise perl, and the terminal object otherwise. The C<init> and
937C<start> hooks will be called during this call. 1118C<start> hooks will be called before this call returns, and are free to
1119refer to global data (which is race free).
938 1120
939=cut 1121=cut
940 1122
941sub new { 1123sub new {
942 my ($class, $env, @args) = @_; 1124 my ($class, $env, @args) = @_;
943 1125
1126 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1127 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1128
944 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1129 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
945} 1130}
946 1131
947=item $term->destroy 1132=item $term->destroy
948 1133
949Destroy the terminal object (close the window, free resources 1134Destroy the terminal object (close the window, free resources
950etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1135etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
951watchers (timers, io watchers) are still active. 1136watchers (timers, io watchers) are still active.
1137
1138=item $term->exec_async ($cmd[, @args])
1139
1140Works like the combination of the C<fork>/C<exec> builtins, which executes
1141("starts") programs in the background. This function takes care of setting
1142the user environment before exec'ing the command (e.g. C<PATH>) and should
1143be preferred over explicit calls to C<exec> or C<system>.
1144
1145Returns the pid of the subprocess or C<undef> on error.
1146
1147=cut
1148
1149sub exec_async {
1150 my $self = shift;
1151
1152 my $pid = fork;
1153
1154 return $pid
1155 if !defined $pid or $pid;
1156
1157 %ENV = %{ $self->env };
1158
1159 exec @_;
1160 urxvt::_exit 255;
1161}
952 1162
953=item $isset = $term->option ($optval[, $set]) 1163=item $isset = $term->option ($optval[, $set])
954 1164
955Returns true if the option specified by C<$optval> is enabled, and 1165Returns true if the option specified by C<$optval> is enabled, and
956optionally change it. All option values are stored by name in the hash 1166optionally change it. All option values are stored by name in the hash
1181 1391
1182Normally its not a good idea to use this function, as programs might be 1392Normally its not a good idea to use this function, as programs might be
1183confused by changes in cursor position or scrolling. Its useful inside a 1393confused by changes in cursor position or scrolling. Its useful inside a
1184C<on_add_lines> hook, though. 1394C<on_add_lines> hook, though.
1185 1395
1396=item $term->scr_change_screen ($screen)
1397
1398Switch to given screen - 0 primary, 1 secondary.
1399
1186=item $term->cmd_parse ($octets) 1400=item $term->cmd_parse ($octets)
1187 1401
1188Similar to C<scr_add_lines>, but the argument must be in the 1402Similar to C<scr_add_lines>, but the argument must be in the
1189locale-specific encoding of the terminal and can contain command sequences 1403locale-specific encoding of the terminal and can contain command sequences
1190(escape codes) that will be interpreted. 1404(escape codes) that will be interpreted.
1200Replaces the event mask of the pty watcher by the given event mask. Can 1414Replaces the event mask of the pty watcher by the given event mask. Can
1201be used to suppress input and output handling to the pty/tty. See the 1415be used to suppress input and output handling to the pty/tty. See the
1202description of C<< urxvt::timer->events >>. Make sure to always restore 1416description of C<< urxvt::timer->events >>. Make sure to always restore
1203the previous value. 1417the previous value.
1204 1418
1419=item $fd = $term->pty_fd
1420
1421Returns the master file descriptor for the pty in use, or C<-1> if no pty
1422is used.
1423
1205=item $windowid = $term->parent 1424=item $windowid = $term->parent
1206 1425
1207Return the window id of the toplevel window. 1426Return the window id of the toplevel window.
1208 1427
1209=item $windowid = $term->vt 1428=item $windowid = $term->vt
1215Adds the specified events to the vt event mask. Useful e.g. when you want 1434Adds the specified events to the vt event mask. Useful e.g. when you want
1216to receive pointer events all the times: 1435to receive pointer events all the times:
1217 1436
1218 $term->vt_emask_add (urxvt::PointerMotionMask); 1437 $term->vt_emask_add (urxvt::PointerMotionMask);
1219 1438
1439=item $term->focus_in
1440
1441=item $term->focus_out
1442
1443=item $term->key_press ($state, $keycode[, $time])
1444
1445=item $term->key_release ($state, $keycode[, $time])
1446
1447Deliver various fake events to to terminal.
1448
1220=item $window_width = $term->width 1449=item $window_width = $term->width
1221 1450
1222=item $window_height = $term->height 1451=item $window_height = $term->height
1223 1452
1224=item $font_width = $term->fwidth 1453=item $font_width = $term->fwidth
1254=item $env = $term->env 1483=item $env = $term->env
1255 1484
1256Returns a copy of the environment in effect for the terminal as a hashref 1485Returns a copy of the environment in effect for the terminal as a hashref
1257similar to C<\%ENV>. 1486similar to C<\%ENV>.
1258 1487
1488=item @envv = $term->envv
1489
1490Returns the environment as array of strings of the form C<VAR=VALUE>.
1491
1492=item @argv = $term->argv
1493
1494Return the argument vector as this terminal, similar to @ARGV, but
1495includes the program name as first element.
1496
1259=cut 1497=cut
1260 1498
1261sub env { 1499sub env {
1262 if (my $env = $_[0]->_env) {
1263 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1500 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1264 } else {
1265 +{ %ENV }
1266 }
1267} 1501}
1268 1502
1269=item $modifiermask = $term->ModLevel3Mask 1503=item $modifiermask = $term->ModLevel3Mask
1270 1504
1271=item $modifiermask = $term->ModMetaMask 1505=item $modifiermask = $term->ModMetaMask
1272 1506
1273=item $modifiermask = $term->ModNumLockMask 1507=item $modifiermask = $term->ModNumLockMask
1274 1508
1275Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1509Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1276AltGr), the meta key (often Alt) and the num lock key, if applicable. 1510AltGr), the meta key (often Alt) and the num lock key, if applicable.
1511
1512=item $screen = $term->current_screen
1513
1514Returns the currently displayed screen (0 primary, 1 secondary).
1515
1516=item $cursor_is_hidden = $term->hidden_cursor
1517
1518Returns wether the cursor is currently hidden or not.
1277 1519
1278=item $view_start = $term->view_start ([$newvalue]) 1520=item $view_start = $term->view_start ([$newvalue])
1279 1521
1280Returns the row number of the topmost displayed line. Maximum value is 1522Returns the row number of the topmost displayed line. Maximum value is
1281C<0>, which displays the normal terminal contents. Lower values scroll 1523C<0>, which displays the normal terminal contents. Lower values scroll
1301line, starting at column C<$start_col> (default C<0>), which is useful 1543line, starting at column C<$start_col> (default C<0>), which is useful
1302to replace only parts of a line. The font index in the rendition will 1544to replace only parts of a line. The font index in the rendition will
1303automatically be updated. 1545automatically be updated.
1304 1546
1305C<$text> is in a special encoding: tabs and wide characters that use more 1547C<$text> is in a special encoding: tabs and wide characters that use more
1306than one cell when displayed are padded with urxvt::NOCHAR characters 1548than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1307(C<chr 65535>). Characters with combining characters and other characters 1549characters. Characters with combining characters and other characters that
1308that do not fit into the normal tetx encoding will be replaced with 1550do not fit into the normal tetx encoding will be replaced with characters
1309characters in the private use area. 1551in the private use area.
1310 1552
1311You have to obey this encoding when changing text. The advantage is 1553You have to obey this encoding when changing text. The advantage is
1312that C<substr> and similar functions work on screen cells and not on 1554that C<substr> and similar functions work on screen cells and not on
1313characters. 1555characters.
1314 1556
1461=item $string = $term->special_decode $text 1703=item $string = $term->special_decode $text
1462 1704
1463Converts rxvt-unicodes text reprsentation into a perl string. See 1705Converts rxvt-unicodes text reprsentation into a perl string. See
1464C<< $term->ROW_t >> for details. 1706C<< $term->ROW_t >> for details.
1465 1707
1466=item $success = $term->grab_button ($button, $modifiermask) 1708=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1467 1709
1710=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1711
1468Registers a synchronous button grab. See the XGrabButton manpage. 1712Register/unregister a synchronous button grab. See the XGrabButton
1713manpage.
1469 1714
1470=item $success = $term->grab ($eventtime[, $sync]) 1715=item $success = $term->grab ($eventtime[, $sync])
1471 1716
1472Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1717Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1473synchronous (C<$sync> is true). Also remembers the grab timestampe. 1718synchronous (C<$sync> is true). Also remembers the grab timestampe.
1488=item $term->ungrab 1733=item $term->ungrab
1489 1734
1490Calls XUngrab for the most recent grab. Is called automatically on 1735Calls XUngrab for the most recent grab. Is called automatically on
1491evaluation errors, as it is better to lose the grab in the error case as 1736evaluation errors, as it is better to lose the grab in the error case as
1492the session. 1737the session.
1738
1739=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1740
1741=item $atom_name = $term->XGetAtomName ($atom)
1742
1743=item @atoms = $term->XListProperties ($window)
1744
1745=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1746
1747=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1748
1749=item $term->XDeleteProperty ($window, $property)
1750
1751=item $window = $term->DefaultRootWindow
1752
1753=item $term->XReparentWindow ($window, $parent, [$x, $y])
1754
1755=item $term->XMapWindow ($window)
1756
1757=item $term->XUnmapWindow ($window)
1758
1759=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1760
1761=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1762
1763=item $term->XChangeInput ($window, $add_events[, $del_events])
1764
1765Various X or X-related functions. The C<$term> object only serves as
1766the source of the display, otherwise those functions map more-or-less
1767directory onto the X functions of the same name.
1493 1768
1494=back 1769=back
1495 1770
1496=cut 1771=cut
1497 1772
1561 my ($self, $text, $cb) = @_; 1836 my ($self, $text, $cb) = @_;
1562 1837
1563 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1838 $self->add_item ({ type => "button", text => $text, activate => $cb});
1564} 1839}
1565 1840
1566=item $popup->add_toggle ($text, $cb, $initial_value) 1841=item $popup->add_toggle ($text, $initial_value, $cb)
1567 1842
1568Adds a toggle/checkbox item to the popup. Teh callback gets called 1843Adds a toggle/checkbox item to the popup. The callback gets called
1569whenever it gets toggled, with a boolean indicating its value as its first 1844whenever it gets toggled, with a boolean indicating its new value as its
1570argument. 1845first argument.
1571 1846
1572=cut 1847=cut
1573 1848
1574sub add_toggle { 1849sub add_toggle {
1575 my ($self, $text, $cb, $value) = @_; 1850 my ($self, $text, $value, $cb) = @_;
1576 1851
1577 my $item; $item = { 1852 my $item; $item = {
1578 type => "button", 1853 type => "button",
1579 text => " $text", 1854 text => " $text",
1580 value => $value, 1855 value => $value,
1617 delete $self->{term}{_destroy}{$self}; 1892 delete $self->{term}{_destroy}{$self};
1618 $self->{term}->ungrab; 1893 $self->{term}->ungrab;
1619} 1894}
1620 1895
1621=back 1896=back
1897
1898=cut
1899
1900package urxvt::watcher;
1901
1902@urxvt::timer::ISA = __PACKAGE__;
1903@urxvt::iow::ISA = __PACKAGE__;
1904@urxvt::pw::ISA = __PACKAGE__;
1905@urxvt::iw::ISA = __PACKAGE__;
1622 1906
1623=head2 The C<urxvt::timer> Class 1907=head2 The C<urxvt::timer> Class
1624 1908
1625This class implements timer watchers/events. Time is represented as a 1909This class implements timer watchers/events. Time is represented as a
1626fractional number of seconds since the epoch. Example: 1910fractional number of seconds since the epoch. Example:
1724 2008
1725Stop watching for events on the given filehandle. 2009Stop watching for events on the given filehandle.
1726 2010
1727=back 2011=back
1728 2012
2013=head2 The C<urxvt::iw> Class
2014
2015This class implements idle watchers, that get called automatically when
2016the process is idle. They should return as fast as possible, after doing
2017some useful work.
2018
2019=over 4
2020
2021=item $iw = new urxvt::iw
2022
2023Create a new idle watcher object in stopped state.
2024
2025=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2026
2027Set the callback to be called when the watcher triggers.
2028
2029=item $timer = $timer->start
2030
2031Start the watcher.
2032
2033=item $timer = $timer->stop
2034
2035Stop the watcher.
2036
2037=back
2038
2039=head2 The C<urxvt::pw> Class
2040
2041This class implements process watchers. They create an event whenever a
2042process exits, after which they stop automatically.
2043
2044 my $pid = fork;
2045 ...
2046 $term->{pw} = urxvt::pw
2047 ->new
2048 ->start ($pid)
2049 ->cb (sub {
2050 my ($pw, $exit_status) = @_;
2051 ...
2052 });
2053
2054=over 4
2055
2056=item $pw = new urxvt::pw
2057
2058Create a new process watcher in stopped state.
2059
2060=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2061
2062Set the callback to be called when the timer triggers.
2063
2064=item $pw = $timer->start ($pid)
2065
2066Tells the wqtcher to start watching for process C<$pid>.
2067
2068=item $pw = $pw->stop
2069
2070Stop the watcher.
2071
2072=back
2073
1729=head1 ENVIRONMENT 2074=head1 ENVIRONMENT
1730 2075
1731=head2 URXVT_PERL_VERBOSITY 2076=head2 URXVT_PERL_VERBOSITY
1732 2077
1733This variable controls the verbosity level of the perl extension. Higher 2078This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines