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.231 by root, Sun Apr 27 20:26:28 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
22Everytime 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' 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"
32and "perl-ext-common" resources to the empty string.
33
31=head1 PREPACKAGED EXTENSIONS 34=head1 PREPACKAGED EXTENSIONS
32 35
33This section describes the extensions delivered with this release. You can 36A number of extensions are delivered with this release. You can find them
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37in F<< <libdir>/urxvt/perl/ >>, and the documentation can be viewed using
38F<< man urxvt-<EXTENSIONNAME> >>.
35 39
36You can activate them like this: 40You can activate them like this:
37 41
38 @@RXVT_NAME@@ -pe <extensionname> 42 urxvt -pe <extensionname>
39 43
40=over 4 44Or by adding them to the resource for extensions loaded by default:
41 45
42=item selection (enabled by default) 46 URxvt.perl-ext-common: default,selection-autotransform
43 47
44(More) intelligent selection. This extension tries to be more intelligent 48Extensions that add command line parameters or resources on their own are
45when the user extends selections (double-click and further clicks). Right 49loaded automatically when used.
46now, it tries to select words, urls and complete shell-quoted
47arguments, which is very convenient, too, if your F<ls> supports
48C<--quoting-style=shell>.
49
50A double-click usually selects the word under the cursor, further clicks
51will enlarge the selection.
52
53The selection works by trying to match a number of regexes and displaying
54them in increasing order of length. You can add your own regexes by
55specifying resources of the form:
56
57 URxvt.selection.pattern-0: perl-regex
58 URxvt.selection.pattern-1: perl-regex
59 ...
60
61The index number (0, 1...) must not have any holes, and each regex must
62contain at least one pair of capturing parentheses, which will be used for
63the match. For example, the followign adds a regex that matches everything
64between two vertical bars:
65
66 URxvt.selection.pattern-0: \\|([^|]+)\\|
67
68You can look at the source of the selection extension to see more
69interesting uses, such as parsing a line from beginning to end.
70
71This extension also offers following bindable keyboard commands:
72
73=over 4
74
75=item rot13
76
77Rot-13 the selection when activated. Used via keyboard trigger:
78
79 URxvt.keysym.C-M-r: perl:selection:rot13
80
81=back
82
83=item option-popup (enabled by default)
84
85Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
86runtime.
87
88=item selection-popup (enabled by default)
89
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content.
93
94Other extensions can extend this popup menu by pushing a code reference onto
95C<@urxvt::ext::selection_popup::hook>, that is called whenever the popup is displayed.
96
97It'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.
99It 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
101when the button gets activated and should transform C<$_>.
102
103The 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
105C<a>s:
106
107 push urxvt::ext::selection_popup::hook, sub {
108 /a/ ? ("a to be" => sub { s/a/b/g }
109 : ()
110 };
111
112=item searchable-scrollback<hotkey> (enabled by default)
113
114Adds regex search functionality to the scrollback buffer, triggered
115by a hotkey (default: C<M-s>). While in search mode, normal terminal
116input/output is suspended and a regex is displayed at the bottom of the
117screen.
118
119Inputting characters appends them to the regex and continues incremental
120search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
121search upwards/downwards in the scrollback buffer, C<End> jumps to the
122bottom. 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
124additionally stores the first match in the current line into the primary
125selection.
126
127=item selection-autotransform
128
129This selection allows you to do automatic transforms on a selection
130whenever a selection is made.
131
132It works by specifying perl snippets (most useful is a single C<s///>
133operator) that modify C<$_> as resources:
134
135 URxvt.selection-autotransform.0: transform
136 URxvt.selection-autotransform.1: transform
137 ...
138
139For example, the following will transform selections of the form
140C<filename:number>, often seen in compiler messages, into C<vi +$filename
141$word>:
142
143 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
144
145And this example matches the same,but replaces it with vi-commands you can
146paste directly into your (vi :) editor:
147
148 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
149
150Of course, this can be modified to suit your needs and your editor :)
151
152To expand the example above to typical perl error messages ("XXX at
153FILENAME line YYY."), you need a slightly more elaborate solution:
154
155 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
156 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
157
158The first line tells the selection code to treat the unchanging part of
159every error message as a selection pattern, and the second line transforms
160the message into vi commands to load the file.
161
162=item mark-urls
163
164Uses per-line display filtering (C<on_line_update>) to underline urls and
165make them clickable. When middle-clicked, the program specified in the
166resource C<urlLauncher> (default C<x-www-browser>) will be started with
167the URL as first argument.
168
169=item automove-background
170
171This is basically a one-line extension that dynamically changes the background pixmap offset
172to the window position, in effect creating the same effect as pseudo transparency with
173a custom pixmap. No scaling is supported in this mode. Exmaple:
174
175 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
176
177=item block-graphics-to-ascii
178
179A not very useful example of filtering all text output to the terminal,
180by replacing all line-drawing characters (U+2500 .. U+259F) by a
181similar-looking ascii character.
182
183=item digital-clock
184
185Displays a digital clock using the built-in overlay.
186
187=item example-refresh-hooks
188
189Displays a very simple digital clock in the upper right corner of the
190window. Illustrates overwriting the refresh callbacks to create your own
191overlays or changes.
192
193=item selection-pastebin
194
195This is a little rarely useful extension that Uploads the selection as
196textfile to a remote site (or does other things). (The implementation is
197not currently secure for use in a multiuser environment as it writes to
198F</tmp> directly.).
199
200It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
201i.e.
202
203 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
204
205Pressing this combination runs a command with C<%> replaced by the name of
206the textfile. This command can be set via a resource:
207
208 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
209
210And the default is likely not useful to anybody but the few people around
211here :)
212
213The name of the textfile is the hex encoded md5 sum of the selection, so
214the same content should lead to the same filename.
215
216After a successful upload the selection will be replaced by the text given
217in the C<selection-pastebin-url> resource (again, the % is the placeholder
218for the filename):
219
220 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
221
222=back
223 50
224=head1 API DOCUMENTATION 51=head1 API DOCUMENTATION
225 52
226=head2 General API Considerations 53=head2 General API Considerations
227 54
241 68
242=over 4 69=over 4
243 70
244=item $text 71=item $text
245 72
246Rxvt-unicodes special way of encoding text, where one "unicode" character 73Rxvt-unicode's special way of encoding text, where one "unicode" character
247always represents one screen cell. See L<ROW_t> for a discussion of this format. 74always represents one screen cell. See L<ROW_t> for a discussion of this format.
248 75
249=item $string 76=item $string
250 77
251A perl text string, with an emphasis on I<text>. It can store all unicode 78A perl text string, with an emphasis on I<text>. It can store all unicode
255=item $octets 82=item $octets
256 83
257Either binary data or - more common - a text string encoded in a 84Either binary data or - more common - a text string encoded in a
258locale-specific way. 85locale-specific way.
259 86
87=item $keysym
88
89an integer that is a valid X11 keysym code. You can convert a string
90into a keysym and viceversa by using C<XStringToKeysym> and
91C<XKeysymToString>.
92
260=back 93=back
261 94
262=head2 Extension Objects 95=head2 Extension Objects
263 96
264Very perl extension is a perl class. A separate perl object is created 97Every 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 98for each terminal, and each terminal has its own set of extension objects,
266hooks. So extensions can use their C<$self> object without having to think 99which are passed as the first parameter to hooks. So extensions can use
267about other extensions, with the exception of methods and members that 100their C<$self> object without having to think about clashes with other
101extensions or other terminals, with the exception of methods and members
268begin with an underscore character C<_>: these are reserved for internal 102that begin with an underscore character C<_>: these are reserved for
269use. 103internal use.
270 104
271Although 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
272C<urxvt::term> class on this object. 106C<urxvt::term> class on this object.
273 107
274It has the following methods and data members: 108Additional methods only supported for extension objects are described in
275 109the C<urxvt::extension> section below.
276=over 4
277
278=item $urxvt_term = $self->{term}
279
280Returns the C<urxvt::term> object associated with this instance of the
281extension. This member I<must not> be changed in any way.
282
283=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
284
285Dynamically enable the given hooks (named without the C<on_> prefix) for
286this extension, replacing any previous hook. This is useful when you want
287to overwrite time-critical hooks only temporarily.
288
289=item $self->disable ($hook_name[, $hook_name..])
290
291Dynamically disable the given hooks.
292
293=back
294 110
295=head2 Hooks 111=head2 Hooks
296 112
297The following subroutines can be declared in extension files, and will be 113The following subroutines can be declared in extension files, and will be
298called whenever the relevant event happens. 114called whenever the relevant event happens.
299 115
300The first argument passed to them is an extension oject as described in 116The first argument passed to them is an extension object as described in
301the in the C<Extension Objects> section. 117the in the C<Extension Objects> section.
302 118
303B<All> of these hooks must return a boolean value. If it is true, then the 119B<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 120hooks 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. 121relevant action might not be carried out by the C++ code.
306 122
307I<< When in doubt, return a false value (preferably C<()>). >> 123I<< When in doubt, return a false value (preferably C<()>). >>
308 124
309=over 4 125=over 4
310 126
311=item on_init $term 127=item on_init $term
312 128
313Called after a new terminal object has been initialized, but before 129Called after a new terminal object has been initialized, but before
314windows are created or the command gets run. Most methods are unsafe to 130windows are created or the command gets run. Most methods are unsafe to
315call or deliver senseless data, as terminal size and other characteristics 131call or deliver senseless data, as terminal size and other characteristics
316have not yet been determined. You can safely query and change resources, 132have not yet been determined. You can safely query and change resources
317though. 133and options, though. For many purposes the C<on_start> hook is a better
134place.
135
136=item on_start $term
137
138Called at the very end of initialisation of a new terminal, just before
139trying to map (display) the toplevel and returning to the main loop.
140
141=item on_destroy $term
142
143Called whenever something tries to destroy terminal, when the terminal is
144still fully functional (not for long, though).
318 145
319=item on_reset $term 146=item on_reset $term
320 147
321Called after the screen is "reset" for any reason, such as resizing or 148Called 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 149control sequences. Here is where you can react on changes to size-related
323variables. 150variables.
324 151
325=item on_start $term 152=item on_child_start $term, $pid
326 153
327Called at the very end of initialisation of a new terminal, just before 154Called just after the child process has been C<fork>ed.
328returning to the mainloop. 155
156=item on_child_exit $term, $status
157
158Called just after the child process has exited. C<$status> is the status
159from C<waitpid>.
329 160
330=item on_sel_make $term, $eventtime 161=item on_sel_make $term, $eventtime
331 162
332Called whenever a selection has been made by the user, but before the 163Called 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 164selection text is copied, so changes to the beginning, end or type of the
340 171
341Called whenever a selection has been copied, but before the selection is 172Called whenever a selection has been copied, but before the selection is
342requested from the server. The selection text can be queried and changed 173requested from the server. The selection text can be queried and changed
343by calling C<< $term->selection >>. 174by calling C<< $term->selection >>.
344 175
345Returning a true value aborts selection grabbing. It will still be hilighted. 176Returning a true value aborts selection grabbing. It will still be highlighted.
346 177
347=item on_sel_extend $term 178=item on_sel_extend $term
348 179
349Called whenever the user tries to extend the selection (e.g. with a double 180Called whenever the user tries to extend the selection (e.g. with a double
350click) and is either supposed to return false (normal operation), or 181click) and is either supposed to return false (normal operation), or
351should extend the selection itelf and return true to suppress the built-in 182should extend the selection itself and return true to suppress the built-in
352processing. This can happen multiple times, as long as the callback 183processing. This can happen multiple times, as long as the callback
353returns true, it will be called on every further click by the user and is 184returns true, it will be called on every further click by the user and is
354supposed to enlarge the selection more and more, if possible. 185supposed to enlarge the selection more and more, if possible.
355 186
356See the F<selection> example extension. 187See the F<selection> example extension.
357 188
358=item on_view_change $term, $offset 189=item on_view_change $term, $offset
359 190
360Called whenever the view offset changes, i..e the user or program 191Called whenever the view offset changes, i.e. the user or program
361scrolls. Offset C<0> means display the normal terminal, positive values 192scrolls. Offset C<0> means display the normal terminal, positive values
362show this many lines of scrollback. 193show this many lines of scrollback.
363 194
364=item on_scroll_back $term, $lines, $saved 195=item on_scroll_back $term, $lines, $saved
365 196
369 200
370It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 201It 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 202$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
372number of lines that will be in the scrollback buffer. 203number of lines that will be in the scrollback buffer.
373 204
374=item on_osc_seq $term, $string 205=item on_osc_seq $term, $op, $args, $resp
206
207Called on every OSC sequence and can be used to suppress it or modify its
208behaviour. The default should be to return an empty list. A true value
209suppresses execution of the request completely. Make sure you don't get
210confused by recursive invocations when you output an OSC sequence within
211this callback.
212
213C<on_osc_seq_perl> should be used for new behaviour.
214
215=item on_osc_seq_perl $term, $args, $resp
375 216
376Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 217Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
377operating system command) is processed. Cursor position and other state 218operating system command) is processed. Cursor position and other state
378information is up-to-date when this happens. For interoperability, the 219information is up-to-date when this happens. For interoperability, the
379string should start with the extension name and a colon, to distinguish 220string should start with the extension name (sans -osc) and a semicolon,
380it from commands for other extensions, and this might be enforced in the 221to distinguish it from commands for other extensions, and this might be
381future. 222enforced in the future.
223
224For example, C<overlay-osc> uses this:
225
226 sub on_osc_seq_perl {
227 my ($self, $osc, $resp) = @_;
228
229 return unless $osc =~ s/^overlay;//;
230
231 ... process remaining $osc string
232 }
382 233
383Be careful not ever to trust (in a security sense) the data you receive, 234Be careful not ever to trust (in a security sense) the data you receive,
384as its source can not easily be controleld (e-mail content, messages from 235as its source can not easily be controlled (e-mail content, messages from
385other users on the same system etc.). 236other users on the same system etc.).
237
238For responses, C<$resp> contains the end-of-args separator used by the
239sender.
386 240
387=item on_add_lines $term, $string 241=item on_add_lines $term, $string
388 242
389Called whenever text is about to be output, with the text as argument. You 243Called whenever text is about to be output, with the text as argument. You
390can filter/change and output the text yourself by returning a true value 244can filter/change and output the text yourself by returning a true value
395=item on_tt_write $term, $octets 249=item on_tt_write $term, $octets
396 250
397Called whenever some data is written to the tty/pty and can be used to 251Called whenever some data is written to the tty/pty and can be used to
398suppress or filter tty input. 252suppress or filter tty input.
399 253
254=item on_tt_paste $term, $octets
255
256Called whenever text is about to be pasted, with the text as argument. You
257can filter/change and paste the text yourself by returning a true value
258and calling C<< $term->tt_paste >> yourself. C<$octets> is
259locale-encoded.
260
400=item on_line_update $term, $row 261=item on_line_update $term, $row
401 262
402Called whenever a line was updated or changed. Can be used to filter 263Called whenever a line was updated or changed. Can be used to filter
403screen output (e.g. underline urls or other useless stuff). Only lines 264screen output (e.g. underline urls or other useless stuff). Only lines
404that are being shown will be filtered, and, due to performance reasons, 265that are being shown will be filtered, and, due to performance reasons,
411later with the already-modified line (e.g. if unrelated parts change), so 272later with the already-modified line (e.g. if unrelated parts change), so
412you cannot just toggle rendition bits, but only set them. 273you cannot just toggle rendition bits, but only set them.
413 274
414=item on_refresh_begin $term 275=item on_refresh_begin $term
415 276
416Called just before the screen gets redrawn. Can be used for overlay 277Called just before the screen gets redrawn. Can be used for overlay or
417or similar effects by modify terminal contents in refresh_begin, and 278similar effects by modifying the terminal contents in refresh_begin, and
418restoring them in refresh_end. The built-in overlay and selection display 279restoring them in refresh_end. The built-in overlay and selection display
419code is run after this hook, and takes precedence. 280code is run after this hook, and takes precedence.
420 281
421=item on_refresh_end $term 282=item on_refresh_end $term
422 283
423Called just after the screen gets redrawn. See C<on_refresh_begin>. 284Called just after the screen gets redrawn. See C<on_refresh_begin>.
424 285
425=item on_keyboard_command $term, $string 286=item on_user_command $term, $string *DEPRECATED*
426 287
427Called whenever the user presses a key combination that has a 288Called whenever a user-configured event is being activated (e.g. via
428C<perl:string> action bound to it (see description of the B<keysym> 289a C<perl:string> action bound to a key, see description of the B<keysym>
429resource in the @@RXVT_NAME@@(1) manpage). 290resource in the urxvt(1) manpage).
291
292The event is simply the action string. This interface is going away in
293preference to the C<< ->register_keysym_action >> method.
294
295=item on_register_command $term, $keysym, $modifiermask, $string
296
297Called after parsing a keysym resource but before registering the
298associated binding. If this hook returns a true value the binding
299is not registered. It can be used to modify a binding by calling
300C<register_command>.
301
302=item on_resize_all_windows $term, $new_width, $new_height
303
304Called just after the new window size has been calculated, but before
305windows are actually being resized or hints are being set. If this hook
306returns a true value, setting of the window hints is being skipped.
430 307
431=item on_x_event $term, $event 308=item on_x_event $term, $event
432 309
433Called 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
434windows). Should only be used as a last resort. Most event structure 311windows). Should only be used as a last resort. Most event structure
435members are not passed. 312members are not passed.
436 313
314=item on_root_event $term, $event
315
316Like C<on_x_event>, but is called for events on the root window.
317
437=item on_focus_in $term 318=item on_focus_in $term
438 319
439Called whenever the window gets the keyboard focus, before rxvt-unicode 320Called whenever the window gets the keyboard focus, before rxvt-unicode
440does focus in processing. 321does focus in processing.
441 322
442=item on_focus_out $term 323=item on_focus_out $term
443 324
444Called wheneever the window loses keyboard focus, before rxvt-unicode does 325Called whenever the window loses keyboard focus, before rxvt-unicode does
445focus out processing. 326focus out processing.
446 327
447=item on_configure_notify $term, $event 328=item on_configure_notify $term, $event
448 329
330=item on_property_notify $term, $event
331
449=item on_key_press $term, $event, $keysym, $octets 332=item on_key_press $term, $event, $keysym, $octets
450 333
451=item on_key_release $term, $event, $keysym 334=item on_key_release $term, $event, $keysym
452 335
453=item on_button_press $term, $event 336=item on_button_press $term, $event
458 341
459=item on_map_notify $term, $event 342=item on_map_notify $term, $event
460 343
461=item on_unmap_notify $term, $event 344=item on_unmap_notify $term, $event
462 345
463Called whenever the corresponding X event is received for the terminal If 346Called whenever the corresponding X event is received for the terminal. If
464the hook returns true, then the even will be ignored by rxvt-unicode. 347the hook returns true, then the event will be ignored by rxvt-unicode.
465 348
466The event is a hash with most values as named by Xlib (see the XEvent 349The 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 350manpage), with the additional members C<row> and C<col>, which are the
468and column under the mouse cursor. 351(real, not screen-based) row and column under the mouse cursor.
469 352
470C<on_key_press> additionally receives the string rxvt-unicode would 353C<on_key_press> additionally receives the string rxvt-unicode would
471output, if any, in locale-specific encoding. 354output, if any, in locale-specific encoding.
472 355
473subwindow. 356=item on_client_message $term, $event
357
358=item on_wm_protocols $term, $event
359
360=item on_wm_delete_window $term, $event
361
362Called when various types of ClientMessage events are received (all with
363format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
364
365=item on_bell $term
366
367Called on receipt of a bell character.
474 368
475=back 369=back
476 370
477=cut 371=cut
478 372
479package urxvt; 373package urxvt;
480 374
481use utf8; 375use utf8;
482use strict; 376use strict 'vars';
483use Carp (); 377use Carp ();
484use Scalar::Util (); 378use Scalar::Util ();
485use List::Util (); 379use List::Util ();
486 380
487our $VERSION = 1; 381our $VERSION = 1;
488our $TERM; 382our $TERM;
383our @TERM_INIT; # should go, prevents async I/O etc.
384our @TERM_EXT; # should go, prevents async I/O etc.
489our @HOOKNAME; 385our @HOOKNAME;
490our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 386our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
491our %OPTION; 387our %OPTION;
492 388
493our $LIBDIR; 389our $LIBDIR;
494our $RESNAME; 390our $RESNAME;
495our $RESCLASS; 391our $RESCLASS;
496our $RXVTNAME; 392our $RXVTNAME;
497 393
394our $NOCHAR = chr 0xffff;
395
498=head2 Variables in the C<urxvt> Package 396=head2 Variables in the C<urxvt> Package
499 397
500=over 4 398=over 4
501 399
502=item $urxvt::LIBDIR 400=item $urxvt::LIBDIR
515=item $urxvt::TERM 413=item $urxvt::TERM
516 414
517The current terminal. This variable stores the current C<urxvt::term> 415The current terminal. This variable stores the current C<urxvt::term>
518object, whenever a callback/hook is executing. 416object, whenever a callback/hook is executing.
519 417
418=item @urxvt::TERM_INIT
419
420All code references in this array will be called as methods of the next newly
421created C<urxvt::term> object (during the C<on_init> phase). The array
422gets cleared before the code references that were in it are being executed,
423so references can push themselves onto it again if they so desire.
424
425This complements to the perl-eval command line option, but gets executed
426first.
427
428=item @urxvt::TERM_EXT
429
430Works similar to C<@TERM_INIT>, but contains perl package/class names, which
431get registered as normal extensions after calling the hooks in C<@TERM_INIT>
432but before other extensions. Gets cleared just like C<@TERM_INIT>.
433
520=back 434=back
521 435
522=head2 Functions in the C<urxvt> Package 436=head2 Functions in the C<urxvt> Package
523 437
524=over 4 438=over 4
525 439
526=item urxvt::fatal $errormessage 440=item urxvt::fatal $errormessage
527 441
528Fatally aborts execution with the given error message. Avoid at all 442Fatally aborts execution with the given error message (which should
529costs! The only time this is acceptable is when the terminal process 443include a trailing newline). Avoid at all costs! The only time this
530starts up. 444is acceptable (and useful) is in the init hook, where it prevents the
445terminal from starting up.
531 446
532=item urxvt::warn $string 447=item urxvt::warn $string
533 448
534Calls C<rxvt_warn> with the given string which should not include a 449Calls C<rxvt_warn> with the given string which should include a trailing
535newline. The module also overwrites the C<warn> builtin with a function 450newline. The module also overwrites the C<warn> builtin with a function
536that calls this function. 451that calls this function.
537 452
538Using this function has the advantage that its output ends up in the 453Using this function has the advantage that its output ends up in the
539correct place, e.g. on stderr of the connecting urxvtc client. 454correct place, e.g. on stderr of the connecting urxvtc client.
540 455
541Messages have a size limit of 1023 bytes currently. 456Messages have a size limit of 1023 bytes currently.
457
458=item @terms = urxvt::termlist
459
460Returns all urxvt::term objects that exist in this process, regardless of
461whether they are started, being destroyed etc., so be careful. Only term
462objects that have perl extensions attached will be returned (because there
463is no urxvt::term object associated with others).
542 464
543=item $time = urxvt::NOW 465=item $time = urxvt::NOW
544 466
545Returns the "current time" (as per the event loop). 467Returns the "current time" (as per the event loop).
546 468
589 511
590=item $rend = urxvt::OVERLAY_RSTYLE 512=item $rend = urxvt::OVERLAY_RSTYLE
591 513
592Return the rendition mask used for overlays by default. 514Return the rendition mask used for overlays by default.
593 515
594=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 516=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
517urxvt::RS_RVid, urxvt::RS_Uline
595 518
596Return the bit that enabled bold, italic, blink, reverse-video and 519Return the bit that enabled bold, italic, blink, reverse-video and
597underline, respectively. To enable such a style, just logically OR it into 520underline, respectively. To enable such a style, just logically OR it into
598the bitset. 521the bitset.
599 522
604Return the foreground/background colour index, respectively. 527Return the foreground/background colour index, respectively.
605 528
606=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour 529=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
607 530
608=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour 531=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
532
533=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
609 534
610Replace the foreground/background colour in the rendition mask with the 535Replace the foreground/background colour in the rendition mask with the
611specified one. 536specified one.
612 537
613=item $value = urxvt::GET_CUSTOM $rend 538=item $value = urxvt::GET_CUSTOM $rend
630 my $msg = join "", @_; 555 my $msg = join "", @_;
631 $msg .= "\n" 556 $msg .= "\n"
632 unless $msg =~ /\n$/; 557 unless $msg =~ /\n$/;
633 urxvt::warn ($msg); 558 urxvt::warn ($msg);
634 }; 559 };
560}
635 561
636 # %ENV is the original startup environment 562no warnings 'utf8';
637 delete $ENV{IFS}; 563
638 delete $ENV{CDPATH}; 564sub parse_resource {
639 delete $ENV{BASH_ENV}; 565 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
640 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin"; 566
567 $name =~ y/-/./ if $isarg;
568
569 $term->scan_meta;
570
571 my $r = $term->{meta}{resource};
572 keys %$r; # reset iterator
573 while (my ($pattern, $v) = each %$r) {
574 if (
575 $pattern =~ /\.$/
576 ? $pattern eq substr $name, 0, length $pattern
577 : $pattern eq $name
578 ) {
579 $name = "$urxvt::RESCLASS.$name";
580
581 push @{ $term->{perl_ext_3} }, $v->[0];
582
583 if ($v->[1] eq "boolean") {
584 $term->put_option_db ($name, $flag ? "true" : "false");
585 return 1;
586 } else {
587 $term->put_option_db ($name, $value);
588 return 1 + 2;
589 }
590 }
591 }
592
593 0
594}
595
596sub usage {
597 my ($term, $usage_type) = @_;
598
599 $term->scan_meta;
600
601 my $r = $term->{meta}{resource};
602
603 for my $pattern (sort keys %$r) {
604 my ($ext, $type, $desc) = @{ $r->{$pattern} };
605
606 $desc .= " (-pe $ext)";
607
608 if ($usage_type == 1) {
609 $pattern =~ y/./-/;
610 $pattern =~ s/-$/-.../g;
611
612 if ($type eq "boolean") {
613 urxvt::log sprintf " -%-30s %s\n", "/+$pattern", $desc;
614 } else {
615 urxvt::log sprintf " -%-30s %s\n", "$pattern $type", $desc;
616 }
617 } else {
618 $pattern =~ s/\.$/.*/g;
619 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type;
620 }
621 }
641} 622}
642 623
643my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 624my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
644 625
645sub verbose { 626sub verbose {
650my %extension_pkg; 631my %extension_pkg;
651 632
652# load a single script into its own package, once only 633# load a single script into its own package, once only
653sub extension_package($) { 634sub extension_package($) {
654 my ($path) = @_; 635 my ($path) = @_;
655
656 no strict 'refs';
657 636
658 $extension_pkg{$path} ||= do { 637 $extension_pkg{$path} ||= do {
659 $path =~ /([^\/\\]+)$/; 638 $path =~ /([^\/\\]+)$/;
660 my $pkg = $1; 639 my $pkg = $1;
661 $pkg =~ s/[^[:word:]]/_/g; 640 $pkg =~ s/[^[:word:]]/_/g;
662 $pkg = "urxvt::ext::$pkg"; 641 $pkg = "urxvt::ext::$pkg";
663 642
664 verbose 3, "loading extension '$path' into package '$pkg'"; 643 verbose 3, "loading extension '$path' into package '$pkg'";
665 644
645 (${"$pkg\::_NAME"} = $path) =~ s/^.*[\\\/]//; # hackish
646
666 open my $fh, "<:raw", $path 647 open my $fh, "<:raw", $path
667 or die "$path: $!"; 648 or die "$path: $!";
668 649
669 @{"$pkg\::ISA"} = urxvt::term::extension::;
670
671 my $source = 650 my $source =
672 "package $pkg; use strict; use utf8;\n" 651 "package $pkg; use strict 'vars'; use utf8; no warnings 'utf8';\n"
673 . "#line 1 \"$path\"\n{\n" 652 . "#line 1 \"$path\"\n{\n"
674 . (do { local $/; <$fh> }) 653 . (do { local $/; <$fh> })
675 . "\n};\n1"; 654 . "\n};\n1";
676 655
677 eval $source 656 eval $source
686# called by the rxvt core 665# called by the rxvt core
687sub invoke { 666sub invoke {
688 local $TERM = shift; 667 local $TERM = shift;
689 my $htype = shift; 668 my $htype = shift;
690 669
691 if ($htype == 0) { # INIT 670 if ($htype == HOOK_INIT) {
692 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 671 my @dirs = $TERM->perl_libdirs;
693 672
694 my %ext_arg; 673 my %ext_arg;
695 674
675 {
676 my @init = @TERM_INIT;
677 @TERM_INIT = ();
678 $_->($TERM) for @init;
679 my @pkg = @TERM_EXT;
680 @TERM_EXT = ();
681 $TERM->register_package ($_) for @pkg;
682 }
683
684 for (
685 @{ delete $TERM->{perl_ext_3} },
696 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 686 grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2
687 ) {
697 if ($_ eq "default") { 688 if ($_ eq "default") {
698 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 689 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
699 } elsif (/^-(.*)$/) { 690 } elsif (/^-(.*)$/) {
700 delete $ext_arg{$1}; 691 delete $ext_arg{$1};
701 } elsif (/^([^<]+)<(.*)>$/) { 692 } elsif (/^([^<]+)<(.*)>$/) {
702 push @{ $ext_arg{$1} }, $2; 693 push @{ $ext_arg{$1} }, $2;
703 } else { 694 } else {
704 $ext_arg{$_} ||= []; 695 $ext_arg{$_} ||= [];
705 } 696 }
706 } 697 }
707 698
708 while (my ($ext, $argv) = each %ext_arg) { 699 for my $ext (sort keys %ext_arg) {
709 my @files = grep -f $_, map "$_/$ext", @dirs; 700 my @files = grep -f $_, map "$_/$ext", @dirs;
710 701
711 if (@files) { 702 if (@files) {
712 $TERM->register_package (extension_package $files[0], $argv); 703 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
713 } else { 704 } else {
714 warn "perl extension '$ext' not found in perl library search path\n"; 705 warn "perl extension '$ext' not found in perl library search path\n";
715 } 706 }
716 } 707 }
717 708
723 714
724 if (my $cb = $TERM->{_hook}[$htype]) { 715 if (my $cb = $TERM->{_hook}[$htype]) {
725 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 716 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
726 if $verbosity >= 10; 717 if $verbosity >= 10;
727 718
719 for my $pkg (
720 # this hook is only sent to the extension with the name
721 # matching the first arg
722 $htype == HOOK_KEYBOARD_DISPATCH
723 ? exists $cb->{"urxvt::ext::$_[0]"} ? "urxvt::ext::" . shift : return undef
728 keys %$cb; 724 : keys %$cb
729 725 ) {
730 while (my ($pkg, $cb) = each %$cb) {
731 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 726 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) };
732 and last; 727 $retval ||= $retval_;
733 728
734 if ($@) { 729 if ($@) {
735 $TERM->ungrab; # better to lose the grab than the session 730 $TERM->ungrab; # better to lose the grab than the session
736 warn $@; 731 warn $@;
737 } 732 }
739 734
740 verbose 11, "$HOOKNAME[$htype] returning <$retval>" 735 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
741 if $verbosity >= 11; 736 if $verbosity >= 11;
742 } 737 }
743 738
744 if ($htype == 1) { # DESTROY 739 if ($htype == HOOK_DESTROY) {
745 # clear package objects 740 # clear package objects
746 %$_ = () for values %{ $TERM->{_pkg} }; 741 %$_ = () for values %{ $TERM->{_pkg} };
747 742
748 # clear package 743 # clear package
749 %$TERM = (); 744 %$TERM = ();
750 } 745 }
751 746
752 $retval 747 $retval
753} 748}
754 749
755sub exec_async(@) { 750sub SET_COLOR($$$) {
756 my $pid = fork; 751 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} 752}
766 753
767# urxvt::term::extension 754sub rend2mask {
755 no strict 'refs';
756 my ($str, $mask) = (@_, 0);
757 my %color = ( fg => undef, bg => undef );
758 my @failed;
759 for my $spec ( split /\s+/, $str ) {
760 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
761 $color{lc($1)} = $2;
762 } else {
763 my $neg = $spec =~ s/^[-^]//;
764 unless ( exists &{"RS_$spec"} ) {
765 push @failed, $spec;
766 next;
767 }
768 my $cur = &{"RS_$spec"};
769 if ( $neg ) {
770 $mask &= ~$cur;
771 } else {
772 $mask |= $cur;
773 }
774 }
775 }
776 ($mask, @color{qw(fg bg)}, \@failed)
777}
768 778
769package urxvt::term::extension; 779package urxvt::term::extension;
770 780
771sub enable { 781=head2 The C<urxvt::term::extension> class
772 my ($self, %hook) = @_;
773 my $pkg = $self->{_pkg};
774 782
775 while (my ($name, $cb) = each %hook) { 783Each extension attached to a terminal object is represented by
776 my $htype = $HOOKTYPE{uc $name}; 784a C<urxvt::term::extension> object.
777 defined $htype
778 or Carp::croak "unsupported hook type '$name'";
779 785
780 $self->set_should_invoke ($htype, +1) 786You can use these objects, which are passed to all callbacks to store any
781 unless exists $self->{term}{_hook}[$htype]{$pkg}; 787state related to the terminal and extension instance.
782 788
783 $self->{term}{_hook}[$htype]{$pkg} = $cb; 789The methods (And data members) documented below can be called on extension
784 } 790objects, in addition to call methods documented for the <urxvt::term>
785} 791class.
786 792
787sub disable { 793=over 4
788 my ($self, @hook) = @_;
789 my $pkg = $self->{_pkg};
790 794
791 for my $name (@hook) { 795=item $urxvt_term = $self->{term}
792 my $htype = $HOOKTYPE{uc $name};
793 defined $htype
794 or Carp::croak "unsupported hook type '$name'";
795 796
796 $self->set_should_invoke ($htype, -1) 797Returns the C<urxvt::term> object associated with this instance of the
797 if delete $self->{term}{_hook}[$htype]{$pkg}; 798extension. This member I<must not> be changed in any way.
798 } 799
799} 800=cut
800 801
801our $AUTOLOAD; 802our $AUTOLOAD;
802 803
803sub AUTOLOAD { 804sub AUTOLOAD {
804 $AUTOLOAD =~ /:([^:]+)$/ 805 $AUTOLOAD =~ /:([^:]+)$/
817 818
818sub DESTROY { 819sub DESTROY {
819 # nop 820 # nop
820} 821}
821 822
822# urxvt::destroy_hook 823# urxvt::destroy_hook (basically a cheap Guard:: implementation)
823 824
824sub urxvt::destroy_hook::DESTROY { 825sub urxvt::destroy_hook::DESTROY {
825 ${$_[0]}->(); 826 ${$_[0]}->();
826} 827}
827 828
828sub urxvt::destroy_hook(&) { 829sub urxvt::destroy_hook(&) {
829 bless \shift, urxvt::destroy_hook:: 830 bless \shift, urxvt::destroy_hook::
830} 831}
832
833=item $self->enable ($hook_name => $cb[, $hook_name => $cb..])
834
835Dynamically enable the given hooks (named without the C<on_> prefix) for
836this extension, replacing any hook previously installed via C<enable> in
837this extension.
838
839This is useful when you want to overwrite time-critical hooks only
840temporarily.
841
842To install additional callbacks for the same hook, you can use the C<on>
843method of the C<urxvt::term> class.
844
845=item $self->disable ($hook_name[, $hook_name..])
846
847Dynamically disable the given hooks.
848
849=cut
850
851sub enable {
852 my ($self, %hook) = @_;
853 my $pkg = $self->{_pkg};
854
855 while (my ($name, $cb) = each %hook) {
856 my $htype = $HOOKTYPE{uc $name};
857 defined $htype
858 or Carp::croak "unsupported hook type '$name'";
859
860 $self->set_should_invoke ($htype, +1)
861 unless exists $self->{term}{_hook}[$htype]{$pkg};
862
863 $self->{term}{_hook}[$htype]{$pkg} = $cb;
864 }
865}
866
867sub disable {
868 my ($self, @hook) = @_;
869 my $pkg = $self->{_pkg};
870
871 for my $name (@hook) {
872 my $htype = $HOOKTYPE{uc $name};
873 defined $htype
874 or Carp::croak "unsupported hook type '$name'";
875
876 $self->set_should_invoke ($htype, -1)
877 if delete $self->{term}{_hook}[$htype]{$pkg};
878 }
879}
880
881=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
882
883Similar to the C<enable> enable, but installs additional callbacks for
884the given hook(s) (that is, it doesn't replace existing callbacks), and
885returns a guard object. When the guard object is destroyed the callbacks
886are disabled again.
887
888=cut
889
890sub urxvt::extension::on_disable::DESTROY {
891 my $disable = shift;
892
893 my $term = delete $disable->{""};
894
895 while (my ($htype, $id) = each %$disable) {
896 delete $term->{_hook}[$htype]{$id};
897 $term->set_should_invoke ($htype, -1);
898 }
899}
900
901sub on {
902 my ($self, %hook) = @_;
903
904 my $term = $self->{term};
905
906 my %disable = ( "" => $term );
907
908 while (my ($name, $cb) = each %hook) {
909 my $htype = $HOOKTYPE{uc $name};
910 defined $htype
911 or Carp::croak "unsupported hook type '$name'";
912
913 $term->set_should_invoke ($htype, +1);
914 $term->{_hook}[$htype]{ $disable{$htype} = $cb+0 }
915 = sub { shift; $cb->($self, @_) }; # very ugly indeed
916 }
917
918 bless \%disable, "urxvt::extension::on_disable"
919}
920
921=item $self->x_resource ($pattern)
922
923=item $self->x_resource_boolean ($pattern)
924
925These methods support an additional C<%> prefix when called on an
926extension object - see the description of these methods in the
927C<urxvt::term> class for details.
928
929=cut
930
931sub x_resource {
932 my ($self, $name) = @_;
933 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
934 $self->{term}->x_resource ($name)
935}
936
937sub x_resource_boolean {
938 my ($self, $name) = @_;
939 $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
940 $self->{term}->x_resource_boolean ($name)
941}
942
943=back
944
945=cut
831 946
832package urxvt::anyevent; 947package urxvt::anyevent;
833 948
834=head2 The C<urxvt::anyevent> Class 949=head2 The C<urxvt::anyevent> Class
835 950
836The sole purpose of this class is to deliver an interface to the 951The sole purpose of this class is to deliver an interface to the
837C<AnyEvent> module - any module using it will work inside urxvt without 952C<AnyEvent> module - any module using it will work inside urxvt without
838further programming. The only exception is that you cannot wait on 953further programming. The only exception is that you cannot wait on
839condition variables, but non-blocking condvar use is ok. What this means 954condition variables, but non-blocking condvar use is ok.
840is that you cannot use blocking APIs, but the non-blocking variant should
841work.
842 955
843=cut 956In practical terms this means is that you cannot use blocking APIs, but
957the non-blocking variant should work.
844 958
959=cut
960
845our $VERSION = 1; 961our $VERSION = '5.23';
846 962
847$INC{"urxvt/anyevent.pm"} = 1; # mark us as there 963$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
848push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 964push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
849 965
850sub timer { 966sub timer {
852 968
853 my $cb = $arg{cb}; 969 my $cb = $arg{cb};
854 970
855 urxvt::timer 971 urxvt::timer
856 ->new 972 ->new
857 ->start (urxvt::NOW + $arg{after}) 973 ->after ($arg{after}, $arg{interval})
858 ->cb (sub { 974 ->cb ($arg{interval} ? $cb : sub {
859 $_[0]->stop; # need to cancel manually 975 $_[0]->stop; # need to cancel manually
860 $cb->(); 976 $cb->();
861 }) 977 })
862} 978}
863 979
864sub io { 980sub io {
865 my ($class, %arg) = @_; 981 my ($class, %arg) = @_;
866 982
867 my $cb = $arg{cb}; 983 my $cb = $arg{cb};
984 my $fd = fileno $arg{fh};
985 defined $fd or $fd = $arg{fh};
868 986
869 bless [$arg{fh}, urxvt::iow 987 bless [$arg{fh}, urxvt::iow
870 ->new 988 ->new
871 ->fd (fileno $arg{fh}) 989 ->fd ($fd)
872 ->events (($arg{poll} =~ /r/ ? 1 : 0) 990 ->events (($arg{poll} =~ /r/ ? 1 : 0)
873 | ($arg{poll} =~ /w/ ? 2 : 0)) 991 | ($arg{poll} =~ /w/ ? 2 : 0))
874 ->start 992 ->start
875 ->cb (sub { 993 ->cb ($cb)
876 $cb->(($_[1] & 1 ? 'r' : '')
877 . ($_[1] & 2 ? 'w' : ''));
878 })],
879 urxvt::anyevent:: 994 ], urxvt::anyevent::
995}
996
997sub idle {
998 my ($class, %arg) = @_;
999
1000 my $cb = $arg{cb};
1001
1002 urxvt::iw
1003 ->new
1004 ->start
1005 ->cb ($cb)
1006}
1007
1008sub child {
1009 my ($class, %arg) = @_;
1010
1011 my $cb = $arg{cb};
1012
1013 urxvt::pw
1014 ->new
1015 ->start ($arg{pid})
1016 ->cb (sub {
1017 $_[0]->stop; # need to cancel manually
1018 $cb->($_[0]->rpid, $_[0]->rstatus);
1019 })
880} 1020}
881 1021
882sub DESTROY { 1022sub DESTROY {
883 $_[0][1]->stop; 1023 $_[0][1]->stop;
884} 1024}
885 1025
886sub condvar { 1026# only needed for AnyEvent < 6 compatibility
887 bless \my $flag, urxvt::anyevent::condvar:: 1027sub one_event {
888}
889
890sub urxvt::anyevent::condvar::broadcast {
891 ${$_[0]}++;
892}
893
894sub urxvt::anyevent::condvar::wait {
895 unless (${$_[0]}) {
896 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; 1028 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
897 }
898} 1029}
899 1030
900package urxvt::term; 1031package urxvt::term;
901 1032
902=head2 The C<urxvt::term> Class 1033=head2 The C<urxvt::term> Class
908# find on_xxx subs in the package and register them 1039# find on_xxx subs in the package and register them
909# as hooks 1040# as hooks
910sub register_package { 1041sub register_package {
911 my ($self, $pkg, $argv) = @_; 1042 my ($self, $pkg, $argv) = @_;
912 1043
1044 no strict 'refs';
1045
1046 urxvt::verbose 6, "register package $pkg to $self";
1047
1048 @{"$pkg\::ISA"} = urxvt::term::extension::;
1049
913 my $proxy = bless { 1050 my $proxy = bless {
914 _pkg => $pkg, 1051 _pkg => $pkg,
1052 _name => ${"$pkg\::_NAME"}, # hackish
915 argv => $argv, 1053 argv => $argv,
916 }, $pkg; 1054 }, $pkg;
917 Scalar::Util::weaken ($proxy->{term} = $self); 1055 Scalar::Util::weaken ($proxy->{term} = $self);
918 1056
919 $self->{_pkg}{$pkg} = $proxy; 1057 $self->{_pkg}{$pkg} = $proxy;
920 1058
923 $proxy->enable ($name => $ref); 1061 $proxy->enable ($name => $ref);
924 } 1062 }
925 } 1063 }
926} 1064}
927 1065
1066sub perl_libdirs {
1067 map { split /:/ }
1068 $_[0]->resource ("perl_lib"),
1069 $ENV{URXVT_PERL_LIB},
1070 "$ENV{HOME}/.urxvt/ext",
1071 "$LIBDIR/perl"
1072}
1073
1074sub scan_meta {
1075 my ($self) = @_;
1076 my @libdirs = perl_libdirs $self;
1077
1078 return if $self->{meta_libdirs} eq join "\x00", @libdirs;
1079
1080 my %meta;
1081
1082 $self->{meta_libdirs} = join "\x00", @libdirs;
1083 $self->{meta} = \%meta;
1084
1085 for my $dir (reverse @libdirs) {
1086 opendir my $fh, $dir
1087 or next;
1088 for my $ext (readdir $fh) {
1089 $ext !~ /^\./
1090 and open my $fh, "<", "$dir/$ext"
1091 or next;
1092
1093 while (<$fh>) {
1094 if (/^#:META:X_RESOURCE:(.*)/) {
1095 my ($pattern, $type, $desc) = split /:/, $1;
1096 $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name
1097 if ($pattern =~ /[^a-zA-Z0-9\-\.]/) {
1098 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1099 } else {
1100 $meta{resource}{$pattern} = [$ext, $type, $desc];
1101 }
1102 } elsif (/^\s*(?:#|$)/) {
1103 # skip other comments and empty lines
1104 } else {
1105 last; # stop parsing on first non-empty non-comment line
1106 }
1107 }
1108 }
1109 }
1110}
1111
928=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1112=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
929 1113
930Creates a new terminal, very similar as if you had started it with system 1114Creates a new terminal, very similar as if you had started it with system
931C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like 1115C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
932hash which defines the environment of the new terminal. 1116hash which defines the environment of the new terminal.
933 1117
934Croaks (and probably outputs an error message) if the new instance 1118Croaks (and probably outputs an error message) if the new instance
935couldn't be created. Returns C<undef> if the new instance didn't 1119couldn't be created. Returns C<undef> if the new instance didn't
936initialise perl, and the terminal object otherwise. The C<init> and 1120initialise perl, and the terminal object otherwise. The C<init> and
937C<start> hooks will be called during this call. 1121C<start> hooks will be called before this call returns, and are free to
1122refer to global data (which is race free).
938 1123
939=cut 1124=cut
940 1125
941sub new { 1126sub new {
942 my ($class, $env, @args) = @_; 1127 my ($class, $env, @args) = @_;
943 1128
1129 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1130 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1131
944 _new ([ map "$_=$env->{$_}", keys %$env ], @args); 1132 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
945} 1133}
946 1134
947=item $term->destroy 1135=item $term->destroy
948 1136
949Destroy the terminal object (close the window, free resources 1137Destroy the terminal object (close the window, free resources
950etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event 1138etc.). Please note that urxvt will not exit as long as any event
951watchers (timers, io watchers) are still active. 1139watchers (timers, io watchers) are still active.
1140
1141=item $term->exec_async ($cmd[, @args])
1142
1143Works like the combination of the C<fork>/C<exec> builtins, which executes
1144("starts") programs in the background. This function takes care of setting
1145the user environment before exec'ing the command (e.g. C<PATH>) and should
1146be preferred over explicit calls to C<exec> or C<system>.
1147
1148Returns the pid of the subprocess or C<undef> on error.
1149
1150=cut
1151
1152sub exec_async {
1153 my $self = shift;
1154
1155 my $pid = fork;
1156
1157 return $pid
1158 if !defined $pid or $pid;
1159
1160 %ENV = %{ $self->env };
1161
1162 exec @_;
1163 urxvt::_exit 255;
1164}
952 1165
953=item $isset = $term->option ($optval[, $set]) 1166=item $isset = $term->option ($optval[, $set])
954 1167
955Returns true if the option specified by C<$optval> is enabled, and 1168Returns true if the option specified by C<$optval> is enabled, and
956optionally change it. All option values are stored by name in the hash 1169optionally change it. All option values are stored by name in the hash
957C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1170C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
958 1171
959Here is a a likely non-exhaustive list of option names, please see the 1172Here is a likely non-exhaustive list of option names, please see the
960source file F</src/optinc.h> to see the actual list: 1173source file F</src/optinc.h> to see the actual list:
961 1174
962 borderLess console cursorBlink cursorUnderline hold iconic insecure 1175 borderLess buffered console cursorBlink cursorUnderline hold iconic
963 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1176 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
964 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1177 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
965 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1178 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
966 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1179 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
967 transparent tripleclickwords utmpInhibit visualBell 1180 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1181 urgentOnBell utmpInhibit visualBell
968 1182
969=item $value = $term->resource ($name[, $newval]) 1183=item $value = $term->resource ($name[, $newval])
970 1184
971Returns the current resource value associated with a given name and 1185Returns the current resource value associated with a given name and
972optionally sets a new value. Setting values is most useful in the C<init> 1186optionally sets a new value. Setting values is most useful in the C<init>
981likely change). 1195likely change).
982 1196
983Please note that resource strings will currently only be freed when the 1197Please note that resource strings will currently only be freed when the
984terminal is destroyed, so changing options frequently will eat memory. 1198terminal is destroyed, so changing options frequently will eat memory.
985 1199
986Here is a a likely non-exhaustive list of resource names, not all of which 1200Here is a likely non-exhaustive list of resource names, not all of which
987are supported in every build, please see the source file F</src/rsinc.h> 1201are supported in every build, please see the source file F</src/rsinc.h>
988to see the actual list: 1202to see the actual list:
989 1203
990 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1204 answerbackstring backgroundPixmap backspace_key blurradius
991 borderLess color cursorBlink cursorUnderline cutchars delete_key 1205 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
992 display_name embed ext_bwidth fade font geometry hold iconName 1206 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
993 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1207 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1208 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
994 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier 1209 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
995 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval 1210 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
996 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1211 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
997 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1212 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
998 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1213 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
999 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1214 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1000 secondaryScreen secondaryScroll selectstyle shade term_name title 1215 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1001 transient_for transparent transparent_all tripleclickwords utmpInhibit 1216 term_name title transient_for transparent tripleclickwords urgentOnBell
1002 visualBell 1217 utmpInhibit visualBell
1003 1218
1004=cut 1219=cut
1005 1220
1006sub resource($$;$) { 1221sub resource($$;$) {
1007 my ($self, $name) = (shift, shift); 1222 my ($self, $name) = (shift, shift);
1008 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1223 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1009 &urxvt::term::_resource 1224 goto &urxvt::term::_resource
1010} 1225}
1011 1226
1012=item $value = $term->x_resource ($pattern) 1227=item $value = $term->x_resource ($pattern)
1013 1228
1014Returns the X-Resource for the given pattern, excluding the program or 1229Returns the X-Resource for the given pattern, excluding the program or
1015class name, i.e. C<< $term->x_resource ("boldFont") >> should return the 1230class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1016same value as used by this instance of rxvt-unicode. Returns C<undef> if no 1231same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1017resource with that pattern exists. 1232resource with that pattern exists.
1018 1233
1234Extensions that define extra resource or command line arguments also need
1235to call this method to access their values.
1236
1237If the method is called on an extension object (basically, from an
1238extension), then the special prefix C<%.> will be replaced by the name of
1239the extension and a dot, and the lone string C<%> will be replaced by the
1240extension name itself. This makes it possible to code extensions so you
1241can rename them and get a new set of commandline switches and resources
1242without having to change the actual code.
1243
1019This method should only be called during the C<on_start> hook, as there is 1244This method should only be called during the C<on_start> hook, as there is
1020only one resource database per display, and later invocations might return 1245only one resource database per display, and later invocations might return
1021the wrong resources. 1246the wrong resources.
1022 1247
1023=item $success = $term->parse_keysym ($keysym_spec, $command_string) 1248=item $value = $term->x_resource_boolean ($pattern)
1024 1249
1250Like C<x_resource>, above, but interprets the string value as a boolean
1251and returns C<1> for true values, C<0> for false values and C<undef> if
1252the resource or option isn't specified.
1253
1254You should always use this method to parse boolean resources.
1255
1256=cut
1257
1258sub x_resource_boolean {
1259 my $res = &x_resource;
1260
1261 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1262}
1263
1264=item $success = $term->parse_keysym ($key, $octets)
1265
1025Adds a keymap translation exactly as specified via a resource. See the 1266Adds a key binding exactly as specified via a resource. See the
1026C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1267C<keysym> resource in the urxvt(1) manpage.
1268
1269=item $term->register_command ($keysym, $modifiermask, $string)
1270
1271Adds a key binding. This is a lower level api compared to
1272C<parse_keysym>, as it expects a parsed key description, and can be
1273used only inside either the C<on_init> hook, to add a binding, or the
1274C<on_register_command> hook, to modify a parsed binding.
1027 1275
1028=item $rend = $term->rstyle ([$new_rstyle]) 1276=item $rend = $term->rstyle ([$new_rstyle])
1029 1277
1030Return and optionally change the current rendition. Text that is output by 1278Return and optionally change the current rendition. Text that is output by
1031the terminal application will use this style. 1279the terminal application will use this style.
1039 1287
1040=item ($row, $col) = $term->selection_beg ([$row, $col]) 1288=item ($row, $col) = $term->selection_beg ([$row, $col])
1041 1289
1042=item ($row, $col) = $term->selection_end ([$row, $col]) 1290=item ($row, $col) = $term->selection_end ([$row, $col])
1043 1291
1044Return the current values of the selection mark, begin or end positions, 1292Return the current values of the selection mark, begin or end positions.
1045and optionally set them to new values. 1293
1294When arguments are given, then the selection coordinates are set to
1295C<$row> and C<$col>, and the selection screen is set to the current
1296screen.
1297
1298=item $screen = $term->selection_screen ([$screen])
1299
1300Returns the current selection screen, and then optionally sets it.
1046 1301
1047=item $term->selection_make ($eventtime[, $rectangular]) 1302=item $term->selection_make ($eventtime[, $rectangular])
1048 1303
1049Tries to make a selection as set by C<selection_beg> and 1304Tries to make a selection as set by C<selection_beg> and
1050C<selection_end>. If C<$rectangular> is true (default: false), a 1305C<selection_end>. If C<$rectangular> is true (default: false), a
1051rectangular selection will be made. This is the prefered function to make 1306rectangular selection will be made. This is the preferred function to make
1052a selection. 1307a selection.
1053 1308
1054=item $success = $term->selection_grab ($eventtime) 1309=item $success = $term->selection_grab ($eventtime[, $clipboard])
1055 1310
1056Try to request the primary selection text from the server (for example, as 1311Try to acquire ownership of the primary (clipboard if C<$clipboard> is
1312true) selection from the server. The corresponding text can be set
1057set by the next method). No visual feedback will be given. This function 1313with the next method. No visual feedback will be given. This function
1058is mostly useful from within C<on_sel_grab> hooks. 1314is mostly useful from within C<on_sel_grab> hooks.
1059 1315
1060=item $oldtext = $term->selection ([$newtext]) 1316=item $oldtext = $term->selection ([$newtext, $clipboard])
1061 1317
1062Return the current selection text and optionally replace it by C<$newtext>. 1318Return the current selection (clipboard if C<$clipboard> is true) text
1319and optionally replace it by C<$newtext>.
1320
1321=item $term->selection_clear ([$clipboard])
1322
1323Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1063 1324
1064=item $term->overlay_simple ($x, $y, $text) 1325=item $term->overlay_simple ($x, $y, $text)
1065 1326
1066Create a simple multi-line overlay box. See the next method for details. 1327Create a simple multi-line overlay box. See the next method for details.
1067 1328
1097 1358
1098The methods currently supported on C<urxvt::overlay> objects are: 1359The methods currently supported on C<urxvt::overlay> objects are:
1099 1360
1100=over 4 1361=over 4
1101 1362
1102=item $overlay->set ($x, $y, $text, $rend) 1363=item $overlay->set ($x, $y, $text[, $rend])
1103 1364
1104Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1365Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1105text in rxvt-unicode's special encoding and an array of rendition values 1366text in rxvt-unicode's special encoding and an array of rendition values
1106at a specific position inside the overlay. 1367at a specific position inside the overlay.
1368
1369If C<$rend> is missing, then the rendition will not be changed.
1107 1370
1108=item $overlay->hide 1371=item $overlay->hide
1109 1372
1110If visible, hide the overlay, but do not destroy it. 1373If visible, hide the overlay, but do not destroy it.
1111 1374
1181 1444
1182Normally its not a good idea to use this function, as programs might be 1445Normally 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 1446confused by changes in cursor position or scrolling. Its useful inside a
1184C<on_add_lines> hook, though. 1447C<on_add_lines> hook, though.
1185 1448
1449=item $term->scr_change_screen ($screen)
1450
1451Switch to given screen - 0 primary, 1 secondary.
1452
1186=item $term->cmd_parse ($octets) 1453=item $term->cmd_parse ($octets)
1187 1454
1188Similar to C<scr_add_lines>, but the argument must be in the 1455Similar to C<scr_add_lines>, but the argument must be in the
1189locale-specific encoding of the terminal and can contain command sequences 1456locale-specific encoding of the terminal and can contain command sequences
1190(escape codes) that will be interpreted. 1457(escape codes) that will be interpreted.
1191 1458
1192=item $term->tt_write ($octets) 1459=item $term->tt_write ($octets)
1193 1460
1194Write the octets given in C<$data> to the tty (i.e. as program input). To 1461Write the octets given in C<$octets> to the tty (i.e. as program input). To
1195pass characters instead of octets, you should convert your strings first 1462pass characters instead of octets, you should convert your strings first
1196to the locale-specific encoding using C<< $term->locale_encode >>. 1463to the locale-specific encoding using C<< $term->locale_encode >>.
1464
1465=item $term->tt_paste ($octets)
1466
1467Write the octets given in C<$octets> to the tty as a paste, converting NL to
1468CR and bracketing the data with control sequences if bracketed paste mode
1469is set.
1197 1470
1198=item $old_events = $term->pty_ev_events ([$new_events]) 1471=item $old_events = $term->pty_ev_events ([$new_events])
1199 1472
1200Replaces the event mask of the pty watcher by the given event mask. Can 1473Replaces 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 1474be used to suppress input and output handling to the pty/tty. See the
1202description of C<< urxvt::timer->events >>. Make sure to always restore 1475description of C<< urxvt::timer->events >>. Make sure to always restore
1203the previous value. 1476the previous value.
1204 1477
1478=item $fd = $term->pty_fd
1479
1480Returns the master file descriptor for the pty in use, or C<-1> if no pty
1481is used.
1482
1205=item $windowid = $term->parent 1483=item $windowid = $term->parent
1206 1484
1207Return the window id of the toplevel window. 1485Return the window id of the toplevel window.
1208 1486
1209=item $windowid = $term->vt 1487=item $windowid = $term->vt
1215Adds the specified events to the vt event mask. Useful e.g. when you want 1493Adds the specified events to the vt event mask. Useful e.g. when you want
1216to receive pointer events all the times: 1494to receive pointer events all the times:
1217 1495
1218 $term->vt_emask_add (urxvt::PointerMotionMask); 1496 $term->vt_emask_add (urxvt::PointerMotionMask);
1219 1497
1498=item $term->set_urgency ($set)
1499
1500Enable/disable the urgency hint on the toplevel window.
1501
1502=item $term->focus_in
1503
1504=item $term->focus_out
1505
1506=item $term->key_press ($state, $keycode[, $time])
1507
1508=item $term->key_release ($state, $keycode[, $time])
1509
1510Deliver various fake events to to terminal.
1511
1220=item $window_width = $term->width 1512=item $window_width = $term->width
1221 1513
1222=item $window_height = $term->height 1514=item $window_height = $term->height
1223 1515
1224=item $font_width = $term->fwidth 1516=item $font_width = $term->fwidth
1254=item $env = $term->env 1546=item $env = $term->env
1255 1547
1256Returns a copy of the environment in effect for the terminal as a hashref 1548Returns a copy of the environment in effect for the terminal as a hashref
1257similar to C<\%ENV>. 1549similar to C<\%ENV>.
1258 1550
1551=item @envv = $term->envv
1552
1553Returns the environment as array of strings of the form C<VAR=VALUE>.
1554
1555=item @argv = $term->argv
1556
1557Return the argument vector as this terminal, similar to @ARGV, but
1558includes the program name as first element.
1559
1259=cut 1560=cut
1260 1561
1261sub env { 1562sub env {
1262 if (my $env = $_[0]->_env) {
1263 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env } 1563 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1264 } else {
1265 +{ %ENV }
1266 }
1267} 1564}
1268 1565
1269=item $modifiermask = $term->ModLevel3Mask 1566=item $modifiermask = $term->ModLevel3Mask
1270 1567
1271=item $modifiermask = $term->ModMetaMask 1568=item $modifiermask = $term->ModMetaMask
1272 1569
1273=item $modifiermask = $term->ModNumLockMask 1570=item $modifiermask = $term->ModNumLockMask
1274 1571
1275Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1572Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1276AltGr), the meta key (often Alt) and the num lock key, if applicable. 1573AltGr), the meta key (often Alt) and the num lock key, if applicable.
1574
1575=item $screen = $term->current_screen
1576
1577Returns the currently displayed screen (0 primary, 1 secondary).
1578
1579=item $cursor_is_hidden = $term->hidden_cursor
1580
1581Returns whether the cursor is currently hidden or not.
1277 1582
1278=item $view_start = $term->view_start ([$newvalue]) 1583=item $view_start = $term->view_start ([$newvalue])
1279 1584
1280Returns the row number of the topmost displayed line. Maximum value is 1585Returns the row number of the topmost displayed line. Maximum value is
1281C<0>, which displays the normal terminal contents. Lower values scroll 1586C<0>, which displays the normal terminal contents. Lower values scroll
1289 1594
1290Used after changing terminal contents to display them. 1595Used after changing terminal contents to display them.
1291 1596
1292=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1597=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1293 1598
1294Returns the text of the entire row with number C<$row_number>. Row C<0> 1599Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1295is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1600is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1296terminal line. The scrollback buffer starts at line C<-1> and extends to
1297line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1601terminal line. Nothing will be returned if a nonexistent line
1298is requested. 1602is requested.
1299 1603
1300If C<$new_text> is specified, it will replace characters in the current 1604If C<$new_text> is specified, it will replace characters in the current
1301line, starting at column C<$start_col> (default C<0>), which is useful 1605line, 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 1606to replace only parts of a line. The font index in the rendition will
1303automatically be updated. 1607automatically be updated.
1304 1608
1305C<$text> is in a special encoding: tabs and wide characters that use more 1609C<$text> is in a special encoding: tabs and wide characters that use more
1306than one cell when displayed are padded with urxvt::NOCHAR characters 1610than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1307(C<chr 65535>). Characters with combining characters and other characters 1611characters. Characters with combining characters and other characters that
1308that do not fit into the normal tetx encoding will be replaced with 1612do not fit into the normal text encoding will be replaced with characters
1309characters in the private use area. 1613in the private use area.
1310 1614
1311You have to obey this encoding when changing text. The advantage is 1615You have to obey this encoding when changing text. The advantage is
1312that C<substr> and similar functions work on screen cells and not on 1616that C<substr> and similar functions work on screen cells and not on
1313characters. 1617characters.
1314 1618
1398} 1702}
1399 1703
1400sub urxvt::line::t { 1704sub urxvt::line::t {
1401 my ($self) = @_; 1705 my ($self) = @_;
1402 1706
1403 if (@_ > 1) 1707 if (@_ > 1) {
1404 {
1405 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1708 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1406 for $self->{beg} .. $self->{end}; 1709 for $self->{beg} .. $self->{end};
1407 } 1710 }
1408 1711
1409 defined wantarray && 1712 defined wantarray &&
1410 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1713 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1411 0, $self->{len} 1714 0, $self->{len}
1412} 1715}
1413 1716
1414sub urxvt::line::r { 1717sub urxvt::line::r {
1415 my ($self) = @_; 1718 my ($self) = @_;
1416 1719
1417 if (@_ > 1) 1720 if (@_ > 1) {
1418 {
1419 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) 1721 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1420 for $self->{beg} .. $self->{end}; 1722 for $self->{beg} .. $self->{end};
1421 } 1723 }
1422 1724
1423 if (defined wantarray) { 1725 if (defined wantarray) {
1424 my $rend = [ 1726 my $rend = [
1425 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1727 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1426 ]; 1728 ];
1458where one character corresponds to one screen cell. See 1760where one character corresponds to one screen cell. See
1459C<< $term->ROW_t >> for details. 1761C<< $term->ROW_t >> for details.
1460 1762
1461=item $string = $term->special_decode $text 1763=item $string = $term->special_decode $text
1462 1764
1463Converts rxvt-unicodes text reprsentation into a perl string. See 1765Converts rxvt-unicodes text representation into a perl string. See
1464C<< $term->ROW_t >> for details. 1766C<< $term->ROW_t >> for details.
1465 1767
1466=item $success = $term->grab_button ($button, $modifiermask) 1768=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1467 1769
1770=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1771
1468Registers a synchronous button grab. See the XGrabButton manpage. 1772Register/unregister a synchronous button grab. See the XGrabButton
1773manpage.
1469 1774
1470=item $success = $term->grab ($eventtime[, $sync]) 1775=item $success = $term->grab ($eventtime[, $sync])
1471 1776
1472Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or 1777Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1473synchronous (C<$sync> is true). Also remembers the grab timestampe. 1778synchronous (C<$sync> is true). Also remembers the grab timestamp.
1474 1779
1475=item $term->allow_events_async 1780=item $term->allow_events_async
1476 1781
1477Calls XAllowEvents with AsyncBoth for the most recent grab. 1782Calls XAllowEvents with AsyncBoth for the most recent grab.
1478 1783
1485Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most 1790Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1486recent grab. 1791recent grab.
1487 1792
1488=item $term->ungrab 1793=item $term->ungrab
1489 1794
1490Calls XUngrab for the most recent grab. Is called automatically on 1795Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
1491evaluation errors, as it is better to lose the grab in the error case as 1796evaluation errors, as it is better to lose the grab in the error case as
1492the session. 1797the session.
1798
1799=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1800
1801=item $atom_name = $term->XGetAtomName ($atom)
1802
1803=item @atoms = $term->XListProperties ($window)
1804
1805=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1806
1807=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1808
1809=item $term->XDeleteProperty ($window, $property)
1810
1811=item $window = $term->DefaultRootWindow
1812
1813=item $term->XReparentWindow ($window, $parent, [$x, $y])
1814
1815=item $term->XMapWindow ($window)
1816
1817=item $term->XUnmapWindow ($window)
1818
1819=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1820
1821=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1822
1823=item $term->XChangeInput ($window, $add_events[, $del_events])
1824
1825=item $keysym = $term->XStringToKeysym ($string)
1826
1827=item $string = $term->XKeysymToString ($keysym)
1828
1829Various X or X-related functions. The C<$term> object only serves as
1830the source of the display, otherwise those functions map more-or-less
1831directly onto the X functions of the same name.
1493 1832
1494=back 1833=back
1495 1834
1496=cut 1835=cut
1497 1836
1561 my ($self, $text, $cb) = @_; 1900 my ($self, $text, $cb) = @_;
1562 1901
1563 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1902 $self->add_item ({ type => "button", text => $text, activate => $cb});
1564} 1903}
1565 1904
1566=item $popup->add_toggle ($text, $cb, $initial_value) 1905=item $popup->add_toggle ($text, $initial_value, $cb)
1567 1906
1568Adds a toggle/checkbox item to the popup. Teh callback gets called 1907Adds a toggle/checkbox item to the popup. The callback gets called
1569whenever it gets toggled, with a boolean indicating its value as its first 1908whenever it gets toggled, with a boolean indicating its new value as its
1570argument. 1909first argument.
1571 1910
1572=cut 1911=cut
1573 1912
1574sub add_toggle { 1913sub add_toggle {
1575 my ($self, $text, $cb, $value) = @_; 1914 my ($self, $text, $value, $cb) = @_;
1576 1915
1577 my $item; $item = { 1916 my $item; $item = {
1578 type => "button", 1917 type => "button",
1579 text => " $text", 1918 text => " $text",
1580 value => $value, 1919 value => $value,
1599 my $env = $self->{term}->env; 1938 my $env = $self->{term}->env;
1600 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE. 1939 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1601 delete $env->{LC_ALL}; 1940 delete $env->{LC_ALL};
1602 $env->{LC_CTYPE} = $self->{term}->locale; 1941 $env->{LC_CTYPE} = $self->{term}->locale;
1603 1942
1604 urxvt::term->new ($env, "popup", 1943 my $term = urxvt::term->new (
1944 $env, "popup",
1605 "--perl-lib" => "", "--perl-ext-common" => "", 1945 "--perl-lib" => "", "--perl-ext-common" => "",
1606 "-pty-fd" => -1, "-sl" => 0, 1946 "-pty-fd" => -1, "-sl" => 0,
1607 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", 1947 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1608 "--transient-for" => $self->{term}->parent, 1948 "--transient-for" => $self->{term}->parent,
1609 "-display" => $self->{term}->display_id, 1949 "-display" => $self->{term}->display_id,
1610 "-pe" => "urxvt-popup") 1950 "-pe" => "urxvt-popup",
1611 or die "unable to create popup window\n"; 1951 ) or die "unable to create popup window\n";
1952
1953 unless (delete $term->{urxvt_popup_init_done}) {
1954 $term->ungrab;
1955 $term->destroy;
1956 die "unable to initialise popup window\n";
1957 }
1612} 1958}
1613 1959
1614sub DESTROY { 1960sub DESTROY {
1615 my ($self) = @_; 1961 my ($self) = @_;
1616 1962
1617 delete $self->{term}{_destroy}{$self}; 1963 delete $self->{term}{_destroy}{$self};
1618 $self->{term}->ungrab; 1964 $self->{term}->ungrab;
1619} 1965}
1620 1966
1621=back 1967=back
1968
1969=cut
1970
1971package urxvt::watcher;
1622 1972
1623=head2 The C<urxvt::timer> Class 1973=head2 The C<urxvt::timer> Class
1624 1974
1625This class implements timer watchers/events. Time is represented as a 1975This class implements timer watchers/events. Time is represented as a
1626fractional number of seconds since the epoch. Example: 1976fractional number of seconds since the epoch. Example:
1630 ->new 1980 ->new
1631 ->interval (1) 1981 ->interval (1)
1632 ->cb (sub { 1982 ->cb (sub {
1633 $term->{overlay}->set (0, 0, 1983 $term->{overlay}->set (0, 0,
1634 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 1984 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1635 }); 1985 });
1636 1986
1637=over 4 1987=over 4
1638 1988
1639=item $timer = new urxvt::timer 1989=item $timer = new urxvt::timer
1640 1990
1643 1993
1644=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 1994=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1645 1995
1646Set the callback to be called when the timer triggers. 1996Set the callback to be called when the timer triggers.
1647 1997
1648=item $tstamp = $timer->at
1649
1650Return the time this watcher will fire next.
1651
1652=item $timer = $timer->set ($tstamp) 1998=item $timer = $timer->set ($tstamp[, $interval])
1653 1999
1654Set the time the event is generated to $tstamp. 2000Set the time the event is generated to $tstamp (and optionally specifies a
2001new $interval).
1655 2002
1656=item $timer = $timer->interval ($interval) 2003=item $timer = $timer->interval ($interval)
1657 2004
1658Normally (and when C<$interval> is C<0>), the timer will automatically 2005By default (and when C<$interval> is C<0>), the timer will automatically
1659stop after it has fired once. If C<$interval> is non-zero, then the timer 2006stop after it has fired once. If C<$interval> is non-zero, then the timer
1660is automatically rescheduled at the given intervals. 2007is automatically rescheduled at the given intervals.
1661 2008
1662=item $timer = $timer->start 2009=item $timer = $timer->start
1663 2010
1664Start the timer. 2011Start the timer.
1665 2012
1666=item $timer = $timer->start ($tstamp) 2013=item $timer = $timer->start ($tstamp[, $interval])
1667 2014
1668Set the event trigger time to C<$tstamp> and start the timer. 2015Set the event trigger time to C<$tstamp> and start the timer. Optionally
2016also replaces the interval.
1669 2017
1670=item $timer = $timer->after ($delay) 2018=item $timer = $timer->after ($delay[, $interval])
1671 2019
1672Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>. 2020Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1673 2021
1674=item $timer = $timer->stop 2022=item $timer = $timer->stop
1675 2023
1683 2031
1684 $term->{socket} = ... 2032 $term->{socket} = ...
1685 $term->{iow} = urxvt::iow 2033 $term->{iow} = urxvt::iow
1686 ->new 2034 ->new
1687 ->fd (fileno $term->{socket}) 2035 ->fd (fileno $term->{socket})
1688 ->events (urxvt::EVENT_READ) 2036 ->events (urxvt::EV_READ)
1689 ->start 2037 ->start
1690 ->cb (sub { 2038 ->cb (sub {
1691 my ($iow, $revents) = @_; 2039 my ($iow, $revents) = @_;
1692 # $revents must be 1 here, no need to check 2040 # $revents must be 1 here, no need to check
1693 sysread $term->{socket}, my $buf, 8192 2041 sysread $term->{socket}, my $buf, 8192
1706Set the callback to be called when io events are triggered. C<$reventmask> 2054Set the callback to be called when io events are triggered. C<$reventmask>
1707is a bitset as described in the C<events> method. 2055is a bitset as described in the C<events> method.
1708 2056
1709=item $iow = $iow->fd ($fd) 2057=item $iow = $iow->fd ($fd)
1710 2058
1711Set the filedescriptor (not handle) to watch. 2059Set the file descriptor (not handle) to watch.
1712 2060
1713=item $iow = $iow->events ($eventmask) 2061=item $iow = $iow->events ($eventmask)
1714 2062
1715Set the event mask to watch. The only allowed values are 2063Set the event mask to watch. The only allowed values are
1716C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed 2064C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
1717together, or C<urxvt::EVENT_NONE>. 2065together, or C<urxvt::EV_NONE>.
1718 2066
1719=item $iow = $iow->start 2067=item $iow = $iow->start
1720 2068
1721Start watching for requested events on the given handle. 2069Start watching for requested events on the given handle.
1722 2070
1723=item $iow = $iow->stop 2071=item $iow = $iow->stop
1724 2072
1725Stop watching for events on the given filehandle. 2073Stop watching for events on the given file handle.
2074
2075=back
2076
2077=head2 The C<urxvt::iw> Class
2078
2079This class implements idle watchers, that get called automatically when
2080the process is idle. They should return as fast as possible, after doing
2081some useful work.
2082
2083=over 4
2084
2085=item $iw = new urxvt::iw
2086
2087Create a new idle watcher object in stopped state.
2088
2089=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2090
2091Set the callback to be called when the watcher triggers.
2092
2093=item $timer = $timer->start
2094
2095Start the watcher.
2096
2097=item $timer = $timer->stop
2098
2099Stop the watcher.
2100
2101=back
2102
2103=head2 The C<urxvt::pw> Class
2104
2105This class implements process watchers. They create an event whenever a
2106process exits, after which they stop automatically.
2107
2108 my $pid = fork;
2109 ...
2110 $term->{pw} = urxvt::pw
2111 ->new
2112 ->start ($pid)
2113 ->cb (sub {
2114 my ($pw, $exit_status) = @_;
2115 ...
2116 });
2117
2118=over 4
2119
2120=item $pw = new urxvt::pw
2121
2122Create a new process watcher in stopped state.
2123
2124=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2125
2126Set the callback to be called when the timer triggers.
2127
2128=item $pw = $timer->start ($pid)
2129
2130Tells the watcher to start watching for process C<$pid>.
2131
2132=item $pw = $pw->stop
2133
2134Stop the watcher.
1726 2135
1727=back 2136=back
1728 2137
1729=head1 ENVIRONMENT 2138=head1 ENVIRONMENT
1730 2139
1739 2148
1740=item >= 3 - script loading and management 2149=item >= 3 - script loading and management
1741 2150
1742=item >=10 - all called hooks 2151=item >=10 - all called hooks
1743 2152
1744=item >=11 - hook reutrn values 2153=item >=11 - hook return values
1745 2154
1746=back 2155=back
1747 2156
1748=head1 AUTHOR 2157=head1 AUTHOR
1749 2158
1750 Marc Lehmann <pcg@goof.com> 2159 Marc Lehmann <schmorp@schmorp.de>
1751 http://software.schmorp.de/pkg/rxvt-unicode 2160 http://software.schmorp.de/pkg/rxvt-unicode
1752 2161
1753=cut 2162=cut
1754 2163
17551 21641
2165
2166# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines