5 @@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
9 # create a file grab_test in $HOME:
12 warn "you selected ", $_[0]->selection;
16 # start a @@RXVT_NAME@@ using it:
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
22 Every time a terminal object gets created, extension scripts specified via
23 the C<perl> resource are loaded and associated with it.
25 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26 thus must be encoded as UTF-8.
28 Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29 scripts will be shared (but not enabled) for all terminals.
31 You can disable the embedded perl interpreter by setting both "perl-ext"
32 and "perl-ext-common" resources to the empty string.
34 =head1 PREPACKAGED EXTENSIONS
36 This section describes the extensions delivered with this release. You can
37 find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
39 You can activate them like this:
41 @@RXVT_NAME@@ -pe <extensionname>
43 Or by adding them to the resource for extensions loaded by default:
45 URxvt.perl-ext-common: default,selection-autotransform
49 =item selection (enabled by default)
51 (More) intelligent selection. This extension tries to be more intelligent
52 when the user extends selections (double-click and further clicks). Right
53 now, it tries to select words, urls and complete shell-quoted
54 arguments, which is very convenient, too, if your F<ls> supports
55 C<--quoting-style=shell>.
57 A double-click usually selects the word under the cursor, further clicks
58 will enlarge the selection.
60 The selection works by trying to match a number of regexes and displaying
61 them in increasing order of length. You can add your own regexes by
62 specifying resources of the form:
64 URxvt.selection.pattern-0: perl-regex
65 URxvt.selection.pattern-1: perl-regex
68 The index number (0, 1...) must not have any holes, and each regex must
69 contain at least one pair of capturing parentheses, which will be used for
70 the match. For example, the following adds a regex that matches everything
71 between two vertical bars:
73 URxvt.selection.pattern-0: \\|([^|]+)\\|
75 Another example: Programs I use often output "absolute path: " at the
76 beginning of a line when they process multiple files. The following
77 pattern matches the filename (note, there is a single space at the very
80 URxvt.selection.pattern-0: ^(/[^:]+):\
82 You can look at the source of the selection extension to see more
83 interesting uses, such as parsing a line from beginning to end.
85 This extension also offers following bindable keyboard commands:
91 Rot-13 the selection when activated. Used via keyboard trigger:
93 URxvt.keysym.C-M-r: perl:selection:rot13
97 =item option-popup (enabled by default)
99 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
102 Other extensions can extend this popup menu by pushing a code reference
103 onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the
104 popup is being displayed.
106 Its sole argument is the popup menu, which can be modified. It should
107 either return nothing or a string, the initial boolean value and a code
108 reference. The string will be used as button text and the code reference
109 will be called when the toggle changes, with the new boolean value as
112 The following will add an entry C<myoption> that changes
113 C<< $self->{myoption} >>:
115 push @{ $self->{term}{option_popup_hook} }, sub {
116 ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
119 =item selection-popup (enabled by default)
121 Binds a popup menu to Ctrl-Button3 that lets you convert the selection
122 text into various other formats/action (such as uri unescaping, perl
123 evaluation, web-browser starting etc.), depending on content.
125 Other extensions can extend this popup menu by pushing a code reference
126 onto C<@{ $term->{selection_popup_hook} }>, which gets called whenever the
127 popup is being displayed.
129 Its sole argument is the popup menu, which can be modified. The selection
130 is in C<$_>, which can be used to decide whether to add something or not.
131 It should either return nothing or a string and a code reference. The
132 string will be used as button text and the code reference will be called
133 when the button gets activated and should transform C<$_>.
135 The following will add an entry C<a to b> that transforms all C<a>s in
136 the selection to C<b>s, but only if the selection currently contains any
139 push @{ $self->{term}{selection_popup_hook} }, sub {
140 /a/ ? ("a to b" => sub { s/a/b/g }
144 =item searchable-scrollback<hotkey> (enabled by default)
146 Adds regex search functionality to the scrollback buffer, triggered
147 by a hotkey (default: C<M-s>). While in search mode, normal terminal
148 input/output is suspended and a regex is displayed at the bottom of the
151 Inputting characters appends them to the regex and continues incremental
152 search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
153 search upwards/downwards in the scrollback buffer, C<End> jumps to the
154 bottom. C<Escape> leaves search mode and returns to the point where search
155 was started, while C<Enter> or C<Return> stay at the current position and
156 additionally stores the first match in the current line into the primary
157 selection if the C<Shift> modifier is active.
159 The regex defaults to "(?i)", resulting in a case-insensitive search. To
160 get a case-sensitive search you can delete this prefix using C<BackSpace>
161 or simply use an uppercase character which removes the "(?i)" prefix.
163 See L<perlre> for more info about perl regular expression syntax.
165 =item readline (enabled by default)
167 A support package that tries to make editing with readline easier. At
168 the moment, it reacts to clicking shift-left mouse button by trying to
169 move the text cursor to this position. It does so by generating as many
170 cursor-left or cursor-right keypresses as required (this only works
171 for programs that correctly support wide characters).
173 To avoid too many false positives, this is only done when:
177 =item - the tty is in ICANON state.
179 =item - the text cursor is visible.
181 =item - the primary screen is currently being displayed.
183 =item - the mouse is on the same (multi-row-) line as the text cursor.
187 The normal selection mechanism isn't disabled, so quick successive clicks
188 might interfere with selection creation in harmless ways.
190 =item selection-autotransform
192 This selection allows you to do automatic transforms on a selection
193 whenever a selection is made.
195 It works by specifying perl snippets (most useful is a single C<s///>
196 operator) that modify C<$_> as resources:
198 URxvt.selection-autotransform.0: transform
199 URxvt.selection-autotransform.1: transform
202 For example, the following will transform selections of the form
203 C<filename:number>, often seen in compiler messages, into C<vi +$filename
206 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
208 And this example matches the same,but replaces it with vi-commands you can
209 paste directly into your (vi :) editor:
211 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
213 Of course, this can be modified to suit your needs and your editor :)
215 To expand the example above to typical perl error messages ("XXX at
216 FILENAME line YYY."), you need a slightly more elaborate solution:
218 URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
219 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
221 The first line tells the selection code to treat the unchanging part of
222 every error message as a selection pattern, and the second line transforms
223 the message into vi commands to load the file.
227 This transforms the terminal into a tabbar with additional terminals, that
228 is, it implements what is commonly referred to as "tabbed terminal". The topmost line
229 displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
232 Clicking a button will activate that tab. Pressing B<Shift-Left> and
233 B<Shift-Right> will switch to the tab left or right of the current one,
234 while B<Shift-Down> creates a new tab.
236 The tabbar itself can be configured similarly to a normal terminal, but
237 with a resource class of C<URxvt.tabbed>. In addition, it supports the
238 following four resources (shown with defaults):
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>
245 See I<COLOR AND GRAPHICS> in the @@RXVT_NAME@@(1) manpage for valid
250 Uses per-line display filtering (C<on_line_update>) to underline text
251 matching a certain pattern and make it clickable. When clicked with the
252 mouse button specified in the C<matcher.button> resource (default 2, or
253 middle), the program specified in the C<matcher.launcher> resource
254 (default, the C<urlLauncher> resource, C<sensible-browser>) will be started
255 with the matched text as first argument. The default configuration is
256 suitable for matching URLs and launching a web browser, like the
257 former "mark-urls" extension.
259 The default pattern to match URLs can be overridden with the
260 C<matcher.pattern.0> resource, and additional patterns can be specified
261 with numbered patterns, in a manner similar to the "selection" extension.
262 The launcher can also be overridden on a per-pattern basis.
264 It is possible to activate the most recently seen match from the keyboard.
265 Simply bind a keysym to "perl:matcher" as seen in the example below.
267 Example configuration:
269 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher
272 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1
279 This (experimental) perl extension implements OnTheSpot editing. It does
280 not work perfectly, and some input methods don't seem to work well with
281 OnTheSpot editing in general, but it seems to work at least for SCIM and
284 You enable it by specifying this extension and a preedit style of
287 @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
291 A very primitive quake-console-like extension. It was inspired by a
292 description of how the programs C<kuake> and C<yakuake> work: Whenever the
293 user presses a global accelerator key (by default C<F10>), the terminal
294 will show or hide itself. Another press of the accelerator key will hide
297 Initially, the window will not be shown when using this extension.
299 This is useful if you need a single terminal that is not using any desktop
300 space most of the time but is quickly available at the press of a key.
302 The accelerator key is grabbed regardless of any modifiers, so this
303 extension will actually grab a physical key just for this function.
305 If you want a quake-like animation, tell your window manager to do so
310 This extension implements some OSC commands to display timed popups on the
311 screen - useful for status displays from within scripts. You have to read
312 the sources for more info.
314 =item block-graphics-to-ascii
316 A not very useful example of filtering all text output to the terminal
317 by replacing all line-drawing characters (U+2500 .. U+259F) by a
318 similar-looking ascii character.
322 Displays a digital clock using the built-in overlay.
324 =item remote-clipboard
326 Somewhat of a misnomer, this extension adds two menu entries to the
327 selection popup that allows one to run external commands to store the
328 selection somewhere and fetch it again.
330 We use it to implement a "distributed selection mechanism", which just
331 means that one command uploads the file to a remote server, and another
334 The commands can be set using the C<URxvt.remote-selection.store> and
335 C<URxvt.remote-selection.fetch> resources. The first should read the
336 selection to store from STDIN (always in UTF-8), the second should provide
337 the selection data on STDOUT (also in UTF-8).
339 The defaults (which are likely useless to you) use rsh and cat:
341 URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
342 URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
344 =item selection-pastebin
346 This is a little rarely useful extension that Uploads the selection as
347 textfile to a remote site (or does other things). (The implementation is
348 not currently secure for use in a multiuser environment as it writes to
351 It listens to the C<selection-pastebin:remote-pastebin> keyboard command,
354 URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
356 Pressing this combination runs a command with C<%> replaced by the name of
357 the textfile. This command can be set via a resource:
359 URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
361 And the default is likely not useful to anybody but the few people around
364 The name of the textfile is the hex encoded md5 sum of the selection, so
365 the same content should lead to the same filename.
367 After a successful upload the selection will be replaced by the text given
368 in the C<selection-pastebin-url> resource (again, the % is the placeholder
371 URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
373 I<Note to xrdb users:> xrdb uses the C preprocessor, which might interpret
374 the double C</> characters as comment start. Use C<\057\057> instead,
375 which works regardless of wether xrdb is used to parse the resource file
378 =item macosx-pastebin and macosx-pastebin-native
380 These two modules implement an extended clipboard for Mac OS X. They are
383 URxvt.perl-ext-common: default,macosx-clipboard
384 URxvt.keysym.M-c: perl:macosx-clipboard:copy
385 URxvt.keysym.M-v: perl:macosx-clipboard:paste
387 The difference between them is that the native variant requires a
388 perl from apple's devkit or so, and C<maxosx-pastebin> requires the
389 C<Mac::Pasteboard> module, works with other perls, has fewer bugs, is
392 =item example-refresh-hooks
394 Displays a very simple digital clock in the upper right corner of the
395 window. Illustrates overwriting the refresh callbacks to create your own
400 =head1 API DOCUMENTATION
402 =head2 General API Considerations
404 All objects (such as terminals, time watchers etc.) are typical
405 reference-to-hash objects. The hash can be used to store anything you
406 like. All members starting with an underscore (such as C<_ptr> or
407 C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
410 When objects are destroyed on the C++ side, the perl object hashes are
411 emptied, so its best to store related objects such as time watchers and
412 the like inside the terminal object so they get destroyed as soon as the
413 terminal is destroyed.
415 Argument names also often indicate the type of a parameter. Here are some
416 hints on what they mean:
422 Rxvt-unicodes special way of encoding text, where one "unicode" character
423 always represents one screen cell. See L<ROW_t> for a discussion of this format.
427 A perl text string, with an emphasis on I<text>. It can store all unicode
428 characters and is to be distinguished with text encoded in a specific
429 encoding (often locale-specific) and binary data.
433 Either binary data or - more common - a text string encoded in a
438 =head2 Extension Objects
440 Every perl extension is a perl class. A separate perl object is created
441 for each terminal, and each terminal has its own set of extenion objects,
442 which are passed as the first parameter to hooks. So extensions can use
443 their C<$self> object without having to think about clashes with other
444 extensions or other terminals, with the exception of methods and members
445 that begin with an underscore character C<_>: these are reserved for
448 Although it isn't a C<urxvt::term> object, you can call all methods of the
449 C<urxvt::term> class on this object.
451 It has the following methods and data members:
455 =item $urxvt_term = $self->{term}
457 Returns the C<urxvt::term> object associated with this instance of the
458 extension. This member I<must not> be changed in any way.
460 =item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
462 Dynamically enable the given hooks (named without the C<on_> prefix) for
463 this extension, replacing any previous hook. This is useful when you want
464 to overwrite time-critical hooks only temporarily.
466 =item $self->disable ($hook_name[, $hook_name..])
468 Dynamically disable the given hooks.
474 The following subroutines can be declared in extension files, and will be
475 called whenever the relevant event happens.
477 The first argument passed to them is an extension object as described in
478 the in the C<Extension Objects> section.
480 B<All> of these hooks must return a boolean value. If any of the called
481 hooks returns true, then the event counts as being I<consumed>, and the
482 relevant action might not be carried out by the C++ code.
484 I<< When in doubt, return a false value (preferably C<()>). >>
490 Called after a new terminal object has been initialized, but before
491 windows are created or the command gets run. Most methods are unsafe to
492 call or deliver senseless data, as terminal size and other characteristics
493 have not yet been determined. You can safely query and change resources
494 and options, though. For many purposes the C<on_start> hook is a better
499 Called at the very end of initialisation of a new terminal, just before
500 trying to map (display) the toplevel and returning to the main loop.
502 =item on_destroy $term
504 Called whenever something tries to destroy terminal, when the terminal is
505 still fully functional (not for long, though).
509 Called after the screen is "reset" for any reason, such as resizing or
510 control sequences. Here is where you can react on changes to size-related
513 =item on_child_start $term, $pid
515 Called just after the child process has been C<fork>ed.
517 =item on_child_exit $term, $status
519 Called just after the child process has exited. C<$status> is the status
522 =item on_sel_make $term, $eventtime
524 Called whenever a selection has been made by the user, but before the
525 selection text is copied, so changes to the beginning, end or type of the
526 selection will be honored.
528 Returning a true value aborts selection making by urxvt, in which case you
529 have to make a selection yourself by calling C<< $term->selection_grab >>.
531 =item on_sel_grab $term, $eventtime
533 Called whenever a selection has been copied, but before the selection is
534 requested from the server. The selection text can be queried and changed
535 by calling C<< $term->selection >>.
537 Returning a true value aborts selection grabbing. It will still be highlighted.
539 =item on_sel_extend $term
541 Called whenever the user tries to extend the selection (e.g. with a double
542 click) and is either supposed to return false (normal operation), or
543 should extend the selection itself and return true to suppress the built-in
544 processing. This can happen multiple times, as long as the callback
545 returns true, it will be called on every further click by the user and is
546 supposed to enlarge the selection more and more, if possible.
548 See the F<selection> example extension.
550 =item on_view_change $term, $offset
552 Called whenever the view offset changes, i.e. the user or program
553 scrolls. Offset C<0> means display the normal terminal, positive values
554 show this many lines of scrollback.
556 =item on_scroll_back $term, $lines, $saved
558 Called whenever lines scroll out of the terminal area into the scrollback
559 buffer. C<$lines> is the number of lines scrolled out and may be larger
560 than the scroll back buffer or the terminal.
562 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
563 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
564 number of lines that will be in the scrollback buffer.
566 =item on_osc_seq $term, $op, $args, $resp
568 Called on every OSC sequence and can be used to suppress it or modify its
569 behaviour. The default should be to return an empty list. A true value
570 suppresses execution of the request completely. Make sure you don't get
571 confused by recursive invocations when you output an OSC sequence within
574 C<on_osc_seq_perl> should be used for new behaviour.
576 =item on_osc_seq_perl $term, $args, $resp
578 Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
579 operating system command) is processed. Cursor position and other state
580 information is up-to-date when this happens. For interoperability, the
581 string should start with the extension name (sans -osc) and a semicolon,
582 to distinguish it from commands for other extensions, and this might be
583 enforced in the future.
585 For example, C<overlay-osc> uses this:
587 sub on_osc_seq_perl {
588 my ($self, $osc, $resp) = @_;
590 return unless $osc =~ s/^overlay;//;
592 ... process remaining $osc string
595 Be careful not ever to trust (in a security sense) the data you receive,
596 as its source can not easily be controlled (e-mail content, messages from
597 other users on the same system etc.).
599 For responses, C<$resp> contains the end-of-args separator used by the
602 =item on_add_lines $term, $string
604 Called whenever text is about to be output, with the text as argument. You
605 can filter/change and output the text yourself by returning a true value
606 and calling C<< $term->scr_add_lines >> yourself. Please note that this
607 might be very slow, however, as your hook is called for B<all> text being
610 =item on_tt_write $term, $octets
612 Called whenever some data is written to the tty/pty and can be used to
613 suppress or filter tty input.
615 =item on_line_update $term, $row
617 Called whenever a line was updated or changed. Can be used to filter
618 screen output (e.g. underline urls or other useless stuff). Only lines
619 that are being shown will be filtered, and, due to performance reasons,
620 not always immediately.
622 The row number is always the topmost row of the line if the line spans
625 Please note that, if you change the line, then the hook might get called
626 later with the already-modified line (e.g. if unrelated parts change), so
627 you cannot just toggle rendition bits, but only set them.
629 =item on_refresh_begin $term
631 Called just before the screen gets redrawn. Can be used for overlay or
632 similar effects by modifying the terminal contents in refresh_begin, and
633 restoring them in refresh_end. The built-in overlay and selection display
634 code is run after this hook, and takes precedence.
636 =item on_refresh_end $term
638 Called just after the screen gets redrawn. See C<on_refresh_begin>.
640 =item on_user_command $term, $string
642 Called whenever a user-configured event is being activated (e.g. via
643 a C<perl:string> action bound to a key, see description of the B<keysym>
644 resource in the @@RXVT_NAME@@(1) manpage).
646 The event is simply the action string. This interface is assumed to change
647 slightly in the future.
649 =item on_resize_all_windows $tern, $new_width, $new_height
651 Called just after the new window size has been calculated, but before
652 windows are actually being resized or hints are being set. If this hook
653 returns TRUE, setting of the window hints is being skipped.
655 =item on_x_event $term, $event
657 Called on every X event received on the vt window (and possibly other
658 windows). Should only be used as a last resort. Most event structure
659 members are not passed.
661 =item on_root_event $term, $event
663 Like C<on_x_event>, but is called for events on the root window.
665 =item on_focus_in $term
667 Called whenever the window gets the keyboard focus, before rxvt-unicode
668 does focus in processing.
670 =item on_focus_out $term
672 Called whenever the window loses keyboard focus, before rxvt-unicode does
673 focus out processing.
675 =item on_configure_notify $term, $event
677 =item on_property_notify $term, $event
679 =item on_key_press $term, $event, $keysym, $octets
681 =item on_key_release $term, $event, $keysym
683 =item on_button_press $term, $event
685 =item on_button_release $term, $event
687 =item on_motion_notify $term, $event
689 =item on_map_notify $term, $event
691 =item on_unmap_notify $term, $event
693 Called whenever the corresponding X event is received for the terminal If
694 the hook returns true, then the even will be ignored by rxvt-unicode.
696 The event is a hash with most values as named by Xlib (see the XEvent
697 manpage), with the additional members C<row> and C<col>, which are the
698 (real, not screen-based) row and column under the mouse cursor.
700 C<on_key_press> additionally receives the string rxvt-unicode would
701 output, if any, in locale-specific encoding.
705 =item on_client_message $term, $event
707 =item on_wm_protocols $term, $event
709 =item on_wm_delete_window $term, $event
711 Called when various types of ClientMessage events are received (all with
712 format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
731 our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
739 our $NOCHAR = chr 0xffff;
741 =head2 Variables in the C<urxvt> Package
747 The rxvt-unicode library directory, where, among other things, the perl
748 modules and scripts are stored.
750 =item $urxvt::RESCLASS, $urxvt::RESCLASS
752 The resource class and name rxvt-unicode uses to look up X resources.
754 =item $urxvt::RXVTNAME
756 The basename of the installed binaries, usually C<urxvt>.
760 The current terminal. This variable stores the current C<urxvt::term>
761 object, whenever a callback/hook is executing.
763 =item @urxvt::TERM_INIT
765 All code references in this array will be called as methods of the next newly
766 created C<urxvt::term> object (during the C<on_init> phase). The array
767 gets cleared before the code references that were in it are being executed,
768 so references can push themselves onto it again if they so desire.
770 This complements to the perl-eval command line option, but gets executed
773 =item @urxvt::TERM_EXT
775 Works similar to C<@TERM_INIT>, but contains perl package/class names, which
776 get registered as normal extensions after calling the hooks in C<@TERM_INIT>
777 but before other extensions. Gets cleared just like C<@TERM_INIT>.
781 =head2 Functions in the C<urxvt> Package
785 =item urxvt::fatal $errormessage
787 Fatally aborts execution with the given error message. Avoid at all
788 costs! The only time this is acceptable is when the terminal process
791 =item urxvt::warn $string
793 Calls C<rxvt_warn> with the given string which should not include a
794 newline. The module also overwrites the C<warn> builtin with a function
795 that calls this function.
797 Using this function has the advantage that its output ends up in the
798 correct place, e.g. on stderr of the connecting urxvtc client.
800 Messages have a size limit of 1023 bytes currently.
802 =item @terms = urxvt::termlist
804 Returns all urxvt::term objects that exist in this process, regardless of
805 whether they are started, being destroyed etc., so be careful. Only term
806 objects that have perl extensions attached will be returned (because there
807 is no urxvt::term objet associated with others).
809 =item $time = urxvt::NOW
811 Returns the "current time" (as per the event loop).
813 =item urxvt::CurrentTime
815 =item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
816 Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
817 Button4Mask, Button5Mask, AnyModifier
819 =item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
820 ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
821 PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
822 Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
823 KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
824 ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
825 FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
827 =item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
828 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
829 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
830 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
831 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
832 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
833 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
835 Various constants for use in X calls and event processing.
841 Rendition bitsets contain information about colour, font, font styles and
842 similar information for each screen cell.
844 The following "macros" deal with changes in rendition sets. You should
845 never just create a bitset, you should always modify an existing one,
846 as they contain important information required for correct operation of
851 =item $rend = urxvt::DEFAULT_RSTYLE
853 Returns the default rendition, as used when the terminal is starting up or
854 being reset. Useful as a base to start when creating renditions.
856 =item $rend = urxvt::OVERLAY_RSTYLE
858 Return the rendition mask used for overlays by default.
860 =item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
862 Return the bit that enabled bold, italic, blink, reverse-video and
863 underline, respectively. To enable such a style, just logically OR it into
866 =item $foreground = urxvt::GET_BASEFG $rend
868 =item $background = urxvt::GET_BASEBG $rend
870 Return the foreground/background colour index, respectively.
872 =item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
874 =item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
876 =item $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
878 Replace the foreground/background colour in the rendition mask with the
881 =item $value = urxvt::GET_CUSTOM $rend
883 Return the "custom" value: Every rendition has 5 bits for use by
884 extensions. They can be set and changed as you like and are initially
887 =item $rend = urxvt::SET_CUSTOM $rend, $new_value
889 Change the custom value.
896 # overwrite perl's warn
897 *CORE::GLOBAL::warn = sub {
898 my $msg = join "", @_;
900 unless $msg =~ /\n$/;
907 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
910 my ($level, $msg) = @_;
911 warn "$msg\n" if $level <= $verbosity;
916 # load a single script into its own package, once only
917 sub extension_package($) {
920 $extension_pkg{$path} ||= do {
921 $path =~ /([^\/\\]+)$/;
923 $pkg =~ s/[^[:word:]]/_/g;
924 $pkg = "urxvt::ext::$pkg";
926 verbose 3, "loading extension '$path' into package '$pkg'";
928 open my $fh, "<:raw", $path
932 "package $pkg; use strict; use utf8; no warnings 'utf8';\n"
933 . "#line 1 \"$path\"\n{\n"
934 . (do { local $/; <$fh> })
944 our $retval; # return value for urxvt
946 # called by the rxvt core
951 if ($htype == 0) { # INIT
952 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
957 my @init = @TERM_INIT;
959 $_->($TERM) for @init;
962 $TERM->register_package ($_) for @pkg;
965 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
966 if ($_ eq "default") {
967 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
968 } elsif (/^-(.*)$/) {
970 } elsif (/^([^<]+)<(.*)>$/) {
971 push @{ $ext_arg{$1} }, $2;
977 for my $ext (sort keys %ext_arg) {
978 my @files = grep -f $_, map "$_/$ext", @dirs;
981 $TERM->register_package (extension_package $files[0], $ext_arg{$ext});
983 warn "perl extension '$ext' not found in perl library search path\n";
987 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
993 if (my $cb = $TERM->{_hook}[$htype]) {
994 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
997 for my $pkg (keys %$cb) {
998 my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) };
999 $retval ||= $retval_;
1002 $TERM->ungrab; # better to lose the grab than the session
1007 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
1008 if $verbosity >= 11;
1011 if ($htype == 1) { # DESTROY
1012 # clear package objects
1013 %$_ = () for values %{ $TERM->{_pkg} };
1022 sub SET_COLOR($$$) {
1023 SET_BGCOLOR (SET_FGCOLOR ($_[0], $_[1]), $_[2])
1028 my ($str, $mask) = (@_, 0);
1029 my %color = ( fg => undef, bg => undef );
1031 for my $spec ( split /\s+/, $str ) {
1032 if ( $spec =~ /^([fb]g)[_:-]?(\d+)/i ) {
1033 $color{lc($1)} = $2;
1035 my $neg = $spec =~ s/^[-^]//;
1036 unless ( exists &{"RS_$spec"} ) {
1037 push @failed, $spec;
1040 my $cur = &{"RS_$spec"};
1048 ($mask, @color{qw(fg bg)}, \@failed)
1051 # urxvt::term::extension
1053 package urxvt::term::extension;
1056 my ($self, %hook) = @_;
1057 my $pkg = $self->{_pkg};
1059 while (my ($name, $cb) = each %hook) {
1060 my $htype = $HOOKTYPE{uc $name};
1062 or Carp::croak "unsupported hook type '$name'";
1064 $self->set_should_invoke ($htype, +1)
1065 unless exists $self->{term}{_hook}[$htype]{$pkg};
1067 $self->{term}{_hook}[$htype]{$pkg} = $cb;
1072 my ($self, @hook) = @_;
1073 my $pkg = $self->{_pkg};
1075 for my $name (@hook) {
1076 my $htype = $HOOKTYPE{uc $name};
1078 or Carp::croak "unsupported hook type '$name'";
1080 $self->set_should_invoke ($htype, -1)
1081 if delete $self->{term}{_hook}[$htype]{$pkg};
1088 $AUTOLOAD =~ /:([^:]+)$/
1089 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
1094 \$proxy->{term}->$1 (\@_)
1097 } or die "FATAL: unable to compile method forwarder: $@";
1106 # urxvt::destroy_hook
1108 sub urxvt::destroy_hook::DESTROY {
1112 sub urxvt::destroy_hook(&) {
1113 bless \shift, urxvt::destroy_hook::
1116 package urxvt::anyevent;
1118 =head2 The C<urxvt::anyevent> Class
1120 The sole purpose of this class is to deliver an interface to the
1121 C<AnyEvent> module - any module using it will work inside urxvt without
1122 further programming. The only exception is that you cannot wait on
1123 condition variables, but non-blocking condvar use is ok. What this means
1124 is that you cannot use blocking APIs, but the non-blocking variant should
1129 our $VERSION = '5.23';
1131 $INC{"urxvt/anyevent.pm"} = 1; # mark us as there
1132 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1135 my ($class, %arg) = @_;
1141 ->after ($arg{after}, $arg{interval})
1142 ->cb ($arg{interval} ? $cb : sub {
1143 $_[0]->stop; # need to cancel manually
1149 my ($class, %arg) = @_;
1152 my $fd = fileno $arg{fh};
1153 defined $fd or $fd = $arg{fh};
1155 bless [$arg{fh}, urxvt::iow
1158 ->events (($arg{poll} =~ /r/ ? 1 : 0)
1159 | ($arg{poll} =~ /w/ ? 2 : 0))
1162 ], urxvt::anyevent::
1166 my ($class, %arg) = @_;
1177 my ($class, %arg) = @_;
1185 $_[0]->stop; # need to cancel manually
1186 $cb->($_[0]->rpid, $_[0]->rstatus);
1195 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1198 package urxvt::term;
1200 =head2 The C<urxvt::term> Class
1206 # find on_xxx subs in the package and register them
1208 sub register_package {
1209 my ($self, $pkg, $argv) = @_;
1213 urxvt::verbose 6, "register package $pkg to $self";
1215 @{"$pkg\::ISA"} = urxvt::term::extension::;
1221 Scalar::Util::weaken ($proxy->{term} = $self);
1223 $self->{_pkg}{$pkg} = $proxy;
1225 for my $name (@HOOKNAME) {
1226 if (my $ref = $pkg->can ("on_" . lc $name)) {
1227 $proxy->enable ($name => $ref);
1232 =item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1234 Creates a new terminal, very similar as if you had started it with system
1235 C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1236 hash which defines the environment of the new terminal.
1238 Croaks (and probably outputs an error message) if the new instance
1239 couldn't be created. Returns C<undef> if the new instance didn't
1240 initialise perl, and the terminal object otherwise. The C<init> and
1241 C<start> hooks will be called before this call returns, and are free to
1242 refer to global data (which is race free).
1247 my ($class, $env, @args) = @_;
1249 $env or Carp::croak "environment hash missing in call to urxvt::term->new";
1250 @args or Carp::croak "name argument missing in call to urxvt::term->new";
1252 _new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1255 =item $term->destroy
1257 Destroy the terminal object (close the window, free resources
1258 etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
1259 watchers (timers, io watchers) are still active.
1261 =item $term->exec_async ($cmd[, @args])
1263 Works like the combination of the C<fork>/C<exec> builtins, which executes
1264 ("starts") programs in the background. This function takes care of setting
1265 the user environment before exec'ing the command (e.g. C<PATH>) and should
1266 be preferred over explicit calls to C<exec> or C<system>.
1268 Returns the pid of the subprocess or C<undef> on error.
1278 if !defined $pid or $pid;
1280 %ENV = %{ $self->env };
1286 =item $isset = $term->option ($optval[, $set])
1288 Returns true if the option specified by C<$optval> is enabled, and
1289 optionally change it. All option values are stored by name in the hash
1290 C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1292 Here is a likely non-exhaustive list of option names, please see the
1293 source file F</src/optinc.h> to see the actual list:
1295 borderLess console cursorBlink cursorUnderline hold iconic insecure
1296 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
1297 override-redirect pastableTabs pointerBlank reverseVideo scrollBar
1298 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
1299 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
1300 transparent tripleclickwords utmpInhibit visualBell
1302 =item $value = $term->resource ($name[, $newval])
1304 Returns the current resource value associated with a given name and
1305 optionally sets a new value. Setting values is most useful in the C<init>
1306 hook. Unset resources are returned and accepted as C<undef>.
1308 The new value must be properly encoded to a suitable character encoding
1309 before passing it to this method. Similarly, the returned value may need
1310 to be converted from the used encoding to text.
1312 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
1313 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
1316 Please note that resource strings will currently only be freed when the
1317 terminal is destroyed, so changing options frequently will eat memory.
1319 Here is a likely non-exhaustive list of resource names, not all of which
1320 are supported in every build, please see the source file F</src/rsinc.h>
1321 to see the actual list:
1323 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
1324 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key
1325 display_name embed ext_bwidth fade font geometry hold iconName
1326 imFont imLocale inputMethod insecure int_bwidth intensityStyles
1327 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8
1328 modifier mouseWheelScrollPage name override_redirect pastableTabs path
1329 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1330 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1331 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1332 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1333 secondaryScreen secondaryScroll shade term_name title
1334 transient_for transparent transparent_all tripleclickwords utmpInhibit
1339 sub resource($$;$) {
1340 my ($self, $name) = (shift, shift);
1341 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
1342 goto &urxvt::term::_resource
1345 =item $value = $term->x_resource ($pattern)
1347 Returns the X-Resource for the given pattern, excluding the program or
1348 class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
1349 same value as used by this instance of rxvt-unicode. Returns C<undef> if no
1350 resource with that pattern exists.
1352 This method should only be called during the C<on_start> hook, as there is
1353 only one resource database per display, and later invocations might return
1354 the wrong resources.
1356 =item $success = $term->parse_keysym ($keysym_spec, $command_string)
1358 Adds a keymap translation exactly as specified via a resource. See the
1359 C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1361 =item $rend = $term->rstyle ([$new_rstyle])
1363 Return and optionally change the current rendition. Text that is output by
1364 the terminal application will use this style.
1366 =item ($row, $col) = $term->screen_cur ([$row, $col])
1368 Return the current coordinates of the text cursor position and optionally
1369 set it (which is usually bad as applications don't expect that).
1371 =item ($row, $col) = $term->selection_mark ([$row, $col])
1373 =item ($row, $col) = $term->selection_beg ([$row, $col])
1375 =item ($row, $col) = $term->selection_end ([$row, $col])
1377 Return the current values of the selection mark, begin or end positions.
1379 When arguments are given, then the selection coordinates are set to
1380 C<$row> and C<$col>, and the selection screen is set to the current
1383 =item $screen = $term->selection_screen ([$screen])
1385 Returns the current selection screen, and then optionally sets it.
1387 =item $term->selection_make ($eventtime[, $rectangular])
1389 Tries to make a selection as set by C<selection_beg> and
1390 C<selection_end>. If C<$rectangular> is true (default: false), a
1391 rectangular selection will be made. This is the prefered function to make
1394 =item $success = $term->selection_grab ($eventtime)
1396 Try to request the primary selection text from the server (for example, as
1397 set by the next method). No visual feedback will be given. This function
1398 is mostly useful from within C<on_sel_grab> hooks.
1400 =item $oldtext = $term->selection ([$newtext])
1402 Return the current selection text and optionally replace it by C<$newtext>.
1404 =item $term->overlay_simple ($x, $y, $text)
1406 Create a simple multi-line overlay box. See the next method for details.
1410 sub overlay_simple {
1411 my ($self, $x, $y, $text) = @_;
1413 my @lines = split /\n/, $text;
1415 my $w = List::Util::max map $self->strwidth ($_), @lines;
1417 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
1418 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
1423 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
1425 Create a new (empty) overlay at the given position with the given
1426 width/height. C<$rstyle> defines the initial rendition style
1427 (default: C<OVERLAY_RSTYLE>).
1429 If C<$border> is C<2> (default), then a decorative border will be put
1432 If either C<$x> or C<$y> is negative, then this is counted from the
1433 right/bottom side, respectively.
1435 This method returns an urxvt::overlay object. The overlay will be visible
1436 as long as the perl object is referenced.
1438 The methods currently supported on C<urxvt::overlay> objects are:
1442 =item $overlay->set ($x, $y, $text[, $rend])
1444 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1445 text in rxvt-unicode's special encoding and an array of rendition values
1446 at a specific position inside the overlay.
1448 If C<$rend> is missing, then the rendition will not be changed.
1450 =item $overlay->hide
1452 If visible, hide the overlay, but do not destroy it.
1454 =item $overlay->show
1456 If hidden, display the overlay again.
1460 =item $popup = $term->popup ($event)
1462 Creates a new C<urxvt::popup> object that implements a popup menu. The
1463 C<$event> I<must> be the event causing the menu to pop up (a button event,
1469 my ($self, $event) = @_;
1471 $self->grab ($event->{time}, 1)
1479 Scalar::Util::weaken $popup->{term};
1481 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1482 Scalar::Util::weaken $self->{_destroy}{$popup};
1487 =item $cellwidth = $term->strwidth ($string)
1489 Returns the number of screen-cells this string would need. Correctly
1490 accounts for wide and combining characters.
1492 =item $octets = $term->locale_encode ($string)
1494 Convert the given text string into the corresponding locale encoding.
1496 =item $string = $term->locale_decode ($octets)
1498 Convert the given locale-encoded octets into a perl string.
1500 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1502 XORs the rendition values in the given span with the provided value
1503 (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1504 refresh hooks to provide effects similar to the selection.
1506 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1508 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1509 whitespace will additionally be xored with the C<$rstyle2>, which defaults
1510 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1511 it instead. Both styles I<MUST NOT> contain font styles.
1513 =item $term->scr_bell
1517 =item $term->scr_add_lines ($string)
1519 Write the given text string to the screen, as if output by the application
1520 running inside the terminal. It may not contain command sequences (escape
1521 codes), but is free to use line feeds, carriage returns and tabs. The
1522 string is a normal text string, not in locale-dependent encoding.
1524 Normally its not a good idea to use this function, as programs might be
1525 confused by changes in cursor position or scrolling. Its useful inside a
1526 C<on_add_lines> hook, though.
1528 =item $term->scr_change_screen ($screen)
1530 Switch to given screen - 0 primary, 1 secondary.
1532 =item $term->cmd_parse ($octets)
1534 Similar to C<scr_add_lines>, but the argument must be in the
1535 locale-specific encoding of the terminal and can contain command sequences
1536 (escape codes) that will be interpreted.
1538 =item $term->tt_write ($octets)
1540 Write the octets given in C<$data> to the tty (i.e. as program input). To
1541 pass characters instead of octets, you should convert your strings first
1542 to the locale-specific encoding using C<< $term->locale_encode >>.
1544 =item $old_events = $term->pty_ev_events ([$new_events])
1546 Replaces the event mask of the pty watcher by the given event mask. Can
1547 be used to suppress input and output handling to the pty/tty. See the
1548 description of C<< urxvt::timer->events >>. Make sure to always restore
1551 =item $fd = $term->pty_fd
1553 Returns the master file descriptor for the pty in use, or C<-1> if no pty
1556 =item $windowid = $term->parent
1558 Return the window id of the toplevel window.
1560 =item $windowid = $term->vt
1562 Return the window id of the terminal window.
1564 =item $term->vt_emask_add ($x_event_mask)
1566 Adds the specified events to the vt event mask. Useful e.g. when you want
1567 to receive pointer events all the times:
1569 $term->vt_emask_add (urxvt::PointerMotionMask);
1571 =item $term->focus_in
1573 =item $term->focus_out
1575 =item $term->key_press ($state, $keycode[, $time])
1577 =item $term->key_release ($state, $keycode[, $time])
1579 Deliver various fake events to to terminal.
1581 =item $window_width = $term->width
1583 =item $window_height = $term->height
1585 =item $font_width = $term->fwidth
1587 =item $font_height = $term->fheight
1589 =item $font_ascent = $term->fbase
1591 =item $terminal_rows = $term->nrow
1593 =item $terminal_columns = $term->ncol
1595 =item $has_focus = $term->focus
1597 =item $is_mapped = $term->mapped
1599 =item $max_scrollback = $term->saveLines
1601 =item $nrow_plus_saveLines = $term->total_rows
1603 =item $topmost_scrollback_row = $term->top_row
1605 Return various integers describing terminal characteristics.
1607 =item $x_display = $term->display_id
1609 Return the DISPLAY used by rxvt-unicode.
1611 =item $lc_ctype = $term->locale
1613 Returns the LC_CTYPE category string used by this rxvt-unicode.
1615 =item $env = $term->env
1617 Returns a copy of the environment in effect for the terminal as a hashref
1618 similar to C<\%ENV>.
1620 =item @envv = $term->envv
1622 Returns the environment as array of strings of the form C<VAR=VALUE>.
1624 =item @argv = $term->argv
1626 Return the argument vector as this terminal, similar to @ARGV, but
1627 includes the program name as first element.
1632 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), $_[0]->envv }
1635 =item $modifiermask = $term->ModLevel3Mask
1637 =item $modifiermask = $term->ModMetaMask
1639 =item $modifiermask = $term->ModNumLockMask
1641 Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1642 AltGr), the meta key (often Alt) and the num lock key, if applicable.
1644 =item $screen = $term->current_screen
1646 Returns the currently displayed screen (0 primary, 1 secondary).
1648 =item $cursor_is_hidden = $term->hidden_cursor
1650 Returns whether the cursor is currently hidden or not.
1652 =item $view_start = $term->view_start ([$newvalue])
1654 Returns the row number of the topmost displayed line. Maximum value is
1655 C<0>, which displays the normal terminal contents. Lower values scroll
1656 this many lines into the scrollback buffer.
1658 =item $term->want_refresh
1660 Requests a screen refresh. At the next opportunity, rxvt-unicode will
1661 compare the on-screen display with its stored representation. If they
1662 differ, it redraws the differences.
1664 Used after changing terminal contents to display them.
1666 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1668 Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >>
1669 is the topmost terminal line, row C<< $term->nrow-1 >> is the bottommost
1670 terminal line. Nothing will be returned if a nonexistent line
1673 If C<$new_text> is specified, it will replace characters in the current
1674 line, starting at column C<$start_col> (default C<0>), which is useful
1675 to replace only parts of a line. The font index in the rendition will
1676 automatically be updated.
1678 C<$text> is in a special encoding: tabs and wide characters that use more
1679 than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1680 characters. Characters with combining characters and other characters that
1681 do not fit into the normal text encoding will be replaced with characters
1682 in the private use area.
1684 You have to obey this encoding when changing text. The advantage is
1685 that C<substr> and similar functions work on screen cells and not on
1688 The methods C<< $term->special_encode >> and C<< $term->special_decode >>
1689 can be used to convert normal strings into this encoding and vice versa.
1691 =item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1693 Like C<< $term->ROW_t >>, but returns an arrayref with rendition
1694 bitsets. Rendition bitsets contain information about colour, font, font
1695 styles and similar information. See also C<< $term->ROW_t >>.
1697 When setting rendition, the font mask will be ignored.
1699 See the section on RENDITION, above.
1701 =item $length = $term->ROW_l ($row_number[, $new_length])
1703 Returns the number of screen cells that are in use ("the line
1704 length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
1705 line is joined with the following one.
1707 =item $bool = $term->is_longer ($row_number)
1709 Returns true if the row is part of a multiple-row logical "line" (i.e.
1710 joined with the following row), which means all characters are in use
1711 and it is continued on the next row (and possibly a continuation of the
1714 =item $line = $term->line ($row_number)
1716 Create and return a new C<urxvt::line> object that stores information
1717 about the logical line that row C<$row_number> is part of. It supports the
1722 =item $text = $line->t ([$new_text])
1724 Returns or replaces the full text of the line, similar to C<ROW_t>
1726 =item $rend = $line->r ([$new_rend])
1728 Returns or replaces the full rendition array of the line, similar to C<ROW_r>
1730 =item $length = $line->l
1732 Returns the length of the line in cells, similar to C<ROW_l>.
1734 =item $rownum = $line->beg
1736 =item $rownum = $line->end
1738 Return the row number of the first/last row of the line, respectively.
1740 =item $offset = $line->offset_of ($row, $col)
1742 Returns the character offset of the given row|col pair within the logical
1743 line. Works for rows outside the line, too, and returns corresponding
1744 offsets outside the string.
1746 =item ($row, $col) = $line->coord_of ($offset)
1748 Translates a string offset into terminal coordinates again.
1755 my ($self, $row) = @_;
1757 my $maxrow = $self->nrow - 1;
1759 my ($beg, $end) = ($row, $row);
1761 --$beg while $self->ROW_is_longer ($beg - 1);
1762 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1768 ncol => $self->ncol,
1769 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1773 sub urxvt::line::t {
1778 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1779 for $self->{beg} .. $self->{end};
1782 defined wantarray &&
1783 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1787 sub urxvt::line::r {
1792 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1793 for $self->{beg} .. $self->{end};
1796 if (defined wantarray) {
1798 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1800 $#$rend = $self->{len} - 1;
1807 sub urxvt::line::beg { $_[0]{beg} }
1808 sub urxvt::line::end { $_[0]{end} }
1809 sub urxvt::line::l { $_[0]{len} }
1811 sub urxvt::line::offset_of {
1812 my ($self, $row, $col) = @_;
1814 ($row - $self->{beg}) * $self->{ncol} + $col
1817 sub urxvt::line::coord_of {
1818 my ($self, $offset) = @_;
1823 $offset / $self->{ncol} + $self->{beg},
1824 $offset % $self->{ncol}
1828 =item $text = $term->special_encode $string
1830 Converts a perl string into the special encoding used by rxvt-unicode,
1831 where one character corresponds to one screen cell. See
1832 C<< $term->ROW_t >> for details.
1834 =item $string = $term->special_decode $text
1836 Converts rxvt-unicodes text representation into a perl string. See
1837 C<< $term->ROW_t >> for details.
1839 =item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1841 =item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1843 Register/unregister a synchronous button grab. See the XGrabButton
1846 =item $success = $term->grab ($eventtime[, $sync])
1848 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1849 synchronous (C<$sync> is true). Also remembers the grab timestamp.
1851 =item $term->allow_events_async
1853 Calls XAllowEvents with AsyncBoth for the most recent grab.
1855 =item $term->allow_events_sync
1857 Calls XAllowEvents with SyncBoth for the most recent grab.
1859 =item $term->allow_events_replay
1861 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1866 Calls XUngrab for the most recent grab. Is called automatically on
1867 evaluation errors, as it is better to lose the grab in the error case as
1870 =item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1872 =item $atom_name = $term->XGetAtomName ($atom)
1874 =item @atoms = $term->XListProperties ($window)
1876 =item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1878 =item $term->XChangeProperty ($window, $property, $type, $format, $octets)
1880 =item $term->XDeleteProperty ($window, $property)
1882 =item $window = $term->DefaultRootWindow
1884 =item $term->XReparentWindow ($window, $parent, [$x, $y])
1886 =item $term->XMapWindow ($window)
1888 =item $term->XUnmapWindow ($window)
1890 =item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1892 =item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1894 =item $term->XChangeInput ($window, $add_events[, $del_events])
1896 Various X or X-related functions. The C<$term> object only serves as
1897 the source of the display, otherwise those functions map more-or-less
1898 directory onto the X functions of the same name.
1904 package urxvt::popup;
1906 =head2 The C<urxvt::popup> Class
1913 my ($self, $item) = @_;
1915 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1916 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1917 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1919 $item->{render} ||= sub { $_[0]{text} };
1921 push @{ $self->{item} }, $item;
1924 =item $popup->add_title ($title)
1926 Adds a non-clickable title to the popup.
1931 my ($self, $title) = @_;
1934 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1936 activate => sub { },
1940 =item $popup->add_separator ([$sepchr])
1942 Creates a separator, optionally using the character given as C<$sepchr>.
1947 my ($self, $sep) = @_;
1952 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1954 render => sub { $sep x $self->{term}->ncol },
1955 activate => sub { },
1959 =item $popup->add_button ($text, $cb)
1961 Adds a clickable button to the popup. C<$cb> is called whenever it is
1967 my ($self, $text, $cb) = @_;
1969 $self->add_item ({ type => "button", text => $text, activate => $cb});
1972 =item $popup->add_toggle ($text, $initial_value, $cb)
1974 Adds a toggle/checkbox item to the popup. The callback gets called
1975 whenever it gets toggled, with a boolean indicating its new value as its
1981 my ($self, $text, $value, $cb) = @_;
1987 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1988 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1991 $self->add_item ($item);
1996 Displays the popup (which is initially hidden).
2003 local $urxvt::popup::self = $self;
2005 my $env = $self->{term}->env;
2006 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
2007 delete $env->{LC_ALL};
2008 $env->{LC_CTYPE} = $self->{term}->locale;
2010 my $term = urxvt::term->new (
2012 "--perl-lib" => "", "--perl-ext-common" => "",
2013 "-pty-fd" => -1, "-sl" => 0,
2014 "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect",
2015 "--transient-for" => $self->{term}->parent,
2016 "-display" => $self->{term}->display_id,
2017 "-pe" => "urxvt-popup",
2018 ) or die "unable to create popup window\n";
2020 unless (delete $term->{urxvt_popup_init_done}) {
2023 die "unable to initialise popup window\n";
2030 delete $self->{term}{_destroy}{$self};
2031 $self->{term}->ungrab;
2038 package urxvt::watcher;
2040 =head2 The C<urxvt::timer> Class
2042 This class implements timer watchers/events. Time is represented as a
2043 fractional number of seconds since the epoch. Example:
2045 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
2046 $term->{timer} = urxvt::timer
2050 $term->{overlay}->set (0, 0,
2051 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
2056 =item $timer = new urxvt::timer
2058 Create a new timer object in started state. It is scheduled to fire
2061 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
2063 Set the callback to be called when the timer triggers.
2065 =item $timer = $timer->set ($tstamp[, $interval])
2067 Set the time the event is generated to $tstamp (and optionally specifies a
2070 =item $timer = $timer->interval ($interval)
2072 By default (and when C<$interval> is C<0>), the timer will automatically
2073 stop after it has fired once. If C<$interval> is non-zero, then the timer
2074 is automatically rescheduled at the given intervals.
2076 =item $timer = $timer->start
2080 =item $timer = $timer->start ($tstamp[, $interval])
2082 Set the event trigger time to C<$tstamp> and start the timer. Optionally
2083 also replaces the interval.
2085 =item $timer = $timer->after ($delay[, $interval])
2087 Like C<start>, but sets the expiry timer to c<urxvt::NOW + $delay>.
2089 =item $timer = $timer->stop
2095 =head2 The C<urxvt::iow> Class
2097 This class implements io watchers/events. Example:
2099 $term->{socket} = ...
2100 $term->{iow} = urxvt::iow
2102 ->fd (fileno $term->{socket})
2103 ->events (urxvt::EV_READ)
2106 my ($iow, $revents) = @_;
2107 # $revents must be 1 here, no need to check
2108 sysread $term->{socket}, my $buf, 8192
2115 =item $iow = new urxvt::iow
2117 Create a new io watcher object in stopped state.
2119 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
2121 Set the callback to be called when io events are triggered. C<$reventmask>
2122 is a bitset as described in the C<events> method.
2124 =item $iow = $iow->fd ($fd)
2126 Set the file descriptor (not handle) to watch.
2128 =item $iow = $iow->events ($eventmask)
2130 Set the event mask to watch. The only allowed values are
2131 C<urxvt::EV_READ> and C<urxvt::EV_WRITE>, which might be ORed
2132 together, or C<urxvt::EV_NONE>.
2134 =item $iow = $iow->start
2136 Start watching for requested events on the given handle.
2138 =item $iow = $iow->stop
2140 Stop watching for events on the given file handle.
2144 =head2 The C<urxvt::iw> Class
2146 This class implements idle watchers, that get called automatically when
2147 the process is idle. They should return as fast as possible, after doing
2152 =item $iw = new urxvt::iw
2154 Create a new idle watcher object in stopped state.
2156 =item $iw = $iw->cb (sub { my ($iw) = @_; ... })
2158 Set the callback to be called when the watcher triggers.
2160 =item $timer = $timer->start
2164 =item $timer = $timer->stop
2170 =head2 The C<urxvt::pw> Class
2172 This class implements process watchers. They create an event whenever a
2173 process exits, after which they stop automatically.
2177 $term->{pw} = urxvt::pw
2181 my ($pw, $exit_status) = @_;
2187 =item $pw = new urxvt::pw
2189 Create a new process watcher in stopped state.
2191 =item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
2193 Set the callback to be called when the timer triggers.
2195 =item $pw = $timer->start ($pid)
2197 Tells the watcher to start watching for process C<$pid>.
2199 =item $pw = $pw->stop
2207 =head2 URXVT_PERL_VERBOSITY
2209 This variable controls the verbosity level of the perl extension. Higher
2210 numbers indicate more verbose output.
2214 =item == 0 - fatal messages
2216 =item >= 3 - script loading and management
2218 =item >=10 - all called hooks
2220 =item >=11 - hook return values
2226 Marc Lehmann <pcg@goof.com>
2227 http://software.schmorp.de/pkg/rxvt-unicode