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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines