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.31 by root, Wed Jan 4 19:39:46 2006 UTC vs.
Revision 1.125 by root, Sun Jan 22 20:39:47 2006 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, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<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 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
43
40=over 4 44=over 4
41 45
42=item selection 46=item selection (enabled by default)
43 47
44Intelligent selection. This extension tries to be more intelligent when 48(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 49when the user extends selections (double-click and further clicks). Right
46urls and complete shell-quoted arguments, which is very convenient, too, 50now, it tries to select words, urls and complete shell-quoted
47if your F<ls> supports C<--quoting-style=shell>. 51arguments, which is very convenient, too, if your F<ls> supports
52C<--quoting-style=shell>.
48 53
49It also offers the following bindable event: 54A double-click usually selects the word under the cursor, further clicks
55will enlarge the selection.
56
57The selection works by trying to match a number of regexes and displaying
58them in increasing order of length. You can add your own regexes by
59specifying resources of the form:
60
61 URxvt.selection.pattern-0: perl-regex
62 URxvt.selection.pattern-1: perl-regex
63 ...
64
65The index number (0, 1...) must not have any holes, and each regex must
66contain at least one pair of capturing parentheses, which will be used for
67the match. For example, the followign adds a regex that matches everything
68between two vertical bars:
69
70 URxvt.selection.pattern-0: \\|([^|]+)\\|
71
72You can look at the source of the selection extension to see more
73interesting uses, such as parsing a line from beginning to end.
74
75This extension also offers following bindable keyboard commands:
50 76
51=over 4 77=over 4
52 78
53=item rot13 79=item rot13
54 80
55Rot-13 the selection when activated. Used via keyboard trigger: 81Rot-13 the selection when activated. Used via keyboard trigger:
56 82
57 URxvt.keysym.C-M-r: perl:selection:rot13 83 URxvt.keysym.C-M-r: perl:selection:rot13
58 84
59=back 85=back
86
87=item option-popup (enabled by default)
88
89Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
90runtime.
91
92=item selection-popup (enabled by default)
93
94Binds a popup menu to Ctrl-Button3 that lets you convert the selection
95text into various other formats/action (such as uri unescaping, perl
96evaluation, web-browser starting etc.), depending on content.
97
98Other extensions can extend this popup menu by pushing a code reference
99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
100popup is displayed.
101
102It's sole argument is the popup menu, which can be modified. The selection
103is in C<$_>, which can be used to decide wether to add something or not.
104It should either return nothing or a string and a code reference. The
105string will be used as button text and the code reference will be called
106when the button gets activated and should transform C<$_>.
107
108The following will add an entry C<a to b> that transforms all C<a>s in
109the selection to C<b>s, but only if the selection currently contains any
110C<a>s:
111
112 push @{ $self->{term}{selection_popup_hook} }, sub {
113 /a/ ? ("a to be" => sub { s/a/b/g }
114 : ()
115 };
116
117=item searchable-scrollback<hotkey> (enabled by default)
118
119Adds regex search functionality to the scrollback buffer, triggered
120by a hotkey (default: C<M-s>). While in search mode, normal terminal
121input/output is suspended and a regex is displayed at the bottom of the
122screen.
123
124Inputting characters appends them to the regex and continues incremental
125search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
126search upwards/downwards in the scrollback buffer, C<End> jumps to the
127bottom. C<Escape> leaves search mode and returns to the point where search
128was started, while C<Enter> or C<Return> stay at the current position and
129additionally stores the first match in the current line into the primary
130selection.
131
132=item readline (enabled by default)
133
134A support package that tries to make editing with readline easier. At the
135moment, it reacts to clicking with the left mouse button by trying to
136move the text cursor to this position. It does so by generating as many
137cursor-left or cursor-right keypresses as required (the this only works
138for programs that correctly support wide characters).
139
140To avoid too many false positives, this is only done when:
141
142=over 4
143
144=item - the tty is in ICANON state.
145
146=item - the text cursor is visible.
147
148=item - the primary screen is currently being displayed.
149
150=item - the mouse is on the same (multi-row-) line as the text cursor.
151
152=back
153
154The normal selection mechanism isn't disabled, so quick successive clicks
155might interfere with selection creation in harmless ways.
156
157=item selection-autotransform
158
159This selection allows you to do automatic transforms on a selection
160whenever a selection is made.
161
162It works by specifying perl snippets (most useful is a single C<s///>
163operator) that modify C<$_> as resources:
164
165 URxvt.selection-autotransform.0: transform
166 URxvt.selection-autotransform.1: transform
167 ...
168
169For example, the following will transform selections of the form
170C<filename:number>, often seen in compiler messages, into C<vi +$filename
171$word>:
172
173 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
174
175And this example matches the same,but replaces it with vi-commands you can
176paste directly into your (vi :) editor:
177
178 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
179
180Of course, this can be modified to suit your needs and your editor :)
181
182To expand the example above to typical perl error messages ("XXX at
183FILENAME line YYY."), you need a slightly more elaborate solution:
184
185 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
186 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
187
188The first line tells the selection code to treat the unchanging part of
189every error message as a selection pattern, and the second line transforms
190the message into vi commands to load the file.
191
192=item tabbed
193
194This transforms the terminal into a tabbar with additional terminals, that
195is, it implements what is commonly refered to as "tabbed terminal". The topmost line
196displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
197button per tab.
198
199Clicking a button will activate that tab. Pressing B<Shift-Left> and
200B<Shift-Right> will switch to the tab left or right of the current one,
201while B<Shift-Down> creates a new tab.
202
203=item mark-urls
204
205Uses per-line display filtering (C<on_line_update>) to underline urls and
206make them clickable. When middle-clicked, the program specified in the
207resource C<urlLauncher> (default C<x-www-browser>) will be started with
208the URL as first argument.
209
210=item automove-background
211
212This is basically a one-line extension that dynamically changes the background pixmap offset
213to the window position, in effect creating the same effect as pseudo transparency with
214a custom pixmap. No scaling is supported in this mode. Exmaple:
215
216 @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background
217
218=item block-graphics-to-ascii
219
220A not very useful example of filtering all text output to the terminal,
221by replacing all line-drawing characters (U+2500 .. U+259F) by a
222similar-looking ascii character.
60 223
61=item digital-clock 224=item digital-clock
62 225
63Displays a digital clock using the built-in overlay. 226Displays a digital clock using the built-in overlay.
64 227
66 229
67Displays a very simple digital clock in the upper right corner of the 230Displays a very simple digital clock in the upper right corner of the
68window. Illustrates overwriting the refresh callbacks to create your own 231window. Illustrates overwriting the refresh callbacks to create your own
69overlays or changes. 232overlays or changes.
70 233
234=item selection-pastebin
235
236This is a little rarely useful extension that Uploads the selection as
237textfile to a remote site (or does other things). (The implementation is
238not currently secure for use in a multiuser environment as it writes to
239F</tmp> directly.).
240
241It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
242i.e.
243
244 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
245
246Pressing this combination runs a command with C<%> replaced by the name of
247the textfile. This command can be set via a resource:
248
249 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
250
251And the default is likely not useful to anybody but the few people around
252here :)
253
254The name of the textfile is the hex encoded md5 sum of the selection, so
255the same content should lead to the same filename.
256
257After a successful upload the selection will be replaced by the text given
258in the C<selection-pastebin-url> resource (again, the % is the placeholder
259for the filename):
260
261 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
262
71=back 263=back
264
265=head1 API DOCUMENTATION
72 266
73=head2 General API Considerations 267=head2 General API Considerations
74 268
75All objects (such as terminals, time watchers etc.) are typical 269All objects (such as terminals, time watchers etc.) are typical
76reference-to-hash objects. The hash can be used to store anything you 270reference-to-hash objects. The hash can be used to store anything you
81When objects are destroyed on the C++ side, the perl object hashes are 275When objects are destroyed on the C++ side, the perl object hashes are
82emptied, so its best to store related objects such as time watchers and 276emptied, so its best to store related objects such as time watchers and
83the like inside the terminal object so they get destroyed as soon as the 277the like inside the terminal object so they get destroyed as soon as the
84terminal is destroyed. 278terminal is destroyed.
85 279
280Argument names also often indicate the type of a parameter. Here are some
281hints on what they mean:
282
283=over 4
284
285=item $text
286
287Rxvt-unicodes special way of encoding text, where one "unicode" character
288always represents one screen cell. See L<ROW_t> for a discussion of this format.
289
290=item $string
291
292A perl text string, with an emphasis on I<text>. It can store all unicode
293characters and is to be distinguished with text encoded in a specific
294encoding (often locale-specific) and binary data.
295
296=item $octets
297
298Either binary data or - more common - a text string encoded in a
299locale-specific way.
300
301=back
302
303=head2 Extension Objects
304
305Very perl extension is a perl class. A separate perl object is created
306for each terminal and each extension and passed as the first parameter to
307hooks. So extensions can use their C<$self> object without having to think
308about other extensions, with the exception of methods and members that
309begin with an underscore character C<_>: these are reserved for internal
310use.
311
312Although it isn't a C<urxvt::term> object, you can call all methods of the
313C<urxvt::term> class on this object.
314
315It has the following methods and data members:
316
317=over 4
318
319=item $urxvt_term = $self->{term}
320
321Returns the C<urxvt::term> object associated with this instance of the
322extension. This member I<must not> be changed in any way.
323
324=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
325
326Dynamically enable the given hooks (named without the C<on_> prefix) for
327this extension, replacing any previous hook. This is useful when you want
328to overwrite time-critical hooks only temporarily.
329
330=item $self->disable ($hook_name[, $hook_name..])
331
332Dynamically disable the given hooks.
333
334=back
335
86=head2 Hooks 336=head2 Hooks
87 337
88The following subroutines can be declared in loaded scripts, and will be 338The following subroutines can be declared in extension files, and will be
89called whenever the relevant event happens. 339called whenever the relevant event happens.
90 340
91The first argument passed to them is an object private to each terminal 341The first argument passed to them is an extension oject as described in
92and extension package. You can call all C<urxvt::term> methods on it, but 342the in the C<Extension Objects> section.
93its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
94object that is shared between all packages is stored in the C<term>
95member.
96 343
97All of them must return a boolean value. If it is true, then the event 344B<All> of these hooks must return a boolean value. If any of the called
98counts as being I<consumed>, and the invocation of other hooks is skipped, 345hooks returns true, then the event counts as being I<consumed>, and the
99and the relevant action might not be carried out by the C++ code. 346relevant action might not be carried out by the C++ code.
100 347
101When in doubt, return a false value (preferably C<()>). 348I<< When in doubt, return a false value (preferably C<()>). >>
102 349
103=over 4 350=over 4
104 351
105=item on_init $term 352=item on_init $term
106 353
107Called after a new terminal object has been initialized, but before 354Called after a new terminal object has been initialized, but before
108windows are created or the command gets run. 355windows are created or the command gets run. Most methods are unsafe to
356call or deliver senseless data, as terminal size and other characteristics
357have not yet been determined. You can safely query and change resources
358and options, though. For many purposes the C<on_start> hook is a better
359place.
360
361=item on_start $term
362
363Called at the very end of initialisation of a new terminal, just before
364trying to map (display) the toplevel and returning to the mainloop.
365
366=item on_destroy $term
367
368Called whenever something tries to destroy terminal, before doing anything
369yet. If this hook returns true, then destruction is skipped, but this is
370rarely a good idea.
109 371
110=item on_reset $term 372=item on_reset $term
111 373
112Called after the screen is "reset" for any reason, such as resizing or 374Called after the screen is "reset" for any reason, such as resizing or
113control sequences. Here is where you can react on changes to size-related 375control sequences. Here is where you can react on changes to size-related
114variables. 376variables.
115 377
116=item on_start $term 378=item on_child_start $term, $pid
117 379
118Called at the very end of initialisation of a new terminal, just before 380Called just after the child process has been C<fork>ed.
119returning to the mainloop. 381
382=item on_child_exit $term, $status
383
384Called just after the child process has exited. C<$status> is the status
385from C<waitpid>.
120 386
121=item on_sel_make $term, $eventtime 387=item on_sel_make $term, $eventtime
122 388
123Called whenever a selection has been made by the user, but before the 389Called whenever a selection has been made by the user, but before the
124selection text is copied, so changes to the beginning, end or type of the 390selection text is copied, so changes to the beginning, end or type of the
138=item on_sel_extend $term 404=item on_sel_extend $term
139 405
140Called whenever the user tries to extend the selection (e.g. with a double 406Called whenever the user tries to extend the selection (e.g. with a double
141click) and is either supposed to return false (normal operation), or 407click) and is either supposed to return false (normal operation), or
142should extend the selection itelf and return true to suppress the built-in 408should extend the selection itelf and return true to suppress the built-in
143processing. 409processing. This can happen multiple times, as long as the callback
410returns true, it will be called on every further click by the user and is
411supposed to enlarge the selection more and more, if possible.
144 412
145See the F<selection> example extension. 413See the F<selection> example extension.
146
147=item on_focus_in $term
148
149Called whenever the window gets the keyboard focus, before urxvt does
150focus in processing.
151
152=item on_focus_out $term
153
154Called wheneever the window loses keyboard focus, before urxvt does focus
155out processing.
156 414
157=item on_view_change $term, $offset 415=item on_view_change $term, $offset
158 416
159Called whenever the view offset changes, i..e the user or program 417Called whenever the view offset changes, i..e the user or program
160scrolls. Offset C<0> means display the normal terminal, positive values 418scrolls. Offset C<0> means display the normal terminal, positive values
167than the scroll back buffer or the terminal. 425than the scroll back buffer or the terminal.
168 426
169It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 427It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
170$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 428$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
171number of lines that will be in the scrollback buffer. 429number of lines that will be in the scrollback buffer.
172
173=item on_tty_activity $term *NYI*
174
175Called whenever the program(s) running in the urxvt window send output.
176 430
177=item on_osc_seq $term, $string 431=item on_osc_seq $term, $string
178 432
179Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 433Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
180operating system command) is processed. Cursor position and other state 434operating system command) is processed. Cursor position and other state
185 439
186Be careful not ever to trust (in a security sense) the data you receive, 440Be careful not ever to trust (in a security sense) the data you receive,
187as its source can not easily be controleld (e-mail content, messages from 441as its source can not easily be controleld (e-mail content, messages from
188other users on the same system etc.). 442other users on the same system etc.).
189 443
444=item on_add_lines $term, $string
445
446Called whenever text is about to be output, with the text as argument. You
447can filter/change and output the text yourself by returning a true value
448and calling C<< $term->scr_add_lines >> yourself. Please note that this
449might be very slow, however, as your hook is called for B<all> text being
450output.
451
452=item on_tt_write $term, $octets
453
454Called whenever some data is written to the tty/pty and can be used to
455suppress or filter tty input.
456
457=item on_line_update $term, $row
458
459Called whenever a line was updated or changed. Can be used to filter
460screen output (e.g. underline urls or other useless stuff). Only lines
461that are being shown will be filtered, and, due to performance reasons,
462not always immediately.
463
464The row number is always the topmost row of the line if the line spans
465multiple rows.
466
467Please note that, if you change the line, then the hook might get called
468later with the already-modified line (e.g. if unrelated parts change), so
469you cannot just toggle rendition bits, but only set them.
470
190=item on_refresh_begin $term 471=item on_refresh_begin $term
191 472
192Called just before the screen gets redrawn. Can be used for overlay 473Called just before the screen gets redrawn. Can be used for overlay
193or similar effects by modify terminal contents in refresh_begin, and 474or similar effects by modify terminal contents in refresh_begin, and
194restoring them in refresh_end. The built-in overlay and selection display 475restoring them in refresh_end. The built-in overlay and selection display
202 483
203Called whenever the user presses a key combination that has a 484Called whenever the user presses a key combination that has a
204C<perl:string> action bound to it (see description of the B<keysym> 485C<perl:string> action bound to it (see description of the B<keysym>
205resource in the @@RXVT_NAME@@(1) manpage). 486resource in the @@RXVT_NAME@@(1) manpage).
206 487
488=item on_x_event $term, $event
489
490Called on every X event received on the vt window (and possibly other
491windows). Should only be used as a last resort. Most event structure
492members are not passed.
493
494=item on_focus_in $term
495
496Called whenever the window gets the keyboard focus, before rxvt-unicode
497does focus in processing.
498
499=item on_focus_out $term
500
501Called wheneever the window loses keyboard focus, before rxvt-unicode does
502focus out processing.
503
504=item on_configure_notify $term, $event
505
506=item on_property_notify $term, $event
507
508=item on_key_press $term, $event, $keysym, $octets
509
510=item on_key_release $term, $event, $keysym
511
512=item on_button_press $term, $event
513
514=item on_button_release $term, $event
515
516=item on_motion_notify $term, $event
517
518=item on_map_notify $term, $event
519
520=item on_unmap_notify $term, $event
521
522Called whenever the corresponding X event is received for the terminal If
523the hook returns true, then the even will be ignored by rxvt-unicode.
524
525The event is a hash with most values as named by Xlib (see the XEvent
526manpage), with the additional members C<row> and C<col>, which are the
527(real, not screen-based) row and column under the mouse cursor.
528
529C<on_key_press> additionally receives the string rxvt-unicode would
530output, if any, in locale-specific encoding.
531
532subwindow.
533
534=item on_client_message $term, $event
535
536=item on_wm_protocols $term, $event
537
538=item on_wm_delete_window $term, $event
539
540Called when various types of ClientMessage events are received (all with
541format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
542
207=back 543=back
208 544
545=cut
546
547package urxvt;
548
549use utf8;
550use strict;
551use Carp ();
552use Scalar::Util ();
553use List::Util ();
554
555our $VERSION = 1;
556our $TERM;
557our @TERM_INIT;
558our @TERM_EXT;
559our @HOOKNAME;
560our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
561our %OPTION;
562
563our $LIBDIR;
564our $RESNAME;
565our $RESCLASS;
566our $RXVTNAME;
567
568our $NOCHAR = chr 0xffff;
569
209=head2 Variables in the C<urxvt> Package 570=head2 Variables in the C<urxvt> Package
210 571
211=over 4 572=over 4
212 573
574=item $urxvt::LIBDIR
575
576The rxvt-unicode library directory, where, among other things, the perl
577modules and scripts are stored.
578
579=item $urxvt::RESCLASS, $urxvt::RESCLASS
580
581The resource class and name rxvt-unicode uses to look up X resources.
582
583=item $urxvt::RXVTNAME
584
585The basename of the installed binaries, usually C<urxvt>.
586
213=item $urxvt::TERM 587=item $urxvt::TERM
214 588
215The current terminal. Whenever a callback/Hook is bein executed, this 589The current terminal. This variable stores the current C<urxvt::term>
216variable stores the current C<urxvt::term> object. 590object, whenever a callback/hook is executing.
591
592=item @urxvt::TERM_INIT
593
594All coderefs in this array will be called as methods of the next newly
595created C<urxvt::term> object (during the C<on_init> phase). The array
596gets cleared before the codereferences that were in it are being executed,
597so coderefs can push themselves onto it again if they so desire.
598
599This complements to the perl-eval commandline option, but gets executed
600first.
601
602=item @urxvt::TERM_EXT
603
604Works similar to C<@TERM_INIT>, but contains perl package/class names, which
605get registered as normal extensions after calling the hooks in C<@TERM_INIT>
606but before other extensions. Gets cleared just like C<@TERM_INIT>.
217 607
218=back 608=back
219 609
220=head2 Functions in the C<urxvt> Package 610=head2 Functions in the C<urxvt> Package
221 611
234that calls this function. 624that calls this function.
235 625
236Using this function has the advantage that its output ends up in the 626Using this function has the advantage that its output ends up in the
237correct place, e.g. on stderr of the connecting urxvtc client. 627correct place, e.g. on stderr of the connecting urxvtc client.
238 628
629Messages have a size limit of 1023 bytes currently.
630
239=item $time = urxvt::NOW 631=item $time = urxvt::NOW
240 632
241Returns the "current time" (as per the event loop). 633Returns the "current time" (as per the event loop).
634
635=item urxvt::CurrentTime
636
637=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
638Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
639Button4Mask, Button5Mask, AnyModifier
640
641=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
642ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
643PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
644Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
645KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
646ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
647FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
648
649=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
650EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
651GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
652UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
653ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
654CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
655SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
656
657Various constants for use in X calls and event processing.
242 658
243=back 659=back
244 660
245=head2 RENDITION 661=head2 RENDITION
246 662
273 689
274=item $background = urxvt::GET_BASEBG $rend 690=item $background = urxvt::GET_BASEBG $rend
275 691
276Return the foreground/background colour index, respectively. 692Return the foreground/background colour index, respectively.
277 693
278=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour) 694=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
279 695
280=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 696=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
281 697
282Replace the foreground/background colour in the rendition mask with the 698Replace the foreground/background colour in the rendition mask with the
283specified one. 699specified one.
284 700
285=item $value = urxvt::GET_CUSTOM ($rend) 701=item $value = urxvt::GET_CUSTOM $rend
286 702
287Return the "custom" value: Every rendition has 5 bits for use by 703Return the "custom" value: Every rendition has 5 bits for use by
288extensions. They can be set and changed as you like and are initially 704extensions. They can be set and changed as you like and are initially
289zero. 705zero.
290 706
291=item $rend = urxvt::SET_CUSTOM ($rend, $new_value) 707=item $rend = urxvt::SET_CUSTOM $rend, $new_value
292 708
293Change the custom value. 709Change the custom value.
294 710
295=back 711=back
296 712
297=cut 713=cut
298 714
299package urxvt;
300
301use strict;
302use Scalar::Util ();
303
304our $TERM;
305our @HOOKNAME;
306our $LIBDIR;
307
308BEGIN { 715BEGIN {
309 urxvt->bootstrap;
310
311 # overwrite perl's warn 716 # overwrite perl's warn
312 *CORE::GLOBAL::warn = sub { 717 *CORE::GLOBAL::warn = sub {
313 my $msg = join "", @_; 718 my $msg = join "", @_;
314 $msg .= "\n" 719 $msg .= "\n"
315 unless $msg =~ /\n$/; 720 unless $msg =~ /\n$/;
316 urxvt::warn ($msg); 721 urxvt::warn ($msg);
317 }; 722 };
318} 723}
319 724
320my @hook_count; 725no warnings 'utf8';
726
321my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 727my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
322 728
323sub verbose { 729sub verbose {
324 my ($level, $msg) = @_; 730 my ($level, $msg) = @_;
325 warn "$msg\n" if $level <= $verbosity; 731 warn "$msg\n" if $level <= $verbosity;
326} 732}
327 733
328# find on_xxx subs in the package and register them 734my %extension_pkg;
329# as hooks
330sub register_package($) {
331 my ($pkg) = @_;
332
333 for my $htype (0.. $#HOOKNAME) {
334 my $name = $HOOKNAME[$htype];
335
336 my $ref = $pkg->can ("on_" . lc $name)
337 or next;
338
339 $TERM->{_hook}[$htype]{$pkg} = $ref;
340 $hook_count[$htype]++
341 or set_should_invoke $htype, 1;
342 }
343}
344
345my $script_pkg = "script0000";
346my %script_pkg;
347 735
348# load a single script into its own package, once only 736# load a single script into its own package, once only
349sub script_package($) { 737sub extension_package($) {
350 my ($path) = @_; 738 my ($path) = @_;
351 739
352 $script_pkg{$path} ||= do { 740 $extension_pkg{$path} ||= do {
353 my $pkg = "urxvt::" . ($script_pkg++); 741 $path =~ /([^\/\\]+)$/;
742 my $pkg = $1;
743 $pkg =~ s/[^[:word:]]/_/g;
744 $pkg = "urxvt::ext::$pkg";
354 745
355 verbose 3, "loading script '$path' into package '$pkg'"; 746 verbose 3, "loading extension '$path' into package '$pkg'";
356 747
357 open my $fh, "<:raw", $path 748 open my $fh, "<:raw", $path
358 or die "$path: $!"; 749 or die "$path: $!";
359 750
360 my $source = "package $pkg; use strict; use utf8;\n" 751 my $source =
752 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
361 . "#line 1 \"$path\"\n{\n" 753 . "#line 1 \"$path\"\n{\n"
362 . (do { local $/; <$fh> }) 754 . (do { local $/; <$fh> })
363 . "\n};\n1"; 755 . "\n};\n1";
364 756
757 eval $source
365 eval $source or die "$path: $@"; 758 or die "$path: $@";
366 759
367 $pkg 760 $pkg
368 } 761 }
369} 762}
370 763
375 local $TERM = shift; 768 local $TERM = shift;
376 my $htype = shift; 769 my $htype = shift;
377 770
378 if ($htype == 0) { # INIT 771 if ($htype == 0) { # INIT
379 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 772 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
773
774 my %ext_arg;
380 775
776 {
777 my @init = @TERM_INIT;
778 @TERM_INIT = ();
779 $_->($TERM) for @init;
780 my @pkg = @TERM_EXT;
781 @TERM_EXT = ();
782 $TERM->register_package ($_) for @pkg;
783 }
784
381 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 785 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
786 if ($_ eq "default") {
787 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
788 } elsif (/^-(.*)$/) {
789 delete $ext_arg{$1};
790 } elsif (/^([^<]+)<(.*)>$/) {
791 push @{ $ext_arg{$1} }, $2;
792 } else {
793 $ext_arg{$_} ||= [];
794 }
795 }
796
797 while (my ($ext, $argv) = each %ext_arg) {
382 my @files = grep -f $_, map "$_/$ext", @dirs; 798 my @files = grep -f $_, map "$_/$ext", @dirs;
383 799
384 if (@files) { 800 if (@files) {
385 register_package script_package $files[0]; 801 $TERM->register_package (extension_package $files[0], $argv);
386 } else { 802 } else {
387 warn "perl extension '$ext' not found in perl library search path\n"; 803 warn "perl extension '$ext' not found in perl library search path\n";
388 } 804 }
389 } 805 }
806
807 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
808 warn $@ if $@;
390 } 809 }
391 810
392 $retval = undef; 811 $retval = undef;
393 812
394 if (my $cb = $TERM->{_hook}[$htype]) { 813 if (my $cb = $TERM->{_hook}[$htype]) {
396 if $verbosity >= 10; 815 if $verbosity >= 10;
397 816
398 keys %$cb; 817 keys %$cb;
399 818
400 while (my ($pkg, $cb) = each %$cb) { 819 while (my ($pkg, $cb) = each %$cb) {
401 $retval = $cb->( 820 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
402 $TERM->{_pkg}{$pkg} ||= do { 821 $retval ||= $retval_;
403 my $proxy = bless { }, urxvt::term::proxy::;
404 Scalar::Util::weaken ($proxy->{term} = $TERM);
405 $proxy
406 },
407 @_,
408 ) and last;
409 }
410 }
411 822
412 if ($htype == 1) { # DESTROY 823 if ($@) {
413 # remove hooks if unused 824 $TERM->ungrab; # better to lose the grab than the session
414 if (my $hook = $TERM->{_hook}) { 825 warn $@;
415 for my $htype (0..$#$hook) {
416 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
417 or set_should_invoke $htype, 0;
418 } 826 }
419 } 827 }
420 828
829 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
830 if $verbosity >= 11;
831 }
832
833 if ($htype == 1) { # DESTROY
421 # clear package objects 834 # clear package objects
422 %$_ = () for values %{ $TERM->{_pkg} }; 835 %$_ = () for values %{ $TERM->{_pkg} };
423 836
424 # clear package 837 # clear package
425 %$TERM = (); 838 %$TERM = ();
426 } 839 }
427 840
428 $retval 841 $retval
429} 842}
430 843
431sub urxvt::term::proxy::AUTOLOAD { 844# urxvt::term::extension
432 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 845
846package urxvt::term::extension;
847
848sub enable {
849 my ($self, %hook) = @_;
850 my $pkg = $self->{_pkg};
851
852 while (my ($name, $cb) = each %hook) {
853 my $htype = $HOOKTYPE{uc $name};
854 defined $htype
855 or Carp::croak "unsupported hook type '$name'";
856
857 $self->set_should_invoke ($htype, +1)
858 unless exists $self->{term}{_hook}[$htype]{$pkg};
859
860 $self->{term}{_hook}[$htype]{$pkg} = $cb;
861 }
862}
863
864sub disable {
865 my ($self, @hook) = @_;
866 my $pkg = $self->{_pkg};
867
868 for my $name (@hook) {
869 my $htype = $HOOKTYPE{uc $name};
870 defined $htype
871 or Carp::croak "unsupported hook type '$name'";
872
873 $self->set_should_invoke ($htype, -1)
874 if delete $self->{term}{_hook}[$htype]{$pkg};
875 }
876}
877
878our $AUTOLOAD;
879
880sub AUTOLOAD {
881 $AUTOLOAD =~ /:([^:]+)$/
433 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 882 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
434 883
435 eval qq{ 884 eval qq{
436 sub $urxvt::term::proxy::AUTOLOAD { 885 sub $AUTOLOAD {
437 my \$proxy = shift; 886 my \$proxy = shift;
438 \$proxy->{term}->$1 (\@_) 887 \$proxy->{term}->$1 (\@_)
439 } 888 }
440 1 889 1
441 } or die "FATAL: unable to compile method forwarder: $@"; 890 } or die "FATAL: unable to compile method forwarder: $@";
442 891
443 goto &$urxvt::term::proxy::AUTOLOAD; 892 goto &$AUTOLOAD;
444} 893}
894
895sub DESTROY {
896 # nop
897}
898
899# urxvt::destroy_hook
900
901sub urxvt::destroy_hook::DESTROY {
902 ${$_[0]}->();
903}
904
905sub urxvt::destroy_hook(&) {
906 bless \shift, urxvt::destroy_hook::
907}
908
909package urxvt::anyevent;
910
911=head2 The C<urxvt::anyevent> Class
912
913The sole purpose of this class is to deliver an interface to the
914C<AnyEvent> module - any module using it will work inside urxvt without
915further programming. The only exception is that you cannot wait on
916condition variables, but non-blocking condvar use is ok. What this means
917is that you cannot use blocking APIs, but the non-blocking variant should
918work.
919
920=cut
921
922our $VERSION = 1;
923
924$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
925push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
926
927sub timer {
928 my ($class, %arg) = @_;
929
930 my $cb = $arg{cb};
931
932 urxvt::timer
933 ->new
934 ->start (urxvt::NOW + $arg{after})
935 ->cb (sub {
936 $_[0]->stop; # need to cancel manually
937 $cb->();
938 })
939}
940
941sub io {
942 my ($class, %arg) = @_;
943
944 my $cb = $arg{cb};
945
946 bless [$arg{fh}, urxvt::iow
947 ->new
948 ->fd (fileno $arg{fh})
949 ->events (($arg{poll} =~ /r/ ? 1 : 0)
950 | ($arg{poll} =~ /w/ ? 2 : 0))
951 ->start
952 ->cb (sub {
953 $cb->(($_[1] & 1 ? 'r' : '')
954 . ($_[1] & 2 ? 'w' : ''));
955 })],
956 urxvt::anyevent::
957}
958
959sub DESTROY {
960 $_[0][1]->stop;
961}
962
963sub condvar {
964 bless \my $flag, urxvt::anyevent::condvar::
965}
966
967sub urxvt::anyevent::condvar::broadcast {
968 ${$_[0]}++;
969}
970
971sub urxvt::anyevent::condvar::wait {
972 unless (${$_[0]}) {
973 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
974 }
975}
976
977package urxvt::term;
445 978
446=head2 The C<urxvt::term> Class 979=head2 The C<urxvt::term> Class
447 980
448=over 4 981=over 4
982
983=cut
984
985# find on_xxx subs in the package and register them
986# as hooks
987sub register_package {
988 my ($self, $pkg, $argv) = @_;
989
990 no strict 'refs';
991
992 urxvt::verbose 6, "register package $pkg to $self";
993
994 @{"$pkg\::ISA"} = urxvt::term::extension::;
995
996 my $proxy = bless {
997 _pkg => $pkg,
998 argv => $argv,
999 }, $pkg;
1000 Scalar::Util::weaken ($proxy->{term} = $self);
1001
1002 $self->{_pkg}{$pkg} = $proxy;
1003
1004 for my $name (@HOOKNAME) {
1005 if (my $ref = $pkg->can ("on_" . lc $name)) {
1006 $proxy->enable ($name => $ref);
1007 }
1008 }
1009}
1010
1011=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1012
1013Creates a new terminal, very similar as if you had started it with system
1014C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1015hash which defines the environment of the new terminal.
1016
1017Croaks (and probably outputs an error message) if the new instance
1018couldn't be created. Returns C<undef> if the new instance didn't
1019initialise perl, and the terminal object otherwise. The C<init> and
1020C<start> hooks will be called during this call.
1021
1022=cut
1023
1024sub new {
1025 my ($class, $env, @args) = @_;
1026
1027 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
1028}
1029
1030=item $term->destroy
1031
1032Destroy the terminal object (close the window, free resources
1033etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1034watchers (timers, io watchers) are still active.
1035
1036=item $term->exec_async ($cmd[, @args])
1037
1038Works like the combination of the C<fork>/C<exec> builtins, which executes
1039("starts") programs in the background. This function takes care of setting
1040the user environment before exec'ing the command (e.g. C<PATH>) and should
1041be preferred over explicit calls to C<exec> or C<system>.
1042
1043Returns the pid of the subprocess or C<undef> on error.
1044
1045=cut
1046
1047sub exec_async {
1048 my $self = shift;
1049
1050 my $pid = fork;
1051
1052 return $pid
1053 if !defined $pid or $pid;
1054
1055 %ENV = %{ $self->env };
1056
1057 exec @_;
1058 urxvt::_exit 255;
1059}
1060
1061=item $isset = $term->option ($optval[, $set])
1062
1063Returns true if the option specified by C<$optval> is enabled, and
1064optionally change it. All option values are stored by name in the hash
1065C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1066
1067Here is a a likely non-exhaustive list of option names, please see the
1068source file F</src/optinc.h> to see the actual list:
1069
1070 borderLess console cursorBlink cursorUnderline hold iconic insecure
1071 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1072 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1073 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
1074 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
1075 transparent tripleclickwords utmpInhibit visualBell
449 1076
450=item $value = $term->resource ($name[, $newval]) 1077=item $value = $term->resource ($name[, $newval])
451 1078
452Returns the current resource value associated with a given name and 1079Returns the current resource value associated with a given name and
453optionally sets a new value. Setting values is most useful in the C<init> 1080optionally sets a new value. Setting values is most useful in the C<init>
463 1090
464Please note that resource strings will currently only be freed when the 1091Please note that resource strings will currently only be freed when the
465terminal is destroyed, so changing options frequently will eat memory. 1092terminal is destroyed, so changing options frequently will eat memory.
466 1093
467Here is a a likely non-exhaustive list of resource names, not all of which 1094Here is a a likely non-exhaustive list of resource names, not all of which
468are supported in every build, please see the source to see the actual 1095are supported in every build, please see the source file F</src/rsinc.h>
469list: 1096to see the actual list:
470 1097
471 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1098 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
472 borderLess color cursorBlink cursorUnderline cutchars delete_key 1099 borderLess color cursorBlink cursorUnderline cutchars delete_key
473 display_name embed ext_bwidth fade font geometry hold iconName 1100 display_name embed ext_bwidth fade font geometry hold iconName
474 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1101 imFont imLocale inputMethod insecure int_bwidth intensityStyles
475 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 1102 italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
476 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 1103 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
477 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 1104 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
478 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 1105 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
479 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 1106 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
480 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 1107 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
481 shade term_name title transparent transparent_all tripleclickwords 1108 secondaryScreen secondaryScroll selectstyle shade term_name title
482 utmpInhibit visualBell 1109 transient_for transparent transparent_all tripleclickwords utmpInhibit
1110 visualBell
483 1111
484=cut 1112=cut
485 1113
486sub urxvt::term::resource($$;$) { 1114sub resource($$;$) {
487 my ($self, $name) = (shift, shift); 1115 my ($self, $name) = (shift, shift);
488 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 1116 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
489 goto &urxvt::term::_resource; 1117 &urxvt::term::_resource
490} 1118}
1119
1120=item $value = $term->x_resource ($pattern)
1121
1122Returns the X-Resource for the given pattern, excluding the program or
1123class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1124same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1125resource with that pattern exists.
1126
1127This method should only be called during the C<on_start> hook, as there is
1128only one resource database per display, and later invocations might return
1129the wrong resources.
1130
1131=item $success = $term->parse_keysym ($keysym_spec, $command_string)
1132
1133Adds a keymap translation exactly as specified via a resource. See the
1134C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1135
1136=item $rend = $term->rstyle ([$new_rstyle])
1137
1138Return and optionally change the current rendition. Text that is output by
1139the terminal application will use this style.
1140
1141=item ($row, $col) = $term->screen_cur ([$row, $col])
1142
1143Return the current coordinates of the text cursor position and optionally
1144set it (which is usually bad as applications don't expect that).
491 1145
492=item ($row, $col) = $term->selection_mark ([$row, $col]) 1146=item ($row, $col) = $term->selection_mark ([$row, $col])
493 1147
494=item ($row, $col) = $term->selection_beg ([$row, $col]) 1148=item ($row, $col) = $term->selection_beg ([$row, $col])
495 1149
496=item ($row, $col) = $term->selection_end ([$row, $col]) 1150=item ($row, $col) = $term->selection_end ([$row, $col])
497 1151
498Return the current values of the selection mark, begin or end positions, 1152Return the current values of the selection mark, begin or end positions,
499and optionally set them to new values. 1153and optionally set them to new values.
500 1154
1155=item $term->selection_make ($eventtime[, $rectangular])
1156
1157Tries to make a selection as set by C<selection_beg> and
1158C<selection_end>. If C<$rectangular> is true (default: false), a
1159rectangular selection will be made. This is the prefered function to make
1160a selection.
1161
501=item $success = $term->selection_grab ($eventtime) 1162=item $success = $term->selection_grab ($eventtime)
502 1163
503Try to request the primary selection from the server (for example, as set 1164Try to request the primary selection text from the server (for example, as
504by the next method). 1165set by the next method). No visual feedback will be given. This function
1166is mostly useful from within C<on_sel_grab> hooks.
505 1167
506=item $oldtext = $term->selection ([$newtext]) 1168=item $oldtext = $term->selection ([$newtext])
507 1169
508Return the current selection text and optionally replace it by C<$newtext>. 1170Return the current selection text and optionally replace it by C<$newtext>.
509 1171
510#=item $term->overlay ($x, $y, $text) 1172=item $term->overlay_simple ($x, $y, $text)
511# 1173
512#Create a simple multi-line overlay box. See the next method for details. 1174Create a simple multi-line overlay box. See the next method for details.
513# 1175
514#=cut 1176=cut
515 1177
516sub urxvt::term::scr_overlay { 1178sub overlay_simple {
517die;
518 my ($self, $x, $y, $text) = @_; 1179 my ($self, $x, $y, $text) = @_;
519 1180
520 my @lines = split /\n/, $text; 1181 my @lines = split /\n/, $text;
521 1182
522 my $w = 0; 1183 my $w = List::Util::max map $self->strwidth ($_), @lines;
523 for (map $self->strwidth ($_), @lines) {
524 $w = $_ if $w < $_;
525 }
526 1184
527 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 1185 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
528 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1186 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
1187
1188 $overlay
529} 1189}
530 1190
531=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 1191=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
532 1192
533Create a new (empty) overlay at the given position with the given 1193Create a new (empty) overlay at the given position with the given
561 1221
562If hidden, display the overlay again. 1222If hidden, display the overlay again.
563 1223
564=back 1224=back
565 1225
1226=item $popup = $term->popup ($event)
1227
1228Creates a new C<urxvt::popup> object that implements a popup menu. The
1229C<$event> I<must> be the event causing the menu to pop up (a button event,
1230currently).
1231
1232=cut
1233
1234sub popup {
1235 my ($self, $event) = @_;
1236
1237 $self->grab ($event->{time}, 1)
1238 or return;
1239
1240 my $popup = bless {
1241 term => $self,
1242 event => $event,
1243 }, urxvt::popup::;
1244
1245 Scalar::Util::weaken $popup->{term};
1246
1247 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1248 Scalar::Util::weaken $self->{_destroy}{$popup};
1249
1250 $popup
1251}
1252
566=item $cellwidth = $term->strwidth $string 1253=item $cellwidth = $term->strwidth ($string)
567 1254
568Returns the number of screen-cells this string would need. Correctly 1255Returns the number of screen-cells this string would need. Correctly
569accounts for wide and combining characters. 1256accounts for wide and combining characters.
570 1257
571=item $octets = $term->locale_encode $string 1258=item $octets = $term->locale_encode ($string)
572 1259
573Convert the given text string into the corresponding locale encoding. 1260Convert the given text string into the corresponding locale encoding.
574 1261
575=item $string = $term->locale_decode $octets 1262=item $string = $term->locale_decode ($octets)
576 1263
577Convert the given locale-encoded octets into a perl string. 1264Convert the given locale-encoded octets into a perl string.
1265
1266=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1267
1268XORs the rendition values in the given span with the provided value
1269(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1270refresh hooks to provide effects similar to the selection.
1271
1272=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1273
1274Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1275whitespace will additionally be xored with the C<$rstyle2>, which defaults
1276to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1277it instead. Both styles I<MUST NOT> contain font styles.
1278
1279=item $term->scr_bell
1280
1281Ring the bell!
1282
1283=item $term->scr_add_lines ($string)
1284
1285Write the given text string to the screen, as if output by the application
1286running inside the terminal. It may not contain command sequences (escape
1287codes), but is free to use line feeds, carriage returns and tabs. The
1288string is a normal text string, not in locale-dependent encoding.
1289
1290Normally its not a good idea to use this function, as programs might be
1291confused by changes in cursor position or scrolling. Its useful inside a
1292C<on_add_lines> hook, though.
1293
1294=item $term->scr_change_screen ($screen)
1295
1296Switch to given screen - 0 primary, 1 secondary.
1297
1298=item $term->cmd_parse ($octets)
1299
1300Similar to C<scr_add_lines>, but the argument must be in the
1301locale-specific encoding of the terminal and can contain command sequences
1302(escape codes) that will be interpreted.
578 1303
579=item $term->tt_write ($octets) 1304=item $term->tt_write ($octets)
580 1305
581Write the octets given in C<$data> to the tty (i.e. as program input). To 1306Write the octets given in C<$data> to the tty (i.e. as program input). To
582pass characters instead of octets, you should convert your strings first 1307pass characters instead of octets, you should convert your strings first
583to the locale-specific encoding using C<< $term->locale_encode >>. 1308to the locale-specific encoding using C<< $term->locale_encode >>.
584 1309
1310=item $old_events = $term->pty_ev_events ([$new_events])
1311
1312Replaces the event mask of the pty watcher by the given event mask. Can
1313be used to suppress input and output handling to the pty/tty. See the
1314description of C<< urxvt::timer->events >>. Make sure to always restore
1315the previous value.
1316
1317=item $fd = $term->pty_fd
1318
1319Returns the master file descriptor for the pty in use, or C<-1> if no pty
1320is used.
1321
1322=item $windowid = $term->parent
1323
1324Return the window id of the toplevel window.
1325
1326=item $windowid = $term->vt
1327
1328Return the window id of the terminal window.
1329
1330=item $term->vt_emask_add ($x_event_mask)
1331
1332Adds the specified events to the vt event mask. Useful e.g. when you want
1333to receive pointer events all the times:
1334
1335 $term->vt_emask_add (urxvt::PointerMotionMask);
1336
1337=item $window_width = $term->width
1338
1339=item $window_height = $term->height
1340
1341=item $font_width = $term->fwidth
1342
1343=item $font_height = $term->fheight
1344
1345=item $font_ascent = $term->fbase
1346
585=item $nrow = $term->nrow 1347=item $terminal_rows = $term->nrow
586 1348
587=item $ncol = $term->ncol 1349=item $terminal_columns = $term->ncol
588 1350
589Return the number of rows/columns of the terminal window (i.e. as 1351=item $has_focus = $term->focus
590specified by C<-geometry>, excluding any scrollback).
591 1352
1353=item $is_mapped = $term->mapped
1354
1355=item $max_scrollback = $term->saveLines
1356
1357=item $nrow_plus_saveLines = $term->total_rows
1358
1359=item $topmost_scrollback_row = $term->top_row
1360
1361Return various integers describing terminal characteristics.
1362
1363=item $x_display = $term->display_id
1364
1365Return the DISPLAY used by rxvt-unicode.
1366
1367=item $lc_ctype = $term->locale
1368
1369Returns the LC_CTYPE category string used by this rxvt-unicode.
1370
592=item $nsaved = $term->nsaved 1371=item $env = $term->env
593 1372
594Returns the number of lines in the scrollback buffer. 1373Returns a copy of the environment in effect for the terminal as a hashref
1374similar to C<\%ENV>.
1375
1376=cut
1377
1378sub env {
1379 if (my $env = $_[0]->_env) {
1380 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1381 } else {
1382 +{ %ENV }
1383 }
1384}
1385
1386=item $modifiermask = $term->ModLevel3Mask
1387
1388=item $modifiermask = $term->ModMetaMask
1389
1390=item $modifiermask = $term->ModNumLockMask
1391
1392Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1393AltGr), the meta key (often Alt) and the num lock key, if applicable.
1394
1395=item $screen = $term->current_screen
1396
1397Returns the currently displayed screen (0 primary, 1 secondary).
1398
1399=item $cursor_is_hidden = $term->hidden_cursor
1400
1401Returns wether the cursor is currently hidden or not.
595 1402
596=item $view_start = $term->view_start ([$newvalue]) 1403=item $view_start = $term->view_start ([$newvalue])
597 1404
598Returns the negative row number of the topmost line. Minimum value is 1405Returns the row number of the topmost displayed line. Maximum value is
599C<0>, which displays the normal terminal contents. Larger values scroll 1406C<0>, which displays the normal terminal contents. Lower values scroll
600this many lines into the scrollback buffer. 1407this many lines into the scrollback buffer.
601 1408
602=item $term->want_refresh 1409=item $term->want_refresh
603 1410
604Requests a screen refresh. At the next opportunity, rxvt-unicode will 1411Requests a screen refresh. At the next opportunity, rxvt-unicode will
619line, starting at column C<$start_col> (default C<0>), which is useful 1426line, starting at column C<$start_col> (default C<0>), which is useful
620to replace only parts of a line. The font index in the rendition will 1427to replace only parts of a line. The font index in the rendition will
621automatically be updated. 1428automatically be updated.
622 1429
623C<$text> is in a special encoding: tabs and wide characters that use more 1430C<$text> is in a special encoding: tabs and wide characters that use more
624than one cell when displayed are padded with urxvt::NOCHAR characters 1431than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
625(C<chr 65535>). Characters with combining characters and other characters 1432characters. Characters with combining characters and other characters that
626that do not fit into the normal tetx encoding will be replaced with 1433do not fit into the normal tetx encoding will be replaced with characters
627characters in the private use area. 1434in the private use area.
628 1435
629You have to obey this encoding when changing text. The advantage is 1436You have to obey this encoding when changing text. The advantage is
630that C<substr> and similar functions work on screen cells and not on 1437that C<substr> and similar functions work on screen cells and not on
631characters. 1438characters.
632 1439
662about the logical line that row C<$row_number> is part of. It supports the 1469about the logical line that row C<$row_number> is part of. It supports the
663following methods: 1470following methods:
664 1471
665=over 4 1472=over 4
666 1473
667=item $text = $line->t 1474=item $text = $line->t ([$new_text])
668 1475
669Returns the full text of the line, similar to C<ROW_t> 1476Returns or replaces the full text of the line, similar to C<ROW_t>
670 1477
671=item $rend = $line->r 1478=item $rend = $line->r ([$new_rend])
672 1479
673Returns the full rendition array of the line, similar to C<ROW_r> 1480Returns or replaces the full rendition array of the line, similar to C<ROW_r>
674 1481
675=item $length = $line->l 1482=item $length = $line->l
676 1483
677Returns the length of the line in cells, similar to C<ROW_l>. 1484Returns the length of the line in cells, similar to C<ROW_l>.
678 1485
683Return the row number of the first/last row of the line, respectively. 1490Return the row number of the first/last row of the line, respectively.
684 1491
685=item $offset = $line->offset_of ($row, $col) 1492=item $offset = $line->offset_of ($row, $col)
686 1493
687Returns the character offset of the given row|col pair within the logical 1494Returns the character offset of the given row|col pair within the logical
688line. 1495line. Works for rows outside the line, too, and returns corresponding
1496offsets outside the string.
689 1497
690=item ($row, $col) = $line->coord_of ($offset) 1498=item ($row, $col) = $line->coord_of ($offset)
691 1499
692Translates a string offset into terminal coordinates again. 1500Translates a string offset into terminal coordinates again.
693 1501
694=back 1502=back
695 1503
696=cut 1504=cut
697 1505
698sub urxvt::term::line { 1506sub line {
699 my ($self, $row) = @_; 1507 my ($self, $row) = @_;
700 1508
701 my $maxrow = $self->nrow - 1; 1509 my $maxrow = $self->nrow - 1;
702 1510
703 my ($beg, $end) = ($row, $row); 1511 my ($beg, $end) = ($row, $row);
707 1515
708 bless { 1516 bless {
709 term => $self, 1517 term => $self,
710 beg => $beg, 1518 beg => $beg,
711 end => $end, 1519 end => $end,
1520 ncol => $self->ncol,
712 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 1521 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
713 }, urxvt::line:: 1522 }, urxvt::line::
714} 1523}
715 1524
716sub urxvt::line::t { 1525sub urxvt::line::t {
717 my ($self) = @_; 1526 my ($self) = @_;
718 1527
1528 if (@_ > 1)
1529 {
1530 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1531 for $self->{beg} .. $self->{end};
1532 }
1533
1534 defined wantarray &&
719 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1535 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
720 0, $self->{len} 1536 0, $self->{len}
721} 1537}
722 1538
723sub urxvt::line::r { 1539sub urxvt::line::r {
724 my ($self) = @_; 1540 my ($self) = @_;
725 1541
1542 if (@_ > 1)
1543 {
1544 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1545 for $self->{beg} .. $self->{end};
1546 }
1547
1548 if (defined wantarray) {
726 my $rend = [ 1549 my $rend = [
727 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1550 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
728 ]; 1551 ];
729 $#$rend = $self->{len} - 1; 1552 $#$rend = $self->{len} - 1;
730 $rend 1553 return $rend;
1554 }
1555
1556 ()
731} 1557}
732 1558
733sub urxvt::line::beg { $_[0]{beg} } 1559sub urxvt::line::beg { $_[0]{beg} }
734sub urxvt::line::end { $_[0]{end} } 1560sub urxvt::line::end { $_[0]{end} }
735sub urxvt::line::l { $_[0]{len} } 1561sub urxvt::line::l { $_[0]{len} }
736 1562
737sub urxvt::line::offset_of { 1563sub urxvt::line::offset_of {
738 my ($self, $row, $col) = @_; 1564 my ($self, $row, $col) = @_;
739 1565
740 ($row - $self->{beg}) * $self->{term}->ncol + $col 1566 ($row - $self->{beg}) * $self->{ncol} + $col
741} 1567}
742 1568
743sub urxvt::line::coord_of { 1569sub urxvt::line::coord_of {
744 my ($self, $offset) = @_; 1570 my ($self, $offset) = @_;
745 1571
746 use integer; 1572 use integer;
747 1573
748 ( 1574 (
749 $offset / $self->{term}->ncol + $self->{beg}, 1575 $offset / $self->{ncol} + $self->{beg},
750 $offset % $self->{term}->ncol 1576 $offset % $self->{ncol}
751 ) 1577 )
752} 1578}
753 1579
754=item ($row, $col) = $line->coord_of ($offset)
755=item $text = $term->special_encode $string 1580=item $text = $term->special_encode $string
756 1581
757Converts a perl string into the special encoding used by rxvt-unicode, 1582Converts a perl string into the special encoding used by rxvt-unicode,
758where one character corresponds to one screen cell. See 1583where one character corresponds to one screen cell. See
759C<< $term->ROW_t >> for details. 1584C<< $term->ROW_t >> for details.
761=item $string = $term->special_decode $text 1586=item $string = $term->special_decode $text
762 1587
763Converts rxvt-unicodes text reprsentation into a perl string. See 1588Converts rxvt-unicodes text reprsentation into a perl string. See
764C<< $term->ROW_t >> for details. 1589C<< $term->ROW_t >> for details.
765 1590
1591=item $success = $term->grab_button ($button, $modifiermask)
1592
1593Registers a synchronous button grab. See the XGrabButton manpage.
1594
1595=item $success = $term->grab ($eventtime[, $sync])
1596
1597Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1598synchronous (C<$sync> is true). Also remembers the grab timestampe.
1599
1600=item $term->allow_events_async
1601
1602Calls XAllowEvents with AsyncBoth for the most recent grab.
1603
1604=item $term->allow_events_sync
1605
1606Calls XAllowEvents with SyncBoth for the most recent grab.
1607
1608=item $term->allow_events_replay
1609
1610Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1611recent grab.
1612
1613=item $term->ungrab
1614
1615Calls XUngrab for the most recent grab. Is called automatically on
1616evaluation errors, as it is better to lose the grab in the error case as
1617the session.
1618
1619=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1620
1621=item $atom_name = $term->XGetAtomName ($atom)
1622
1623=item @atoms = $term->XListProperties ($window)
1624
1625=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1626
1627=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1628
1629=item $term->XDeleteProperty ($window, $property)
1630
1631=item $window = $term->DefaultRootWindow
1632
1633=item $term->XReparentWindow ($window, $parent, [$x, $y])
1634
1635=item $term->XMapWindow ($window)
1636
1637=item $term->XUnmapWindow ($window)
1638
1639=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1640
1641=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1642
1643=item $term->XChangeInput ($window, $add_events[, $del_events])
1644
1645Various X or X-related functions. The C<$term> object only serves as
1646the source of the display, otherwise those functions map more-or-less
1647directory onto the X functions of the same name.
1648
766=back 1649=back
1650
1651=cut
1652
1653package urxvt::popup;
1654
1655=head2 The C<urxvt::popup> Class
1656
1657=over 4
1658
1659=cut
1660
1661sub add_item {
1662 my ($self, $item) = @_;
1663
1664 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1665 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1666 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1667
1668 $item->{render} ||= sub { $_[0]{text} };
1669
1670 push @{ $self->{item} }, $item;
1671}
1672
1673=item $popup->add_title ($title)
1674
1675Adds a non-clickable title to the popup.
1676
1677=cut
1678
1679sub add_title {
1680 my ($self, $title) = @_;
1681
1682 $self->add_item ({
1683 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1684 text => $title,
1685 activate => sub { },
1686 });
1687}
1688
1689=item $popup->add_separator ([$sepchr])
1690
1691Creates a separator, optionally using the character given as C<$sepchr>.
1692
1693=cut
1694
1695sub add_separator {
1696 my ($self, $sep) = @_;
1697
1698 $sep ||= "=";
1699
1700 $self->add_item ({
1701 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1702 text => "",
1703 render => sub { $sep x $self->{term}->ncol },
1704 activate => sub { },
1705 });
1706}
1707
1708=item $popup->add_button ($text, $cb)
1709
1710Adds a clickable button to the popup. C<$cb> is called whenever it is
1711selected.
1712
1713=cut
1714
1715sub add_button {
1716 my ($self, $text, $cb) = @_;
1717
1718 $self->add_item ({ type => "button", text => $text, activate => $cb});
1719}
1720
1721=item $popup->add_toggle ($text, $cb, $initial_value)
1722
1723Adds a toggle/checkbox item to the popup. Teh callback gets called
1724whenever it gets toggled, with a boolean indicating its value as its first
1725argument.
1726
1727=cut
1728
1729sub add_toggle {
1730 my ($self, $text, $cb, $value) = @_;
1731
1732 my $item; $item = {
1733 type => "button",
1734 text => " $text",
1735 value => $value,
1736 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1737 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1738 };
1739
1740 $self->add_item ($item);
1741}
1742
1743=item $popup->show
1744
1745Displays the popup (which is initially hidden).
1746
1747=cut
1748
1749sub show {
1750 my ($self) = @_;
1751
1752 local $urxvt::popup::self = $self;
1753
1754 my $env = $self->{term}->env;
1755 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1756 delete $env->{LC_ALL};
1757 $env->{LC_CTYPE} = $self->{term}->locale;
1758
1759 urxvt::term->new ($env, "popup",
1760 "--perl-lib" => "", "--perl-ext-common" => "",
1761 "-pty-fd" => -1, "-sl" => 0,
1762 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
1763 "--transient-for" => $self->{term}->parent,
1764 "-display" => $self->{term}->display_id,
1765 "-pe" => "urxvt-popup")
1766 or die "unable to create popup window\n";
1767}
1768
1769sub DESTROY {
1770 my ($self) = @_;
1771
1772 delete $self->{term}{_destroy}{$self};
1773 $self->{term}->ungrab;
1774}
1775
1776=back
1777
1778=cut
1779
1780package urxvt::watcher;
1781
1782@urxvt::timer::ISA = __PACKAGE__;
1783@urxvt::iow::ISA = __PACKAGE__;
1784@urxvt::pw::ISA = __PACKAGE__;
1785@urxvt::iw::ISA = __PACKAGE__;
767 1786
768=head2 The C<urxvt::timer> Class 1787=head2 The C<urxvt::timer> Class
769 1788
770This class implements timer watchers/events. Time is represented as a 1789This class implements timer watchers/events. Time is represented as a
771fractional number of seconds since the epoch. Example: 1790fractional number of seconds since the epoch. Example:
810 1829
811=item $timer = $timer->start ($tstamp) 1830=item $timer = $timer->start ($tstamp)
812 1831
813Set the event trigger time to C<$tstamp> and start the timer. 1832Set the event trigger time to C<$tstamp> and start the timer.
814 1833
1834=item $timer = $timer->after ($delay)
1835
1836Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
1837
815=item $timer = $timer->stop 1838=item $timer = $timer->stop
816 1839
817Stop the timer. 1840Stop the timer.
818 1841
819=back 1842=back
824 1847
825 $term->{socket} = ... 1848 $term->{socket} = ...
826 $term->{iow} = urxvt::iow 1849 $term->{iow} = urxvt::iow
827 ->new 1850 ->new
828 ->fd (fileno $term->{socket}) 1851 ->fd (fileno $term->{socket})
829 ->events (1) # wait for read data 1852 ->events (urxvt::EVENT_READ)
830 ->start 1853 ->start
831 ->cb (sub { 1854 ->cb (sub {
832 my ($iow, $revents) = @_; 1855 my ($iow, $revents) = @_;
833 # $revents must be 1 here, no need to check 1856 # $revents must be 1 here, no need to check
834 sysread $term->{socket}, my $buf, 8192 1857 sysread $term->{socket}, my $buf, 8192
851 1874
852Set the filedescriptor (not handle) to watch. 1875Set the filedescriptor (not handle) to watch.
853 1876
854=item $iow = $iow->events ($eventmask) 1877=item $iow = $iow->events ($eventmask)
855 1878
856Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1879Set the event mask to watch. The only allowed values are
857data, Bit #1 (value C<2>) enables watching for write data. 1880C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1881together, or C<urxvt::EVENT_NONE>.
858 1882
859=item $iow = $iow->start 1883=item $iow = $iow->start
860 1884
861Start watching for requested events on the given handle. 1885Start watching for requested events on the given handle.
862 1886
863=item $iow = $iow->stop 1887=item $iow = $iow->stop
864 1888
865Stop watching for events on the given filehandle. 1889Stop watching for events on the given filehandle.
1890
1891=back
1892
1893=head2 The C<urxvt::iw> Class
1894
1895This class implements idle watchers, that get called automatically when
1896the process is idle. They should return as fast as possible, after doing
1897some useful work.
1898
1899=over 4
1900
1901=item $iw = new urxvt::iw
1902
1903Create a new idle watcher object in stopped state.
1904
1905=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1906
1907Set the callback to be called when the watcher triggers.
1908
1909=item $timer = $timer->start
1910
1911Start the watcher.
1912
1913=item $timer = $timer->stop
1914
1915Stop the watcher.
1916
1917=back
1918
1919=head2 The C<urxvt::pw> Class
1920
1921This class implements process watchers. They create an event whenever a
1922process exits, after which they stop automatically.
1923
1924 my $pid = fork;
1925 ...
1926 $term->{pw} = urxvt::pw
1927 ->new
1928 ->start ($pid)
1929 ->cb (sub {
1930 my ($pw, $exit_status) = @_;
1931 ...
1932 });
1933
1934=over 4
1935
1936=item $pw = new urxvt::pw
1937
1938Create a new process watcher in stopped state.
1939
1940=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1941
1942Set the callback to be called when the timer triggers.
1943
1944=item $pw = $timer->start ($pid)
1945
1946Tells the wqtcher to start watching for process C<$pid>.
1947
1948=item $pw = $pw->stop
1949
1950Stop the watcher.
866 1951
867=back 1952=back
868 1953
869=head1 ENVIRONMENT 1954=head1 ENVIRONMENT
870 1955
873This variable controls the verbosity level of the perl extension. Higher 1958This variable controls the verbosity level of the perl extension. Higher
874numbers indicate more verbose output. 1959numbers indicate more verbose output.
875 1960
876=over 4 1961=over 4
877 1962
878=item =0 - only fatal messages 1963=item == 0 - fatal messages
879 1964
880=item =3 - script loading and management 1965=item >= 3 - script loading and management
881 1966
882=item =10 - all events received 1967=item >=10 - all called hooks
1968
1969=item >=11 - hook reutrn values
883 1970
884=back 1971=back
885 1972
886=head1 AUTHOR 1973=head1 AUTHOR
887 1974

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines