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.51 by root, Sun Jan 8 00:27:47 2006 UTC vs.
Revision 1.209 by root, Tue Jun 5 22:38:17 2012 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --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' 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 @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31You can disable the embedded perl interpreter by setting both "perl-ext"
32and "perl-ext-common" resources to the empty string.
32 33
34=head1 PREPACKAGED EXTENSIONS
35
33This section describes the extensiosn delivered with this version. You can 36This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 37find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 38
36You can activate them like this: 39You can activate them like this:
37 40
38 @@RXVT_NAME@@ -pe <extensionname> 41 @@RXVT_NAME@@ -pe <extensionname>
39 42
43Or by adding them to the resource for extensions loaded by default:
44
45 URxvt.perl-ext-common: default,selection-autotransform
46
40=over 4 47=over 4
41 48
42=item selection 49=item selection (enabled by default)
43 50
44Intelligent selection. This extension tries to be more intelligent when 51(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 52when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 53now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 54arguments, which is very convenient, too, if your F<ls> supports
55C<--quoting-style=shell>.
48 56
49It also offers the following bindable event: 57A double-click usually selects the word under the cursor, further clicks
58will enlarge the selection.
59
60The selection works by trying to match a number of regexes and displaying
61them in increasing order of length. You can add your own regexes by
62specifying resources of the form:
63
64 URxvt.selection.pattern-0: perl-regex
65 URxvt.selection.pattern-1: perl-regex
66 ...
67
68The index number (0, 1...) must not have any holes, and each regex must
69contain at least one pair of capturing parentheses, which will be used for
70the match. For example, the following adds a regex that matches everything
71between two vertical bars:
72
73 URxvt.selection.pattern-0: \\|([^|]+)\\|
74
75Another example: Programs I use often output "absolute path: " at the
76beginning of a line when they process multiple files. The following
77pattern matches the filename (note, there is a single space at the very
78end):
79
80 URxvt.selection.pattern-0: ^(/[^:]+):\
81
82You can look at the source of the selection extension to see more
83interesting uses, such as parsing a line from beginning to end.
84
85This extension also offers following bindable keyboard commands:
50 86
51=over 4 87=over 4
52 88
53=item rot13 89=item rot13
54 90
56 92
57 URxvt.keysym.C-M-r: perl:selection:rot13 93 URxvt.keysym.C-M-r: perl:selection:rot13
58 94
59=back 95=back
60 96
61=item digital-clock 97=item option-popup (enabled by default)
62 98
63Displays a digital clock using the built-in overlay. 99Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
100runtime.
64 101
65=item mark-urls 102Other extensions can extend this popup menu by pushing a code reference
103onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104popup is being displayed.
66 105
106Its sole argument is the popup menu, which can be modified. It should
107either return nothing or a string, the initial boolean value and a code
108reference. The string will be used as button text and the code reference
109will be called when the toggle changes, with the new boolean value as
110first argument.
111
112The following will add an entry C<myoption> that changes
113C<< $self->{myoption} >>:
114
115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
117 };
118
119=item selection-popup (enabled by default)
120
121Binds a popup menu to Ctrl-Button3 that lets you convert the selection
122text into various other formats/action (such as uri unescaping, perl
123evaluation, web-browser starting etc.), depending on content.
124
125Other extensions can extend this popup menu by pushing a code reference
126onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127popup is being displayed.
128
129Its sole argument is the popup menu, which can be modified. The selection
130is in C<$_>, which can be used to decide whether to add something or not.
131It should either return nothing or a string and a code reference. The
132string will be used as button text and the code reference will be called
133when the button gets activated and should transform C<$_>.
134
135The following will add an entry C<a to b> that transforms all C<a>s in
136the selection to C<b>s, but only if the selection currently contains any
137C<a>s:
138
139 push @{ $self->{term}{selection_popup_hook} }, sub {
140 /a/ ? ("a to b" => sub { s/a/b/g }
141 : ()
142 };
143
144=item searchable-scrollback<hotkey> (enabled by default)
145
146Adds regex search functionality to the scrollback buffer, triggered
147by a hotkey (default: C<M-s>). While in search mode, normal terminal
148input/output is suspended and a regex is displayed at the bottom of the
149screen.
150
151Inputting characters appends them to the regex and continues incremental
152search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
153search upwards/downwards in the scrollback buffer, C<End> jumps to the
154bottom. C<Escape> leaves search mode and returns to the point where search
155was started, while C<Enter> or C<Return> stay at the current position and
156additionally stores the first match in the current line into the primary
157selection if the C<Shift> modifier is active.
158
159The regex defaults to "(?i)", resulting in a case-insensitive search. To
160get a case-sensitive search you can delete this prefix using C<BackSpace>
161or simply use an uppercase character which removes the "(?i)" prefix.
162
163See L<perlre> for more info about perl regular expression syntax.
164
165=item readline (enabled by default)
166
167A support package that tries to make editing with readline easier. At
168the moment, it reacts to clicking shift-left mouse button by trying to
169move the text cursor to this position. It does so by generating as many
170cursor-left or cursor-right keypresses as required (this only works
171for programs that correctly support wide characters).
172
173To avoid too many false positives, this is only done when:
174
175=over 4
176
177=item - the tty is in ICANON state.
178
179=item - the text cursor is visible.
180
181=item - the primary screen is currently being displayed.
182
183=item - the mouse is on the same (multi-row-) line as the text cursor.
184
185=back
186
187The normal selection mechanism isn't disabled, so quick successive clicks
188might interfere with selection creation in harmless ways.
189
190=item selection-autotransform
191
192This selection allows you to do automatic transforms on a selection
193whenever a selection is made.
194
195It works by specifying perl snippets (most useful is a single C<s///>
196operator) that modify C<$_> as resources:
197
198 URxvt.selection-autotransform.0: transform
199 URxvt.selection-autotransform.1: transform
200 ...
201
202For example, the following will transform selections of the form
203C<filename:number>, often seen in compiler messages, into C<vi +$filename
204$word>:
205
206 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
207
208And this example matches the same,but replaces it with vi-commands you can
209paste directly into your (vi :) editor:
210
211 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
212
213Of course, this can be modified to suit your needs and your editor :)
214
215To expand the example above to typical perl error messages ("XXX at
216FILENAME line YYY."), you need a slightly more elaborate solution:
217
218 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
219 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
220
221The first line tells the selection code to treat the unchanging part of
222every error message as a selection pattern, and the second line transforms
223the message into vi commands to load the file.
224
225=item tabbed
226
227This transforms the terminal into a tabbar with additional terminals, that
228is, it implements what is commonly referred to as "tabbed terminal". The topmost line
229displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
230button per tab.
231
232Clicking a button will activate that tab. Pressing B<Shift-Left> and
233B<Shift-Right> will switch to the tab left or right of the current one,
234while B<Shift-Down> creates a new tab.
235
236The tabbar itself can be configured similarly to a normal terminal, but
237with a resource class of C<URxvt.tabbed>. In addition, it supports the
238following four resources (shown with defaults):
239
240 URxvt.tabbed.tabbar-fg: <colour-index, default 3>
241 URxvt.tabbed.tabbar-bg: <colour-index, default 0>
242 URxvt.tabbed.tab-fg: <colour-index, default 0>
243 URxvt.tabbed.tab-bg: <colour-index, default 1>
244
245See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
246indices.
247
248=item matcher
249
67Uses per-line display filtering (C<on_line_update>) to underline urls. 250Uses per-line display filtering (C<on_line_update>) to underline text
251matching a certain pattern and make it clickable. When clicked with the
252mouse button specified in the C<matcher.button> resource (default 2, or
253middle), the program specified in the C<matcher.launcher> resource
254(default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255with the matched text as first argument. The default configuration is
256suitable for matching URLs and launching a web browser, like the
257former "mark-urls" extension.
258
259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis.
263
264It is possible to activate the most recently seen match or a list of matches
265from the keyboard. Simply bind a keysym to "perl:matcher:last" or
266"perl:matcher:list" as seen in the example below.
267
268Example configuration:
269
270 URxvt.perl-ext: default,matcher
271 URxvt.urlLauncher: sensible-browser
272 URxvt.keysym.C-Delete: perl:matcher:last
273 URxvt.keysym.M-Delete: perl:matcher:list
274 URxvt.matcher.button: 1
275 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
276 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
277 URxvt.matcher.launcher.2: gvim +$2 $1
278
279=item xim-onthespot
280
281This (experimental) perl extension implements OnTheSpot editing. It does
282not work perfectly, and some input methods don't seem to work well with
283OnTheSpot editing in general, but it seems to work at least for SCIM and
284kinput2.
285
286You enable it by specifying this extension and a preedit style of
287C<OnTheSpot>, i.e.:
288
289 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
290
291=item kuake<hotkey>
292
293A very primitive quake-console-like extension. It was inspired by a
294description of how the programs C<kuake> and C<yakuake> work: Whenever the
295user presses a global accelerator key (by default C<F10>), the terminal
296will show or hide itself. Another press of the accelerator key will hide
297or show it again.
298
299Initially, the window will not be shown when using this extension.
300
301This is useful if you need a single terminal that is not using any desktop
302space most of the time but is quickly available at the press of a key.
303
304The accelerator key is grabbed regardless of any modifiers, so this
305extension will actually grab a physical key just for this function.
306
307If you want a quake-like animation, tell your window manager to do so
308(fvwm can do it).
309
310=item overlay-osc
311
312This extension implements some OSC commands to display timed popups on the
313screen - useful for status displays from within scripts. You have to read
314the sources for more info.
68 315
69=item block-graphics-to-ascii 316=item block-graphics-to-ascii
70 317
71A not very useful example of filtering all text output to the terminal, 318A not very useful example of filtering all text output to the terminal
72by replacing all line-drawing characters (U+2500 .. U+259F) by a 319by replacing all line-drawing characters (U+2500 .. U+259F) by a
73similar-looking ascii character. 320similar-looking ascii character.
321
322=item digital-clock
323
324Displays a digital clock using the built-in overlay.
325
326=item remote-clipboard
327
328Somewhat of a misnomer, this extension adds two menu entries to the
329selection popup that allows one to run external commands to store the
330selection somewhere and fetch it again.
331
332We use it to implement a "distributed selection mechanism", which just
333means that one command uploads the file to a remote server, and another
334reads it.
335
336The commands can be set using the C<URxvt.remote-selection.store> and
337C<URxvt.remote-selection.fetch> resources. The first should read the
338selection to store from STDIN (always in UTF-8), the second should provide
339the selection data on STDOUT (also in UTF-8).
340
341The defaults (which are likely useless to you) use rsh and cat:
342
343 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
344 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
345
346=item selection-pastebin
347
348This is a little rarely useful extension that uploads the selection as
349textfile to a remote site (or does other things). (The implementation is
350not currently secure for use in a multiuser environment as it writes to
351F</tmp> directly.).
352
353It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
354i.e.
355
356 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
357
358Pressing this combination runs a command with C<%> replaced by the name of
359the textfile. This command can be set via a resource:
360
361 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
362
363And the default is likely not useful to anybody but the few people around
364here :)
365
366The name of the textfile is the hex encoded md5 sum of the selection, so
367the same content should lead to the same filename.
368
369After a successful upload the selection will be replaced by the text given
370in the C<selection-pastebin-url> resource (again, the % is the placeholder
371for the filename):
372
373 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
374
375I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
376the double C</> characters as comment start. Use C<\057\057> instead,
377which works regardless of whether xrdb is used to parse the resource file
378or not.
379
380=item macosx-clipboard and macosx-clipboard-native
381
382These two modules implement an extended clipboard for Mac OS X. They are
383used like this:
384
385 URxvt.perl-ext-common: default,macosx-clipboard
386 URxvt.keysym.M-c: perl:macosx-clipboard:copy
387 URxvt.keysym.M-v: perl:macosx-clipboard:paste
388
389The difference between them is that the native variant requires a
390perl from apple's devkit or so, and C<macosx-clipboard> requires the
391C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
392simpler etc. etc.
74 393
75=item example-refresh-hooks 394=item example-refresh-hooks
76 395
77Displays a very simple digital clock in the upper right corner of the 396Displays a very simple digital clock in the upper right corner of the
78window. Illustrates overwriting the refresh callbacks to create your own 397window. Illustrates overwriting the refresh callbacks to create your own
79overlays or changes. 398overlays or changes.
80 399
400=item confirm-paste
401
402Displays a confirmation dialog when a paste containing at least a full
403line is detected.
404
405=item bell-command
406
407Runs the command specified by the C<URxvt.bell-command> resource when
408a bell event occurs. For example, the following pops up a notification
409bubble with the text "Beep, Beep" using notify-send:
410
411 URxvt.bell-command: notify-send "Beep, Beep"
412
81=back 413=back
414
415=head1 API DOCUMENTATION
82 416
83=head2 General API Considerations 417=head2 General API Considerations
84 418
85All objects (such as terminals, time watchers etc.) are typical 419All objects (such as terminals, time watchers etc.) are typical
86reference-to-hash objects. The hash can be used to store anything you 420reference-to-hash objects. The hash can be used to store anything you
98 432
99=over 4 433=over 4
100 434
101=item $text 435=item $text
102 436
103Rxvt-unicodes special way of encoding text, where one "unicode" character 437Rxvt-unicode's special way of encoding text, where one "unicode" character
104always represents one screen cell. See L<row_t> for a discussion of this format. 438always represents one screen cell. See L<ROW_t> for a discussion of this format.
105 439
106=item $string 440=item $string
107 441
108A perl text string, with an emphasis on I<text>. It can store all unicode 442A perl text string, with an emphasis on I<text>. It can store all unicode
109characters and is to be distinguished with text encoded in a specific 443characters and is to be distinguished with text encoded in a specific
112=item $octets 446=item $octets
113 447
114Either binary data or - more common - a text string encoded in a 448Either binary data or - more common - a text string encoded in a
115locale-specific way. 449locale-specific way.
116 450
451=item $keysym
452
453an integer that is a valid X11 keysym code. You can convert a string
454into a keysym and viceversa by using C<XStringToKeysym> and
455C<XKeysymToString>.
456
457=back
458
459=head2 Extension Objects
460
461Every perl extension is a perl class. A separate perl object is created
462for each terminal, and each terminal has its own set of extension objects,
463which are passed as the first parameter to hooks. So extensions can use
464their C<$self> object without having to think about clashes with other
465extensions or other terminals, with the exception of methods and members
466that begin with an underscore character C<_>: these are reserved for
467internal use.
468
469Although it isn't a C<urxvt::term> object, you can call all methods of the
470C<urxvt::term> class on this object.
471
472It has the following methods and data members:
473
474=over 4
475
476=item $urxvt_term = $self->{term}
477
478Returns the C<urxvt::term> object associated with this instance of the
479extension. This member I<must not> be changed in any way.
480
481=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
482
483Dynamically enable the given hooks (named without the C<on_> prefix) for
484this extension, replacing any previous hook. This is useful when you want
485to overwrite time-critical hooks only temporarily.
486
487=item $self->disable ($hook_name[, $hook_name..])
488
489Dynamically disable the given hooks.
490
117=back 491=back
118 492
119=head2 Hooks 493=head2 Hooks
120 494
121The following subroutines can be declared in extension files, and will be 495The following subroutines can be declared in extension files, and will be
122called whenever the relevant event happens. 496called whenever the relevant event happens.
123 497
124The first argument passed to them is an object private to each terminal 498The first argument passed to them is an extension object as described in
125and extension package. You can call all C<urxvt::term> methods on it, but 499the in the C<Extension Objects> section.
126its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
127object that is shared between all packages is stored in the C<term>
128member. It is, however, blessed intot he package of the extension script,
129so for all practical purposes you can treat an extension script as a class.
130 500
131All of them must return a boolean value. If it is true, then the event 501B<All> of these hooks must return a boolean value. If any of the called
132counts as being I<consumed>, and the invocation of other hooks is skipped, 502hooks returns true, then the event counts as being I<consumed>, and the
133and the relevant action might not be carried out by the C++ code. 503relevant action might not be carried out by the C++ code.
134 504
135When in doubt, return a false value (preferably C<()>). 505I<< When in doubt, return a false value (preferably C<()>). >>
136 506
137=over 4 507=over 4
138 508
139=item on_init $term 509=item on_init $term
140 510
141Called after a new terminal object has been initialized, but before 511Called after a new terminal object has been initialized, but before
142windows are created or the command gets run. Most methods are unsafe to 512windows are created or the command gets run. Most methods are unsafe to
143call or deliver senseless data, as terminal size and other characteristics 513call or deliver senseless data, as terminal size and other characteristics
144have not yet been determined. You can safely query and change resources, 514have not yet been determined. You can safely query and change resources
145though. 515and options, though. For many purposes the C<on_start> hook is a better
516place.
517
518=item on_start $term
519
520Called at the very end of initialisation of a new terminal, just before
521trying to map (display) the toplevel and returning to the main loop.
522
523=item on_destroy $term
524
525Called whenever something tries to destroy terminal, when the terminal is
526still fully functional (not for long, though).
146 527
147=item on_reset $term 528=item on_reset $term
148 529
149Called after the screen is "reset" for any reason, such as resizing or 530Called after the screen is "reset" for any reason, such as resizing or
150control sequences. Here is where you can react on changes to size-related 531control sequences. Here is where you can react on changes to size-related
151variables. 532variables.
152 533
153=item on_start $term 534=item on_child_start $term, $pid
154 535
155Called at the very end of initialisation of a new terminal, just before 536Called just after the child process has been C<fork>ed.
156returning to the mainloop. 537
538=item on_child_exit $term, $status
539
540Called just after the child process has exited. C<$status> is the status
541from C<waitpid>.
157 542
158=item on_sel_make $term, $eventtime 543=item on_sel_make $term, $eventtime
159 544
160Called whenever a selection has been made by the user, but before the 545Called whenever a selection has been made by the user, but before the
161selection text is copied, so changes to the beginning, end or type of the 546selection text is copied, so changes to the beginning, end or type of the
168 553
169Called whenever a selection has been copied, but before the selection is 554Called whenever a selection has been copied, but before the selection is
170requested from the server. The selection text can be queried and changed 555requested from the server. The selection text can be queried and changed
171by calling C<< $term->selection >>. 556by calling C<< $term->selection >>.
172 557
173Returning a true value aborts selection grabbing. It will still be hilighted. 558Returning a true value aborts selection grabbing. It will still be highlighted.
174 559
175=item on_sel_extend $term 560=item on_sel_extend $term
176 561
177Called whenever the user tries to extend the selection (e.g. with a double 562Called whenever the user tries to extend the selection (e.g. with a double
178click) and is either supposed to return false (normal operation), or 563click) and is either supposed to return false (normal operation), or
179should extend the selection itelf and return true to suppress the built-in 564should extend the selection itself and return true to suppress the built-in
180processing. 565processing. This can happen multiple times, as long as the callback
566returns true, it will be called on every further click by the user and is
567supposed to enlarge the selection more and more, if possible.
181 568
182See the F<selection> example extension. 569See the F<selection> example extension.
183 570
184=item on_view_change $term, $offset 571=item on_view_change $term, $offset
185 572
186Called whenever the view offset changes, i..e the user or program 573Called whenever the view offset changes, i.e. the user or program
187scrolls. Offset C<0> means display the normal terminal, positive values 574scrolls. Offset C<0> means display the normal terminal, positive values
188show this many lines of scrollback. 575show this many lines of scrollback.
189 576
190=item on_scroll_back $term, $lines, $saved 577=item on_scroll_back $term, $lines, $saved
191 578
195 582
196It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 583It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
197$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 584$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
198number of lines that will be in the scrollback buffer. 585number of lines that will be in the scrollback buffer.
199 586
200=item on_tty_activity $term *NYI*
201
202Called whenever the program(s) running in the urxvt window send output.
203
204=item on_osc_seq $term, $string 587=item on_osc_seq $term, $op, $args, $resp
588
589Called on every OSC sequence and can be used to suppress it or modify its
590behaviour. The default should be to return an empty list. A true value
591suppresses execution of the request completely. Make sure you don't get
592confused by recursive invocations when you output an OSC sequence within
593this callback.
594
595C<on_osc_seq_perl> should be used for new behaviour.
596
597=item on_osc_seq_perl $term, $args, $resp
205 598
206Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 599Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
207operating system command) is processed. Cursor position and other state 600operating system command) is processed. Cursor position and other state
208information is up-to-date when this happens. For interoperability, the 601information is up-to-date when this happens. For interoperability, the
209string should start with the extension name and a colon, to distinguish 602string should start with the extension name (sans -osc) and a semicolon,
210it from commands for other extensions, and this might be enforced in the 603to distinguish it from commands for other extensions, and this might be
211future. 604enforced in the future.
605
606For example, C<overlay-osc> uses this:
607
608 sub on_osc_seq_perl {
609 my ($self, $osc, $resp) = @_;
610
611 return unless $osc =~ s/^overlay;//;
612
613 ... process remaining $osc string
614 }
212 615
213Be careful not ever to trust (in a security sense) the data you receive, 616Be careful not ever to trust (in a security sense) the data you receive,
214as its source can not easily be controleld (e-mail content, messages from 617as its source can not easily be controlled (e-mail content, messages from
215other users on the same system etc.). 618other users on the same system etc.).
619
620For responses, C<$resp> contains the end-of-args separator used by the
621sender.
216 622
217=item on_add_lines $term, $string 623=item on_add_lines $term, $string
218 624
219Called whenever text is about to be output, with the text as argument. You 625Called whenever text is about to be output, with the text as argument. You
220can filter/change and output the text yourself by returning a true value 626can filter/change and output the text yourself by returning a true value
221and calling C<< $term->scr_add_lines >> yourself. Please note that this 627and calling C<< $term->scr_add_lines >> yourself. Please note that this
222might be very slow, however, as your hook is called for B<all> text being 628might be very slow, however, as your hook is called for B<all> text being
223output. 629output.
224 630
631=item on_tt_write $term, $octets
632
633Called whenever some data is written to the tty/pty and can be used to
634suppress or filter tty input.
635
636=item on_tt_paste $term, $octets
637
638Called whenever text is about to be pasted, with the text as argument. You
639can filter/change and paste the text yourself by returning a true value
640and calling C<< $term->tt_paste >> yourself. C<$octets> is
641locale-encoded.
642
225=item on_line_update $term, $row 643=item on_line_update $term, $row
226 644
227Called whenever a line was updated or changed. Can be used to filter 645Called whenever a line was updated or changed. Can be used to filter
228screen output (e.g. underline urls or other useless stuff). Only lines 646screen output (e.g. underline urls or other useless stuff). Only lines
229that are being shown will be filtered, and, due to performance reasons, 647that are being shown will be filtered, and, due to performance reasons,
236later with the already-modified line (e.g. if unrelated parts change), so 654later with the already-modified line (e.g. if unrelated parts change), so
237you cannot just toggle rendition bits, but only set them. 655you cannot just toggle rendition bits, but only set them.
238 656
239=item on_refresh_begin $term 657=item on_refresh_begin $term
240 658
241Called just before the screen gets redrawn. Can be used for overlay 659Called just before the screen gets redrawn. Can be used for overlay or
242or similar effects by modify terminal contents in refresh_begin, and 660similar effects by modifying the terminal contents in refresh_begin, and
243restoring them in refresh_end. The built-in overlay and selection display 661restoring them in refresh_end. The built-in overlay and selection display
244code is run after this hook, and takes precedence. 662code is run after this hook, and takes precedence.
245 663
246=item on_refresh_end $term 664=item on_refresh_end $term
247 665
248Called just after the screen gets redrawn. See C<on_refresh_begin>. 666Called just after the screen gets redrawn. See C<on_refresh_begin>.
249 667
250=item on_keyboard_command $term, $string 668=item on_user_command $term, $string
251 669
252Called whenever the user presses a key combination that has a 670Called whenever a user-configured event is being activated (e.g. via
253C<perl:string> action bound to it (see description of the B<keysym> 671a C<perl:string> action bound to a key, see description of the B<keysym>
254resource in the @@RXVT_NAME@@(1) manpage). 672resource in the @@RXVT_NAME@@(1) manpage).
673
674The event is simply the action string. This interface is assumed to change
675slightly in the future.
676
677=item on_register_command $term, $keysym, $modifiermask, $string
678
679Called after parsing a keysym resource but before registering the
680associated binding. If this hook returns TRUE the binding is not
681registered. It can be used to modify a binding by calling
682C<register_command>.
683
684=item on_resize_all_windows $term, $new_width, $new_height
685
686Called just after the new window size has been calculated, but before
687windows are actually being resized or hints are being set. If this hook
688returns TRUE, setting of the window hints is being skipped.
689
690=item on_x_event $term, $event
691
692Called on every X event received on the vt window (and possibly other
693windows). Should only be used as a last resort. Most event structure
694members are not passed.
695
696=item on_root_event $term, $event
697
698Like C<on_x_event>, but is called for events on the root window.
255 699
256=item on_focus_in $term 700=item on_focus_in $term
257 701
258Called whenever the window gets the keyboard focus, before rxvt-unicode 702Called whenever the window gets the keyboard focus, before rxvt-unicode
259does focus in processing. 703does focus in processing.
260 704
261=item on_focus_out $term 705=item on_focus_out $term
262 706
263Called wheneever the window loses keyboard focus, before rxvt-unicode does 707Called whenever the window loses keyboard focus, before rxvt-unicode does
264focus out processing. 708focus out processing.
265 709
710=item on_configure_notify $term, $event
711
712=item on_property_notify $term, $event
713
266=item on_key_press $term, $event, $octets 714=item on_key_press $term, $event, $keysym, $octets
267 715
268=item on_key_release $term, $event 716=item on_key_release $term, $event, $keysym
269 717
270=item on_button_press $term, $event 718=item on_button_press $term, $event
271 719
272=item on_button_release $term, $event 720=item on_button_release $term, $event
273 721
275 723
276=item on_map_notify $term, $event 724=item on_map_notify $term, $event
277 725
278=item on_unmap_notify $term, $event 726=item on_unmap_notify $term, $event
279 727
280Called whenever the corresponding X event is received for the terminal If 728Called whenever the corresponding X event is received for the terminal. If
281the hook returns true, then the even will be ignored by rxvt-unicode. 729the hook returns true, then the event will be ignored by rxvt-unicode.
282 730
283The event is a hash with most values as named by Xlib (see the XEvent 731The event is a hash with most values as named by Xlib (see the XEvent
284manpage), with the additional members C<row> and C<col>, which are the row 732manpage), with the additional members C<row> and C<col>, which are the
285and column under the mouse cursor. 733(real, not screen-based) row and column under the mouse cursor.
286 734
287C<on_key_press> additionally receives the string rxvt-unicode would 735C<on_key_press> additionally receives the string rxvt-unicode would
288output, if any, in locale-specific encoding. 736output, if any, in locale-specific encoding.
289 737
290subwindow. 738subwindow.
291 739
740=item on_client_message $term, $event
741
742=item on_wm_protocols $term, $event
743
744=item on_wm_delete_window $term, $event
745
746Called when various types of ClientMessage events are received (all with
747format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
748
749=item on_bell $term
750
751Called on receipt of a bell character.
752
292=back 753=back
293 754
755=cut
756
757package urxvt;
758
759use utf8;
760use strict;
761use Carp ();
762use Scalar::Util ();
763use List::Util ();
764
765our $VERSION = 1;
766our $TERM;
767our @TERM_INIT;
768our @TERM_EXT;
769our @HOOKNAME;
770our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
771our %OPTION;
772
773our $LIBDIR;
774our $RESNAME;
775our $RESCLASS;
776our $RXVTNAME;
777
778our $NOCHAR = chr 0xffff;
779
294=head2 Variables in the C<urxvt> Package 780=head2 Variables in the C<urxvt> Package
295 781
296=over 4 782=over 4
783
784=item $urxvt::LIBDIR
785
786The rxvt-unicode library directory, where, among other things, the perl
787modules and scripts are stored.
788
789=item $urxvt::RESCLASS, $urxvt::RESCLASS
790
791The resource class and name rxvt-unicode uses to look up X resources.
792
793=item $urxvt::RXVTNAME
794
795The basename of the installed binaries, usually C<urxvt>.
297 796
298=item $urxvt::TERM 797=item $urxvt::TERM
299 798
300The current terminal. This variable stores the current C<urxvt::term> 799The current terminal. This variable stores the current C<urxvt::term>
301object, whenever a callback/hook is executing. 800object, whenever a callback/hook is executing.
302 801
802=item @urxvt::TERM_INIT
803
804All code references in this array will be called as methods of the next newly
805created C<urxvt::term> object (during the C<on_init> phase). The array
806gets cleared before the code references that were in it are being executed,
807so references can push themselves onto it again if they so desire.
808
809This complements to the perl-eval command line option, but gets executed
810first.
811
812=item @urxvt::TERM_EXT
813
814Works similar to C<@TERM_INIT>, but contains perl package/class names, which
815get registered as normal extensions after calling the hooks in C<@TERM_INIT>
816but before other extensions. Gets cleared just like C<@TERM_INIT>.
817
303=back 818=back
304 819
305=head2 Functions in the C<urxvt> Package 820=head2 Functions in the C<urxvt> Package
306 821
307=over 4 822=over 4
308 823
309=item $term = new urxvt [arg...]
310
311Creates a new terminal, very similar as if you had started it with
312C<system $binfile, arg...>. Croaks (and probably outputs an error message)
313if the new instance couldn't be created. Returns C<undef> if the new
314instance didn't initialise perl, and the terminal object otherwise. The
315C<init> and C<start> hooks will be called during the call.
316
317=item urxvt::fatal $errormessage 824=item urxvt::fatal $errormessage
318 825
319Fatally aborts execution with the given error message. Avoid at all 826Fatally aborts execution with the given error message (which should
320costs! The only time this is acceptable is when the terminal process 827include a trailing newline). Avoid at all costs! The only time this
321starts up. 828is acceptable (and useful) is in the init hook, where it prevents the
829terminal from starting up.
322 830
323=item urxvt::warn $string 831=item urxvt::warn $string
324 832
325Calls C<rxvt_warn> with the given string which should not include a 833Calls C<rxvt_warn> with the given string which should include a trailing
326newline. The module also overwrites the C<warn> builtin with a function 834newline. The module also overwrites the C<warn> builtin with a function
327that calls this function. 835that calls this function.
328 836
329Using this function has the advantage that its output ends up in the 837Using this function has the advantage that its output ends up in the
330correct place, e.g. on stderr of the connecting urxvtc client. 838correct place, e.g. on stderr of the connecting urxvtc client.
839
840Messages have a size limit of 1023 bytes currently.
841
842=item @terms = urxvt::termlist
843
844Returns all urxvt::term objects that exist in this process, regardless of
845whether they are started, being destroyed etc., so be careful. Only term
846objects that have perl extensions attached will be returned (because there
847is no urxvt::term object associated with others).
331 848
332=item $time = urxvt::NOW 849=item $time = urxvt::NOW
333 850
334Returns the "current time" (as per the event loop). 851Returns the "current time" (as per the event loop).
335 852
337 854
338=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, 855=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
339Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, 856Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
340Button4Mask, Button5Mask, AnyModifier 857Button4Mask, Button5Mask, AnyModifier
341 858
859=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
860ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
861PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
862Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
863KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
864ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
865FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
866
867=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
868EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
869GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
870UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
871ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
872CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
873SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
874
342Various constants for use in X events. 875Various constants for use in X calls and event processing.
343 876
344=back 877=back
345 878
346=head2 RENDITION 879=head2 RENDITION
347 880
362 895
363=item $rend = urxvt::OVERLAY_RSTYLE 896=item $rend = urxvt::OVERLAY_RSTYLE
364 897
365Return the rendition mask used for overlays by default. 898Return the rendition mask used for overlays by default.
366 899
367=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 900=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
901urxvt::RS_RVid, urxvt::RS_Uline
368 902
369Return the bit that enabled bold, italic, blink, reverse-video and 903Return the bit that enabled bold, italic, blink, reverse-video and
370underline, respectively. To enable such a style, just logically OR it into 904underline, respectively. To enable such a style, just logically OR it into
371the bitset. 905the bitset.
372 906
374 908
375=item $background = urxvt::GET_BASEBG $rend 909=item $background = urxvt::GET_BASEBG $rend
376 910
377Return the foreground/background colour index, respectively. 911Return the foreground/background colour index, respectively.
378 912
379=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 913=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
380 914
381=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 915=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
916
917=item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
382 918
383Replace the foreground/background colour in the rendition mask with the 919Replace the foreground/background colour in the rendition mask with the
384specified one. 920specified one.
385 921
386=item $value = urxvt::GET_CUSTOM ($rend) 922=item $value = urxvt::GET_CUSTOM $rend
387 923
388Return the "custom" value: Every rendition has 5 bits for use by 924Return the "custom" value: Every rendition has 5 bits for use by
389extensions. They can be set and changed as you like and are initially 925extensions. They can be set and changed as you like and are initially
390zero. 926zero.
391 927
392=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 928=item $rend = urxvt::SET_CUSTOM $rend, $new_value
393 929
394Change the custom value. 930Change the custom value.
395 931
396=back 932=back
397 933
398=cut 934=cut
399 935
400package urxvt;
401
402use utf8;
403use strict;
404use Scalar::Util ();
405use List::Util ();
406
407our $TERM;
408our @HOOKNAME;
409our %OPTION;
410our $LIBDIR;
411
412BEGIN { 936BEGIN {
413 urxvt->bootstrap;
414
415 # overwrite perl's warn 937 # overwrite perl's warn
416 *CORE::GLOBAL::warn = sub { 938 *CORE::GLOBAL::warn = sub {
417 my $msg = join "", @_; 939 my $msg = join "", @_;
418 $msg .= "\n" 940 $msg .= "\n"
419 unless $msg =~ /\n$/; 941 unless $msg =~ /\n$/;
420 urxvt::warn ($msg); 942 urxvt::warn ($msg);
421 }; 943 };
422} 944}
423 945
424my @hook_count; 946no warnings 'utf8';
947
948sub resource {
949 my ($term, $name, $isarg, $flag, $value) = @_;
950
951 $term->scan_meta;
952
953 warn "resourece<@_>\n";#d#
954
955 0
956}
957
958sub usage {
959 my ($term, $usage_type) = @_;
960
961 $term->scan_meta;
962
963 my $r = $term->{meta}{resource};
964
965 for my $regex (sort keys %$r) {
966 my ($ext, $type, $desc) = @{ $r->{$regex} };
967
968 $desc .= " (-pe $ext)";
969
970 if ($usage_type == 1) {
971 if ($type eq "boolean") {
972 urxvt::log sprintf " -%-20.20s %s\n", "/+$regex", $desc;
973 } else {
974 urxvt::log sprintf " -%-20.20s %s\n", "$regex $type", $desc;
975 }
976 } else {
977 urxvt::log sprintf " %-19.19s %s\n", "$regex:", $type;
978 }
979 }
980}
981
425my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 982my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
426 983
427sub verbose { 984sub verbose {
428 my ($level, $msg) = @_; 985 my ($level, $msg) = @_;
429 warn "$msg\n" if $level <= $verbosity; 986 warn "$msg\n" if $level <= $verbosity;
430} 987}
431 988
432# find on_xxx subs in the package and register them
433# as hooks
434sub register_package($) {
435 my ($pkg) = @_;
436
437 for my $htype (0.. $#HOOKNAME) {
438 my $name = $HOOKNAME[$htype];
439
440 my $ref = $pkg->can ("on_" . lc $name)
441 or next;
442
443 $TERM->{_hook}[$htype]{$pkg} = $ref;
444 $hook_count[$htype]++
445 or set_should_invoke $htype, 1;
446 }
447}
448
449my $extension_pkg = "extension0000";
450my %extension_pkg; 989my %extension_pkg;
451 990
452# load a single script into its own package, once only 991# load a single script into its own package, once only
453sub extension_package($) { 992sub extension_package($) {
454 my ($path) = @_; 993 my ($path) = @_;
455 994
456 $extension_pkg{$path} ||= do { 995 $extension_pkg{$path} ||= do {
457 my $pkg = "urxvt::" . ($extension_pkg++); 996 $path =~ /([^\/\\]+)$/;
997 my $pkg = $1;
998 $pkg =~ s/[^[:word:]]/_/g;
999 $pkg = "urxvt::ext::$pkg";
458 1000
459 verbose 3, "loading extension '$path' into package '$pkg'"; 1001 verbose 3, "loading extension '$path' into package '$pkg'";
460 1002
461 open my $fh, "<:raw", $path 1003 open my $fh, "<:raw", $path
462 or die "$path: $!"; 1004 or die "$path: $!";
463 1005
464 my $source = "package $pkg; use strict; use utf8;\n" 1006 my $source =
465 . "use base urxvt::term::proxy::;\n" 1007 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
466 . "#line 1 \"$path\"\n{\n" 1008 . "#line 1 \"$path\"\n{\n"
467 . (do { local $/; <$fh> }) 1009 . (do { local $/; <$fh> })
468 . "\n};\n1"; 1010 . "\n};\n1";
469 1011
1012 eval $source
470 eval $source or die "$path: $@"; 1013 or die "$path: $@";
471 1014
472 $pkg 1015 $pkg
473 } 1016 }
474} 1017}
475 1018
479sub invoke { 1022sub invoke {
480 local $TERM = shift; 1023 local $TERM = shift;
481 my $htype = shift; 1024 my $htype = shift;
482 1025
483 if ($htype == 0) { # INIT 1026 if ($htype == 0) { # INIT
484 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 1027 my @dirs = $TERM->perl_libdirs;
1028
1029 my %ext_arg;
1030
485 1031 {
486 my %want_ext; 1032 my @init = @TERM_INIT;
1033 @TERM_INIT = ();
1034 $_->($TERM) for @init;
1035 my @pkg = @TERM_EXT;
1036 @TERM_EXT = ();
1037 $TERM->register_package ($_) for @pkg;
1038 }
487 1039
488 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 1040 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
489 if ($_ eq "default") { 1041 if ($_ eq "default") {
490 $want_ext{$_}++ for qw(selection option-popup); 1042 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
491 } elsif (/^-(.*)$/) { 1043 } elsif (/^-(.*)$/) {
492 delete $want_ext{$1}; 1044 delete $ext_arg{$1};
1045 } elsif (/^([^<]+)<(.*)>$/) {
1046 push @{ $ext_arg{$1} }, $2;
493 } else { 1047 } else {
494 $want_ext{$_}++; 1048 $ext_arg{$_} ||= [];
495 } 1049 }
496 } 1050 }
497 1051
498 for my $ext (keys %want_ext) { 1052 for my $ext (sort keys %ext_arg) {
499 my @files = grep -f $_, map "$_/$ext", @dirs; 1053 my @files = grep -f $_, map "$_/$ext", @dirs;
500 1054
501 if (@files) { 1055 if (@files) {
502 register_package extension_package $files[0]; 1056 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
503 } else { 1057 } else {
504 warn "perl extension '$ext' not found in perl library search path\n"; 1058 warn "perl extension '$ext' not found in perl library search path\n";
505 } 1059 }
506 } 1060 }
1061
1062 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
1063 warn $@ if $@;
507 } 1064 }
508 1065
509 $retval = undef; 1066 $retval = undef;
510 1067
511 if (my $cb = $TERM->{_hook}[$htype]) { 1068 if (my $cb = $TERM->{_hook}[$htype]) {
512 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" 1069 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
513 if $verbosity >= 10; 1070 if $verbosity >= 10;
514 1071
515 keys %$cb; 1072 for my $pkg (keys %$cb) {
1073 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
1074 $retval ||= $retval_;
516 1075
517 while (my ($pkg, $cb) = each %$cb) { 1076 if ($@) {
518 eval { 1077 $TERM->ungrab; # better to lose the grab than the session
519 $retval = $cb->( 1078 warn $@;
520 $TERM->{_pkg}{$pkg} ||= do {
521 my $proxy = bless { }, $pkg;
522 Scalar::Util::weaken ($proxy->{term} = $TERM);
523 $proxy
524 },
525 @_,
526 ) and last;
527 };
528 warn $@ if $@;#d#
529 }
530 }
531
532 if ($htype == 1) { # DESTROY
533 # remove hooks if unused
534 if (my $hook = $TERM->{_hook}) {
535 for my $htype (0..$#$hook) {
536 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
537 or set_should_invoke $htype, 0;
538 } 1079 }
539 } 1080 }
540 1081
1082 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
1083 if $verbosity >= 11;
1084 }
1085
1086 if ($htype == 1) { # DESTROY
541 # clear package objects 1087 # clear package objects
542 %$_ = () for values %{ $TERM->{_pkg} }; 1088 %$_ = () for values %{ $TERM->{_pkg} };
543 1089
544 # clear package 1090 # clear package
545 %$TERM = (); 1091 %$TERM = ();
546 } 1092 }
547 1093
548 $retval 1094 $retval
549} 1095}
550 1096
551sub urxvt::term::proxy::AUTOLOAD { 1097sub SET_COLOR($$$) {
552 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 1098 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1099}
1100
1101sub rend2mask {
1102 no strict 'refs';
1103 my ($str, $mask) = (@_, 0);
1104 my %color = ( fg => undef, bg => undef );
1105 my @failed;
1106 for my $spec ( split /\s+/, $str ) {
1107 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1108 $color{lc($1)} = $2;
1109 } else {
1110 my $neg = $spec =~ s/^[-^]//;
1111 unless ( exists &{"RS_$spec"} ) {
1112 push @failed, $spec;
1113 next;
1114 }
1115 my $cur = &{"RS_$spec"};
1116 if ( $neg ) {
1117 $mask &= ~$cur;
1118 } else {
1119 $mask |= $cur;
1120 }
1121 }
1122 }
1123 ($mask, @color{qw(fg bg)}, \@failed)
1124}
1125
1126# urxvt::term::extension
1127
1128package urxvt::term::extension;
1129
1130sub enable {
1131 my ($self, %hook) = @_;
1132 my $pkg = $self->{_pkg};
1133
1134 while (my ($name, $cb) = each %hook) {
1135 my $htype = $HOOKTYPE{uc $name};
1136 defined $htype
1137 or Carp::croak "unsupported hook type '$name'";
1138
1139 $self->set_should_invoke ($htype, +1)
1140 unless exists $self->{term}{_hook}[$htype]{$pkg};
1141
1142 $self->{term}{_hook}[$htype]{$pkg} = $cb;
1143 }
1144}
1145
1146sub disable {
1147 my ($self, @hook) = @_;
1148 my $pkg = $self->{_pkg};
1149
1150 for my $name (@hook) {
1151 my $htype = $HOOKTYPE{uc $name};
1152 defined $htype
1153 or Carp::croak "unsupported hook type '$name'";
1154
1155 $self->set_should_invoke ($htype, -1)
1156 if delete $self->{term}{_hook}[$htype]{$pkg};
1157 }
1158}
1159
1160our $AUTOLOAD;
1161
1162sub AUTOLOAD {
1163 $AUTOLOAD =~ /:([^:]+)$/
553 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 1164 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
554 1165
555 eval qq{ 1166 eval qq{
556 sub $urxvt::term::proxy::AUTOLOAD { 1167 sub $AUTOLOAD {
557 my \$proxy = shift; 1168 my \$proxy = shift;
558 \$proxy->{term}->$1 (\@_) 1169 \$proxy->{term}->$1 (\@_)
559 } 1170 }
560 1 1171 1
561 } or die "FATAL: unable to compile method forwarder: $@"; 1172 } or die "FATAL: unable to compile method forwarder: $@";
562 1173
563 goto &$urxvt::term::proxy::AUTOLOAD; 1174 goto &$AUTOLOAD;
564} 1175}
1176
1177sub DESTROY {
1178 # nop
1179}
1180
1181# urxvt::destroy_hook
565 1182
566sub urxvt::destroy_hook::DESTROY { 1183sub urxvt::destroy_hook::DESTROY {
567 ${$_[0]}->(); 1184 ${$_[0]}->();
568} 1185}
569 1186
570sub urxvt::destroy_hook(&) { 1187sub urxvt::destroy_hook(&) {
571 bless \shift, urxvt::destroy_hook:: 1188 bless \shift, urxvt::destroy_hook::
572} 1189}
573 1190
1191package urxvt::anyevent;
1192
1193=head2 The C<urxvt::anyevent> Class
1194
1195The sole purpose of this class is to deliver an interface to the
1196C<AnyEvent> module - any module using it will work inside urxvt without
1197further programming. The only exception is that you cannot wait on
1198condition variables, but non-blocking condvar use is ok.
1199
1200In practical terms this means is that you cannot use blocking APIs, but
1201the non-blocking variant should work.
1202
1203=cut
1204
1205our $VERSION = '5.23';
1206
1207$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1208push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1209
1210sub timer {
1211 my ($class, %arg) = @_;
1212
1213 my $cb = $arg{cb};
1214
1215 urxvt::timer
1216 ->new
1217 ->after ($arg{after}, $arg{interval})
1218 ->cb ($arg{interval} ? $cb : sub {
1219 $_[0]->stop; # need to cancel manually
1220 $cb->();
1221 })
1222}
1223
1224sub io {
1225 my ($class, %arg) = @_;
1226
1227 my $cb = $arg{cb};
1228 my $fd = fileno $arg{fh};
1229 defined $fd or $fd = $arg{fh};
1230
1231 bless [$arg{fh}, urxvt::iow
1232 ->new
1233 ->fd ($fd)
1234 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1235 | ($arg{poll} =~ /w/ ? 2 : 0))
1236 ->start
1237 ->cb ($cb)
1238 ], urxvt::anyevent::
1239}
1240
1241sub idle {
1242 my ($class, %arg) = @_;
1243
1244 my $cb = $arg{cb};
1245
1246 urxvt::iw
1247 ->new
1248 ->start
1249 ->cb ($cb)
1250}
1251
1252sub child {
1253 my ($class, %arg) = @_;
1254
1255 my $cb = $arg{cb};
1256
1257 urxvt::pw
1258 ->new
1259 ->start ($arg{pid})
1260 ->cb (sub {
1261 $_[0]->stop; # need to cancel manually
1262 $cb->($_[0]->rpid, $_[0]->rstatus);
1263 })
1264}
1265
1266sub DESTROY {
1267 $_[0][1]->stop;
1268}
1269
1270# only needed for AnyEvent < 6 compatibility
1271sub one_event {
1272 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1273}
1274
1275package urxvt::term;
1276
574=head2 The C<urxvt::term> Class 1277=head2 The C<urxvt::term> Class
575 1278
576=over 4 1279=over 4
577 1280
1281=cut
1282
1283# find on_xxx subs in the package and register them
1284# as hooks
1285sub register_package {
1286 my ($self, $pkg, $argv) = @_;
1287
1288 no strict 'refs';
1289
1290 urxvt::verbose 6, "register package $pkg to $self";
1291
1292 @{"$pkg\::ISA"} = urxvt::term::extension::;
1293
1294 my $proxy = bless {
1295 _pkg => $pkg,
1296 argv => $argv,
1297 }, $pkg;
1298 Scalar::Util::weaken ($proxy->{term} = $self);
1299
1300 $self->{_pkg}{$pkg} = $proxy;
1301
1302 for my $name (@HOOKNAME) {
1303 if (my $ref = $pkg->can ("on_" . lc $name)) {
1304 $proxy->enable ($name => $ref);
1305 }
1306 }
1307}
1308
1309sub perl_libdirs {
1310 map { split /:/ }
1311 $_[0]->resource ("perl_lib"),
1312 $ENV{URXVT_PERL_LIB},
1313 "$ENV{HOME}/.urxvt/ext",
1314 "$LIBDIR/perl"
1315}
1316
1317sub scan_meta {
1318 my ($self) = @_;
1319 my @libdirs = perl_libdirs $self;
1320
1321 return if $self->{meta_libdirs} eq join "\x00", @libdirs;
1322
1323 my %meta;
1324
1325 $self->{meta_libdirs} = join "\x00", @libdirs;
1326 $self->{meta} = \%meta;
1327
1328 for my $dir (reverse @libdirs) {
1329 opendir my $fh, $dir
1330 or next;
1331 for my $ext (readdir $fh) {
1332 $ext ne "."
1333 and $ext ne ".."
1334 and open my $fh, "<", "$dir/$ext"
1335 or next;
1336
1337 while (<$fh>) {
1338 if (/^#:META:RESOURCE:(.*)/) {
1339 my ($regex, $type, $desc) = split /:/, $1;
1340 $regex =~ s/\$\$/$ext/g; # $$ in regex == extension name
1341 $meta{resource}{$regex} = [$ext, $type, $desc];
1342 } elsif (/^\s*(?:#|$)/) {
1343 # skip other comments and empty lines
1344 } else {
1345 last; # stop parsing on first non-empty non-comment line
1346 }
1347 }
1348 }
1349 }
1350}
1351
1352=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1353
1354Creates a new terminal, very similar as if you had started it with system
1355C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1356hash which defines the environment of the new terminal.
1357
1358Croaks (and probably outputs an error message) if the new instance
1359couldn't be created. Returns C<undef> if the new instance didn't
1360initialise perl, and the terminal object otherwise. The C<init> and
1361C<start> hooks will be called before this call returns, and are free to
1362refer to global data (which is race free).
1363
1364=cut
1365
1366sub new {
1367 my ($class, $env, @args) = @_;
1368
1369 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1370 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1371
1372 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1373}
1374
578=item $term->destroy 1375=item $term->destroy
579 1376
580Destroy the terminal object (close the window, free resources etc.). 1377Destroy the terminal object (close the window, free resources
1378etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1379watchers (timers, io watchers) are still active.
1380
1381=item $term->exec_async ($cmd[, @args])
1382
1383Works like the combination of the C<fork>/C<exec> builtins, which executes
1384("starts") programs in the background. This function takes care of setting
1385the user environment before exec'ing the command (e.g. C<PATH>) and should
1386be preferred over explicit calls to C<exec> or C<system>.
1387
1388Returns the pid of the subprocess or C<undef> on error.
1389
1390=cut
1391
1392sub exec_async {
1393 my $self = shift;
1394
1395 my $pid = fork;
1396
1397 return $pid
1398 if !defined $pid or $pid;
1399
1400 %ENV = %{ $self->env };
1401
1402 exec @_;
1403 urxvt::_exit 255;
1404}
581 1405
582=item $isset = $term->option ($optval[, $set]) 1406=item $isset = $term->option ($optval[, $set])
583 1407
584Returns true if the option specified by C<$optval> is enabled, and 1408Returns true if the option specified by C<$optval> is enabled, and
585optionally change it. All option values are stored by name in the hash 1409optionally change it. All option values are stored by name in the hash
586C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1410C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
587 1411
588Here is a a likely non-exhaustive list of option names, please see the 1412Here is a likely non-exhaustive list of option names, please see the
589source file F</src/optinc.h> to see the actual list: 1413source file F</src/optinc.h> to see the actual list:
590 1414
591 borderLess console cursorBlink cursorUnderline hold iconic insecure 1415 borderLess buffered console cursorBlink cursorUnderline hold iconic
592 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1416 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1417 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
593 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating 1418 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
594 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer 1419 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
595 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent 1420 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
596 tripleclickwords utmpInhibit visualBell 1421 urgentOnBell utmpInhibit visualBell
597 1422
598=item $value = $term->resource ($name[, $newval]) 1423=item $value = $term->resource ($name[, $newval])
599 1424
600Returns the current resource value associated with a given name and 1425Returns the current resource value associated with a given name and
601optionally sets a new value. Setting values is most useful in the C<init> 1426optionally sets a new value. Setting values is most useful in the C<init>
610likely change). 1435likely change).
611 1436
612Please note that resource strings will currently only be freed when the 1437Please note that resource strings will currently only be freed when the
613terminal is destroyed, so changing options frequently will eat memory. 1438terminal is destroyed, so changing options frequently will eat memory.
614 1439
615Here is a a likely non-exhaustive list of resource names, not all of which 1440Here is a likely non-exhaustive list of resource names, not all of which
616are supported in every build, please see the source file F</src/rsinc.h> 1441are supported in every build, please see the source file F</src/rsinc.h>
617to see the actual list: 1442to see the actual list:
618 1443
619 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1444 answerbackstring backgroundPixmap backspace_key blendtype blurradius
620 borderLess color cursorBlink cursorUnderline cutchars delete_key 1445 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
621 display_name embed ext_bwidth fade font geometry hold iconName 1446 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
622 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1447 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1448 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
623 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1449 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
624 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1450 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
625 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1451 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
626 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1452 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
627 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1453 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
628 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1454 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
629 shade term_name title transparent transparent_all tripleclickwords 1455 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1456 term_name title transient_for transparent tripleclickwords urgentOnBell
630 utmpInhibit visualBell 1457 utmpInhibit visualBell
631 1458
632=cut 1459=cut
633 1460
634sub urxvt::term::resource($$;$) { 1461sub resource($$;$) {
635 my ($self, $name) = (shift, shift); 1462 my ($self, $name) = (shift, shift);
636 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1463 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
637 &urxvt::term::_resource 1464 goto &urxvt::term::_resource
638} 1465}
1466
1467=item $value = $term->x_resource ($pattern)
1468
1469Returns the X-Resource for the given pattern, excluding the program or
1470class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1471same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1472resource with that pattern exists.
1473
1474This method should only be called during the C<on_start> hook, as there is
1475only one resource database per display, and later invocations might return
1476the wrong resources.
1477
1478=item $success = $term->parse_keysym ($key, $octets)
1479
1480Adds a key binding exactly as specified via a resource. See the
1481C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1482
1483=item $term->register_command ($keysym, $modifiermask, $string)
1484
1485Adds a key binding. This is a lower level api compared to
1486C<parse_keysym>, as it expects a parsed key description, and can be
1487used only inside either the C<on_init> hook, to add a binding, or the
1488C<on_register_command> hook, to modify a parsed binding.
639 1489
640=item $rend = $term->rstyle ([$new_rstyle]) 1490=item $rend = $term->rstyle ([$new_rstyle])
641 1491
642Return and optionally change the current rendition. Text that is output by 1492Return and optionally change the current rendition. Text that is output by
643the terminal application will use this style. 1493the terminal application will use this style.
651 1501
652=item ($row, $col) = $term->selection_beg ([$row, $col]) 1502=item ($row, $col) = $term->selection_beg ([$row, $col])
653 1503
654=item ($row, $col) = $term->selection_end ([$row, $col]) 1504=item ($row, $col) = $term->selection_end ([$row, $col])
655 1505
656Return the current values of the selection mark, begin or end positions, 1506Return the current values of the selection mark, begin or end positions.
657and optionally set them to new values.
658 1507
1508When arguments are given, then the selection coordinates are set to
1509C<$row> and C<$col>, and the selection screen is set to the current
1510screen.
1511
1512=item $screen = $term->selection_screen ([$screen])
1513
1514Returns the current selection screen, and then optionally sets it.
1515
1516=item $term->selection_make ($eventtime[, $rectangular])
1517
1518Tries to make a selection as set by C<selection_beg> and
1519C<selection_end>. If C<$rectangular> is true (default: false), a
1520rectangular selection will be made. This is the preferred function to make
1521a selection.
1522
659=item $success = $term->selection_grab ($eventtime) 1523=item $success = $term->selection_grab ($eventtime[, $clipboard])
660 1524
661Try to request the primary selection from the server (for example, as set 1525Try to acquire ownership of the primary (clipboard if C<$clipboard> is
662by the next method). 1526true) selection from the server. The corresponding text can be set
1527with the next method. No visual feedback will be given. This function
1528is mostly useful from within C<on_sel_grab> hooks.
663 1529
664=item $oldtext = $term->selection ([$newtext]) 1530=item $oldtext = $term->selection ([$newtext, $clipboard])
665 1531
666Return the current selection text and optionally replace it by C<$newtext>. 1532Return the current selection (clipboard if C<$clipboard> is true) text
1533and optionally replace it by C<$newtext>.
667 1534
1535=item $term->selection_clear ([$clipboard])
1536
1537Revoke ownership of the primary (clipboard if C<$clipboard> is true) selection.
1538
668#=item $term->overlay ($x, $y, $text) 1539=item $term->overlay_simple ($x, $y, $text)
669# 1540
670#Create a simple multi-line overlay box. See the next method for details. 1541Create a simple multi-line overlay box. See the next method for details.
671# 1542
672#=cut 1543=cut
673# 1544
674#sub urxvt::term::scr_overlay { 1545sub overlay_simple {
675# my ($self, $x, $y, $text) = @_; 1546 my ($self, $x, $y, $text) = @_;
676# 1547
677# my @lines = split /\n/, $text; 1548 my @lines = split /\n/, $text;
678# 1549
679# my $w = 0; 1550 my $w = List::Util::max map $self->strwidth ($_), @lines;
680# for (map $self->strwidth ($_), @lines) { 1551
681# $w = $_ if $w < $_;
682# }
683#
684# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1552 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
685# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1553 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
686#} 1554
1555 $overlay
1556}
687 1557
688=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1558=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
689 1559
690Create a new (empty) overlay at the given position with the given 1560Create a new (empty) overlay at the given position with the given
691width/height. C<$rstyle> defines the initial rendition style 1561width/height. C<$rstyle> defines the initial rendition style
702 1572
703The methods currently supported on C<urxvt::overlay> objects are: 1573The methods currently supported on C<urxvt::overlay> objects are:
704 1574
705=over 4 1575=over 4
706 1576
707=item $overlay->set ($x, $y, $text, $rend) 1577=item $overlay->set ($x, $y, $text[, $rend])
708 1578
709Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts 1579Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
710text in rxvt-unicode's special encoding and an array of rendition values 1580text in rxvt-unicode's special encoding and an array of rendition values
711at a specific position inside the overlay. 1581at a specific position inside the overlay.
712 1582
1583If C<$rend> is missing, then the rendition will not be changed.
1584
713=item $overlay->hide 1585=item $overlay->hide
714 1586
715If visible, hide the overlay, but do not destroy it. 1587If visible, hide the overlay, but do not destroy it.
716 1588
717=item $overlay->show 1589=item $overlay->show
726C<$event> I<must> be the event causing the menu to pop up (a button event, 1598C<$event> I<must> be the event causing the menu to pop up (a button event,
727currently). 1599currently).
728 1600
729=cut 1601=cut
730 1602
731sub urxvt::term::popup { 1603sub popup {
732 my ($self, $event) = @_; 1604 my ($self, $event) = @_;
733 1605
734 $self->grab ($event->{time}, 1) 1606 $self->grab ($event->{time}, 1)
735 or return; 1607 or return;
736 1608
758 1630
759=item $string = $term->locale_decode ($octets) 1631=item $string = $term->locale_decode ($octets)
760 1632
761Convert the given locale-encoded octets into a perl string. 1633Convert the given locale-encoded octets into a perl string.
762 1634
1635=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1636
1637XORs the rendition values in the given span with the provided value
1638(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1639refresh hooks to provide effects similar to the selection.
1640
1641=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1642
1643Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1644whitespace will additionally be xored with the C<$rstyle2>, which defaults
1645to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1646it instead. Both styles I<MUST NOT> contain font styles.
1647
1648=item $term->scr_bell
1649
1650Ring the bell!
1651
763=item $term->scr_add_lines ($string) 1652=item $term->scr_add_lines ($string)
764 1653
765Write the given text string to the screen, as if output by the application 1654Write the given text string to the screen, as if output by the application
766running inside the terminal. It may not contain command sequences (escape 1655running inside the terminal. It may not contain command sequences (escape
767codes), but is free to use line feeds, carriage returns and tabs. The 1656codes), but is free to use line feeds, carriage returns and tabs. The
769 1658
770Normally its not a good idea to use this function, as programs might be 1659Normally its not a good idea to use this function, as programs might be
771confused by changes in cursor position or scrolling. Its useful inside a 1660confused by changes in cursor position or scrolling. Its useful inside a
772C<on_add_lines> hook, though. 1661C<on_add_lines> hook, though.
773 1662
1663=item $term->scr_change_screen ($screen)
1664
1665Switch to given screen - 0 primary, 1 secondary.
1666
774=item $term->cmd_parse ($octets) 1667=item $term->cmd_parse ($octets)
775 1668
776Similar to C<scr_add_lines>, but the argument must be in the 1669Similar to C<scr_add_lines>, but the argument must be in the
777locale-specific encoding of the terminal and can contain command sequences 1670locale-specific encoding of the terminal and can contain command sequences
778(escape codes) that will be interpreted. 1671(escape codes) that will be interpreted.
779 1672
780=item $term->tt_write ($octets) 1673=item $term->tt_write ($octets)
781 1674
782Write the octets given in C<$data> to the tty (i.e. as program input). To 1675Write the octets given in C<$octets> to the tty (i.e. as program input). To
783pass characters instead of octets, you should convert your strings first 1676pass characters instead of octets, you should convert your strings first
784to the locale-specific encoding using C<< $term->locale_encode >>. 1677to the locale-specific encoding using C<< $term->locale_encode >>.
785 1678
1679=item $term->tt_paste ($octets)
1680
1681Write the octets given in C<$octets> to the tty as a paste, converting NL to
1682CR and bracketing the data with control sequences if bracketed paste mode
1683is set.
1684
1685=item $old_events = $term->pty_ev_events ([$new_events])
1686
1687Replaces the event mask of the pty watcher by the given event mask. Can
1688be used to suppress input and output handling to the pty/tty. See the
1689description of C<< urxvt::timer->events >>. Make sure to always restore
1690the previous value.
1691
1692=item $fd = $term->pty_fd
1693
1694Returns the master file descriptor for the pty in use, or C<-1> if no pty
1695is used.
1696
786=item $windowid = $term->parent 1697=item $windowid = $term->parent
787 1698
788Return the window id of the toplevel window. 1699Return the window id of the toplevel window.
789 1700
790=item $windowid = $term->vt 1701=item $windowid = $term->vt
791 1702
792Return the window id of the terminal window. 1703Return the window id of the terminal window.
793 1704
1705=item $term->vt_emask_add ($x_event_mask)
1706
1707Adds the specified events to the vt event mask. Useful e.g. when you want
1708to receive pointer events all the times:
1709
1710 $term->vt_emask_add (urxvt::PointerMotionMask);
1711
1712=item $term->set_urgency ($set)
1713
1714Enable/disable the urgency hint on the toplevel window.
1715
1716=item $term->focus_in
1717
1718=item $term->focus_out
1719
1720=item $term->key_press ($state, $keycode[, $time])
1721
1722=item $term->key_release ($state, $keycode[, $time])
1723
1724Deliver various fake events to to terminal.
1725
794=item $window_width = $term->width 1726=item $window_width = $term->width
795 1727
796=item $window_height = $term->height 1728=item $window_height = $term->height
797 1729
798=item $font_width = $term->fwidth 1730=item $font_width = $term->fwidth
811 1743
812=item $max_scrollback = $term->saveLines 1744=item $max_scrollback = $term->saveLines
813 1745
814=item $nrow_plus_saveLines = $term->total_rows 1746=item $nrow_plus_saveLines = $term->total_rows
815 1747
816=item $lines_in_scrollback = $term->nsaved 1748=item $topmost_scrollback_row = $term->top_row
817 1749
818Return various integers describing terminal characteristics. 1750Return various integers describing terminal characteristics.
1751
1752=item $x_display = $term->display_id
1753
1754Return the DISPLAY used by rxvt-unicode.
1755
1756=item $lc_ctype = $term->locale
1757
1758Returns the LC_CTYPE category string used by this rxvt-unicode.
1759
1760=item $env = $term->env
1761
1762Returns a copy of the environment in effect for the terminal as a hashref
1763similar to C<\%ENV>.
1764
1765=item @envv = $term->envv
1766
1767Returns the environment as array of strings of the form C<VAR=VALUE>.
1768
1769=item @argv = $term->argv
1770
1771Return the argument vector as this terminal, similar to @ARGV, but
1772includes the program name as first element.
1773
1774=cut
1775
1776sub env {
1777 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1778}
819 1779
820=item $modifiermask = $term->ModLevel3Mask 1780=item $modifiermask = $term->ModLevel3Mask
821 1781
822=item $modifiermask = $term->ModMetaMask 1782=item $modifiermask = $term->ModMetaMask
823 1783
824=item $modifiermask = $term->ModNumLockMask 1784=item $modifiermask = $term->ModNumLockMask
825 1785
826Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1786Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
827AltGr), the meta key (often Alt) and the num lock key, if applicable. 1787AltGr), the meta key (often Alt) and the num lock key, if applicable.
828 1788
1789=item $screen = $term->current_screen
1790
1791Returns the currently displayed screen (0 primary, 1 secondary).
1792
1793=item $cursor_is_hidden = $term->hidden_cursor
1794
1795Returns whether the cursor is currently hidden or not.
1796
829=item $view_start = $term->view_start ([$newvalue]) 1797=item $view_start = $term->view_start ([$newvalue])
830 1798
831Returns the negative row number of the topmost line. Minimum value is 1799Returns the row number of the topmost displayed line. Maximum value is
832C<0>, which displays the normal terminal contents. Larger values scroll 1800C<0>, which displays the normal terminal contents. Lower values scroll
833this many lines into the scrollback buffer. 1801this many lines into the scrollback buffer.
834 1802
835=item $term->want_refresh 1803=item $term->want_refresh
836 1804
837Requests a screen refresh. At the next opportunity, rxvt-unicode will 1805Requests a screen refresh. At the next opportunity, rxvt-unicode will
840 1808
841Used after changing terminal contents to display them. 1809Used after changing terminal contents to display them.
842 1810
843=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 1811=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
844 1812
845Returns the text of the entire row with number C<$row_number>. Row C<0> 1813Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
846is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 1814is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
847terminal line. The scrollback buffer starts at line C<-1> and extends to
848line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line 1815terminal line. Nothing will be returned if a nonexistent line
849is requested. 1816is requested.
850 1817
851If C<$new_text> is specified, it will replace characters in the current 1818If C<$new_text> is specified, it will replace characters in the current
852line, starting at column C<$start_col> (default C<0>), which is useful 1819line, starting at column C<$start_col> (default C<0>), which is useful
853to replace only parts of a line. The font index in the rendition will 1820to replace only parts of a line. The font index in the rendition will
854automatically be updated. 1821automatically be updated.
855 1822
856C<$text> is in a special encoding: tabs and wide characters that use more 1823C<$text> is in a special encoding: tabs and wide characters that use more
857than one cell when displayed are padded with urxvt::NOCHAR characters 1824than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
858(C<chr 65535>). Characters with combining characters and other characters 1825characters. Characters with combining characters and other characters that
859that do not fit into the normal tetx encoding will be replaced with 1826do not fit into the normal text encoding will be replaced with characters
860characters in the private use area. 1827in the private use area.
861 1828
862You have to obey this encoding when changing text. The advantage is 1829You have to obey this encoding when changing text. The advantage is
863that C<substr> and similar functions work on screen cells and not on 1830that C<substr> and similar functions work on screen cells and not on
864characters. 1831characters.
865 1832
916Return the row number of the first/last row of the line, respectively. 1883Return the row number of the first/last row of the line, respectively.
917 1884
918=item $offset = $line->offset_of ($row, $col) 1885=item $offset = $line->offset_of ($row, $col)
919 1886
920Returns the character offset of the given row|col pair within the logical 1887Returns the character offset of the given row|col pair within the logical
921line. 1888line. Works for rows outside the line, too, and returns corresponding
1889offsets outside the string.
922 1890
923=item ($row, $col) = $line->coord_of ($offset) 1891=item ($row, $col) = $line->coord_of ($offset)
924 1892
925Translates a string offset into terminal coordinates again. 1893Translates a string offset into terminal coordinates again.
926 1894
927=back 1895=back
928 1896
929=cut 1897=cut
930 1898
931sub urxvt::term::line { 1899sub line {
932 my ($self, $row) = @_; 1900 my ($self, $row) = @_;
933 1901
934 my $maxrow = $self->nrow - 1; 1902 my $maxrow = $self->nrow - 1;
935 1903
936 my ($beg, $end) = ($row, $row); 1904 my ($beg, $end) = ($row, $row);
1000 $offset / $self->{ncol} + $self->{beg}, 1968 $offset / $self->{ncol} + $self->{beg},
1001 $offset % $self->{ncol} 1969 $offset % $self->{ncol}
1002 ) 1970 )
1003} 1971}
1004 1972
1005=item ($row, $col) = $line->coord_of ($offset)
1006=item $text = $term->special_encode $string 1973=item $text = $term->special_encode $string
1007 1974
1008Converts a perl string into the special encoding used by rxvt-unicode, 1975Converts a perl string into the special encoding used by rxvt-unicode,
1009where one character corresponds to one screen cell. See 1976where one character corresponds to one screen cell. See
1010C<< $term->ROW_t >> for details. 1977C<< $term->ROW_t >> for details.
1011 1978
1012=item $string = $term->special_decode $text 1979=item $string = $term->special_decode $text
1013 1980
1014Converts rxvt-unicodes text reprsentation into a perl string. See 1981Converts rxvt-unicodes text representation into a perl string. See
1015C<< $term->ROW_t >> for details. 1982C<< $term->ROW_t >> for details.
1016 1983
1984=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1985
1986=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1987
1988Register/unregister a synchronous button grab. See the XGrabButton
1989manpage.
1990
1991=item $success = $term->grab ($eventtime[, $sync])
1992
1993Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1994synchronous (C<$sync> is true). Also remembers the grab timestamp.
1995
1996=item $term->allow_events_async
1997
1998Calls XAllowEvents with AsyncBoth for the most recent grab.
1999
2000=item $term->allow_events_sync
2001
2002Calls XAllowEvents with SyncBoth for the most recent grab.
2003
2004=item $term->allow_events_replay
2005
2006Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
2007recent grab.
2008
2009=item $term->ungrab
2010
2011Calls XUngrabPointer and XUngrabKeyboard for the most recent grab. Is called automatically on
2012evaluation errors, as it is better to lose the grab in the error case as
2013the session.
2014
2015=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
2016
2017=item $atom_name = $term->XGetAtomName ($atom)
2018
2019=item @atoms = $term->XListProperties ($window)
2020
2021=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
2022
2023=item $term->XChangeProperty ($window, $property, $type, $format, $octets)
2024
2025=item $term->XDeleteProperty ($window, $property)
2026
2027=item $window = $term->DefaultRootWindow
2028
2029=item $term->XReparentWindow ($window, $parent, [$x, $y])
2030
2031=item $term->XMapWindow ($window)
2032
2033=item $term->XUnmapWindow ($window)
2034
2035=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
2036
2037=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
2038
2039=item $term->XChangeInput ($window, $add_events[, $del_events])
2040
2041=item $keysym = $term->XStringToKeysym ($string)
2042
2043=item $string = $term->XKeysymToString ($keysym)
2044
2045Various X or X-related functions. The C<$term> object only serves as
2046the source of the display, otherwise those functions map more-or-less
2047directly onto the X functions of the same name.
2048
1017=back 2049=back
1018 2050
2051=cut
2052
2053package urxvt::popup;
2054
1019=head2 The C<urxvt::popup> Class 2055=head2 The C<urxvt::popup> Class
1020 2056
1021=over 4 2057=over 4
1022 2058
1023=cut 2059=cut
1024
1025package urxvt::popup;
1026 2060
1027sub add_item { 2061sub add_item {
1028 my ($self, $item) = @_; 2062 my ($self, $item) = @_;
1029 2063
2064 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
2065 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
2066 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
2067
2068 $item->{render} ||= sub { $_[0]{text} };
2069
1030 push @{ $self->{item} }, $item; 2070 push @{ $self->{item} }, $item;
1031} 2071}
2072
2073=item $popup->add_title ($title)
2074
2075Adds a non-clickable title to the popup.
2076
2077=cut
2078
2079sub add_title {
2080 my ($self, $title) = @_;
2081
2082 $self->add_item ({
2083 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
2084 text => $title,
2085 activate => sub { },
2086 });
2087}
2088
2089=item $popup->add_separator ([$sepchr])
2090
2091Creates a separator, optionally using the character given as C<$sepchr>.
2092
2093=cut
2094
2095sub add_separator {
2096 my ($self, $sep) = @_;
2097
2098 $sep ||= "=";
2099
2100 $self->add_item ({
2101 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
2102 text => "",
2103 render => sub { $sep x $self->{term}->ncol },
2104 activate => sub { },
2105 });
2106}
2107
2108=item $popup->add_button ($text, $cb)
2109
2110Adds a clickable button to the popup. C<$cb> is called whenever it is
2111selected.
2112
2113=cut
1032 2114
1033sub add_button { 2115sub add_button {
1034 my ($self, $text, $cb) = @_; 2116 my ($self, $text, $cb) = @_;
1035 2117
1036 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb, 2118 $self->add_item ({ type => "button", text => $text, activate => $cb});
1037 render => sub { $_[0]{text} },
1038 });
1039} 2119}
2120
2121=item $popup->add_toggle ($text, $initial_value, $cb)
2122
2123Adds a toggle/checkbox item to the popup. The callback gets called
2124whenever it gets toggled, with a boolean indicating its new value as its
2125first argument.
2126
2127=cut
1040 2128
1041sub add_toggle { 2129sub add_toggle {
1042 my ($self, $text, $cb, $value) = @_; 2130 my ($self, $text, $value, $cb) = @_;
1043 2131
1044 my $item; $item = { 2132 my $item; $item = {
1045 type => "button", 2133 type => "button",
1046 text => " $text", 2134 text => " $text",
1047 value => $value, 2135 value => $value,
1048 render => sub { ($item->{value} ? "" : " ") . $text }, 2136 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1049 activate => sub { $cb->($item->{value} = !$item->{value}); }, 2137 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1050 }; 2138 };
1051 2139
1052 $self->add_item ($item); 2140 $self->add_item ($item);
1053} 2141}
2142
2143=item $popup->show
2144
2145Displays the popup (which is initially hidden).
2146
2147=cut
1054 2148
1055sub show { 2149sub show {
1056 my ($self) = @_; 2150 my ($self) = @_;
1057 2151
1058 local $urxvt::popup::self = $self; 2152 local $urxvt::popup::self = $self;
1059 2153
1060 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 2154 my $env = $self->{term}->env;
2155 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
2156 delete $env->{LC_ALL};
2157 $env->{LC_CTYPE} = $self->{term}->locale;
2158
2159 my $term = urxvt::term->new (
2160 $env, "popup",
2161 "--perl-lib" => "", "--perl-ext-common" => "",
2162 "-pty-fd" => -1, "-sl" => 0,
2163 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1061 "--transient-for" => $self->{term}->parent, 2164 "--transient-for" => $self->{term}->parent,
2165 "-display" => $self->{term}->display_id,
1062 "-pe" => "urxvt-popup") 2166 "-pe" => "urxvt-popup",
1063 or die "unable to create popup window\n"; 2167 ) or die "unable to create popup window\n";
2168
2169 unless (delete $term->{urxvt_popup_init_done}) {
2170 $term->ungrab;
2171 $term->destroy;
2172 die "unable to initialise popup window\n";
2173 }
1064} 2174}
1065 2175
1066sub DESTROY { 2176sub DESTROY {
1067 my ($self) = @_; 2177 my ($self) = @_;
1068 2178
2179 delete $self->{term}{_destroy}{$self};
1069 $self->{term}->ungrab; 2180 $self->{term}->ungrab;
1070} 2181}
2182
2183=back
2184
2185=cut
2186
2187package urxvt::watcher;
1071 2188
1072=head2 The C<urxvt::timer> Class 2189=head2 The C<urxvt::timer> Class
1073 2190
1074This class implements timer watchers/events. Time is represented as a 2191This class implements timer watchers/events. Time is represented as a
1075fractional number of seconds since the epoch. Example: 2192fractional number of seconds since the epoch. Example:
1079 ->new 2196 ->new
1080 ->interval (1) 2197 ->interval (1)
1081 ->cb (sub { 2198 ->cb (sub {
1082 $term->{overlay}->set (0, 0, 2199 $term->{overlay}->set (0, 0,
1083 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); 2200 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1084 }); 2201 });
1085 2202
1086=over 4 2203=over 4
1087 2204
1088=item $timer = new urxvt::timer 2205=item $timer = new urxvt::timer
1089 2206
1092 2209
1093=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 2210=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1094 2211
1095Set the callback to be called when the timer triggers. 2212Set the callback to be called when the timer triggers.
1096 2213
1097=item $tstamp = $timer->at
1098
1099Return the time this watcher will fire next.
1100
1101=item $timer = $timer->set ($tstamp) 2214=item $timer = $timer->set ($tstamp[, $interval])
1102 2215
1103Set the time the event is generated to $tstamp. 2216Set the time the event is generated to $tstamp (and optionally specifies a
2217new $interval).
1104 2218
1105=item $timer = $timer->interval ($interval) 2219=item $timer = $timer->interval ($interval)
1106 2220
1107Normally (and when C<$interval> is C<0>), the timer will automatically 2221By default (and when C<$interval> is C<0>), the timer will automatically
1108stop after it has fired once. If C<$interval> is non-zero, then the timer 2222stop after it has fired once. If C<$interval> is non-zero, then the timer
1109is automatically rescheduled at the given intervals. 2223is automatically rescheduled at the given intervals.
1110 2224
1111=item $timer = $timer->start 2225=item $timer = $timer->start
1112 2226
1113Start the timer. 2227Start the timer.
1114 2228
1115=item $timer = $timer->start ($tstamp) 2229=item $timer = $timer->start ($tstamp[, $interval])
1116 2230
1117Set the event trigger time to C<$tstamp> and start the timer. 2231Set the event trigger time to C<$tstamp> and start the timer. Optionally
2232also replaces the interval.
2233
2234=item $timer = $timer->after ($delay[, $interval])
2235
2236Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1118 2237
1119=item $timer = $timer->stop 2238=item $timer = $timer->stop
1120 2239
1121Stop the timer. 2240Stop the timer.
1122 2241
1128 2247
1129 $term->{socket} = ... 2248 $term->{socket} = ...
1130 $term->{iow} = urxvt::iow 2249 $term->{iow} = urxvt::iow
1131 ->new 2250 ->new
1132 ->fd (fileno $term->{socket}) 2251 ->fd (fileno $term->{socket})
1133 ->events (1) # wait for read data 2252 ->events (urxvt::EV_READ)
1134 ->start 2253 ->start
1135 ->cb (sub { 2254 ->cb (sub {
1136 my ($iow, $revents) = @_; 2255 my ($iow, $revents) = @_;
1137 # $revents must be 1 here, no need to check 2256 # $revents must be 1 here, no need to check
1138 sysread $term->{socket}, my $buf, 8192 2257 sysread $term->{socket}, my $buf, 8192
1151Set the callback to be called when io events are triggered. C<$reventmask> 2270Set the callback to be called when io events are triggered. C<$reventmask>
1152is a bitset as described in the C<events> method. 2271is a bitset as described in the C<events> method.
1153 2272
1154=item $iow = $iow->fd ($fd) 2273=item $iow = $iow->fd ($fd)
1155 2274
1156Set the filedescriptor (not handle) to watch. 2275Set the file descriptor (not handle) to watch.
1157 2276
1158=item $iow = $iow->events ($eventmask) 2277=item $iow = $iow->events ($eventmask)
1159 2278
1160Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 2279Set the event mask to watch. The only allowed values are
1161data, Bit #1 (value C<2>) enables watching for write data. 2280C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2281together, or C<urxvt::EV_NONE>.
1162 2282
1163=item $iow = $iow->start 2283=item $iow = $iow->start
1164 2284
1165Start watching for requested events on the given handle. 2285Start watching for requested events on the given handle.
1166 2286
1167=item $iow = $iow->stop 2287=item $iow = $iow->stop
1168 2288
1169Stop watching for events on the given filehandle. 2289Stop watching for events on the given file handle.
2290
2291=back
2292
2293=head2 The C<urxvt::iw> Class
2294
2295This class implements idle watchers, that get called automatically when
2296the process is idle. They should return as fast as possible, after doing
2297some useful work.
2298
2299=over 4
2300
2301=item $iw = new urxvt::iw
2302
2303Create a new idle watcher object in stopped state.
2304
2305=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2306
2307Set the callback to be called when the watcher triggers.
2308
2309=item $timer = $timer->start
2310
2311Start the watcher.
2312
2313=item $timer = $timer->stop
2314
2315Stop the watcher.
2316
2317=back
2318
2319=head2 The C<urxvt::pw> Class
2320
2321This class implements process watchers. They create an event whenever a
2322process exits, after which they stop automatically.
2323
2324 my $pid = fork;
2325 ...
2326 $term->{pw} = urxvt::pw
2327 ->new
2328 ->start ($pid)
2329 ->cb (sub {
2330 my ($pw, $exit_status) = @_;
2331 ...
2332 });
2333
2334=over 4
2335
2336=item $pw = new urxvt::pw
2337
2338Create a new process watcher in stopped state.
2339
2340=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2341
2342Set the callback to be called when the timer triggers.
2343
2344=item $pw = $timer->start ($pid)
2345
2346Tells the watcher to start watching for process C<$pid>.
2347
2348=item $pw = $pw->stop
2349
2350Stop the watcher.
1170 2351
1171=back 2352=back
1172 2353
1173=head1 ENVIRONMENT 2354=head1 ENVIRONMENT
1174 2355
1177This variable controls the verbosity level of the perl extension. Higher 2358This variable controls the verbosity level of the perl extension. Higher
1178numbers indicate more verbose output. 2359numbers indicate more verbose output.
1179 2360
1180=over 4 2361=over 4
1181 2362
1182=item =0 - only fatal messages 2363=item == 0 - fatal messages
1183 2364
1184=item =3 - script loading and management 2365=item >= 3 - script loading and management
1185 2366
1186=item =10 - all events received 2367=item >=10 - all called hooks
2368
2369=item >=11 - hook return values
1187 2370
1188=back 2371=back
1189 2372
1190=head1 AUTHOR 2373=head1 AUTHOR
1191 2374
1192 Marc Lehmann <pcg@goof.com> 2375 Marc Lehmann <schmorp@schmorp.de>
1193 http://software.schmorp.de/pkg/rxvt-unicode 2376 http://software.schmorp.de/pkg/rxvt-unicode
1194 2377
1195=cut 2378=cut
1196 2379
11971 23801
2381
2382# vim: sw=3:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines