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 Everytime 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 =head2 Prepackaged Extensions
33 This section describes the extensiosn delivered with this version. You can
34 find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
36 You can activate them like this:
38 @@RXVT_NAME@@ -pe <extensionname>
42 =item selection (enabled by default)
44 Intelligent selection. This extension tries to be more intelligent when
45 the user extends selections (double-click). Right now, it tries to select
46 urls and complete shell-quoted arguments, which is very convenient, too,
47 if your F<ls> supports C<--quoting-style=shell>.
49 It also offers the following bindable event:
55 Rot-13 the selection when activated. Used via keyboard trigger:
57 URxvt.keysym.C-M-r: perl:selection:rot13
61 =item option-popup (enabled by default)
63 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
66 =item selection-popup (enabled by default)
68 Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69 text into various other formats/action.
71 =item searchable-scrollback (enabled by default)
73 Adds regex search functionality to the scrollback buffer, triggered by a
74 hotkey (default: C<M-s>). When in search mode, terminal input/output is
75 suspended, C</> starts an incremental regex search, C<n> searches further,
76 C<p> jumps to the previous match. C<enter> leaves search mode at the
77 current position and C<escape> returns to the original position.
81 Displays a digital clock using the built-in overlay.
85 Uses per-line display filtering (C<on_line_update>) to underline urls.
87 =item block-graphics-to-ascii
89 A not very useful example of filtering all text output to the terminal,
90 by replacing all line-drawing characters (U+2500 .. U+259F) by a
91 similar-looking ascii character.
93 =item example-refresh-hooks
95 Displays a very simple digital clock in the upper right corner of the
96 window. Illustrates overwriting the refresh callbacks to create your own
101 =head2 General API Considerations
103 All objects (such as terminals, time watchers etc.) are typical
104 reference-to-hash objects. The hash can be used to store anything you
105 like. All members starting with an underscore (such as C<_ptr> or
106 C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
109 When objects are destroyed on the C++ side, the perl object hashes are
110 emptied, so its best to store related objects such as time watchers and
111 the like inside the terminal object so they get destroyed as soon as the
112 terminal is destroyed.
114 Argument names also often indicate the type of a parameter. Here are some
115 hints on what they mean:
121 Rxvt-unicodes special way of encoding text, where one "unicode" character
122 always represents one screen cell. See L<row_t> for a discussion of this format.
126 A perl text string, with an emphasis on I<text>. It can store all unicode
127 characters and is to be distinguished with text encoded in a specific
128 encoding (often locale-specific) and binary data.
132 Either binary data or - more common - a text string encoded in a
137 =head2 Extension Objects
139 Very perl extension is a perl class. A separate perl object is created
140 for each terminal and each extension and passed as the first parameter to
141 hooks. So extensions can use their C<$self> object without having to think
142 about other extensions, with the exception of methods and members that
143 begin with an underscore character C<_>: these are reserved for internal
146 Although it isn't a C<urxvt::term> object, you can call all methods of the
147 C<urxvt::term> class on this object.
149 It has the following methods and data members:
153 =item $urxvt_term = $self->{term}
155 Returns the C<urxvt::term> object associated with this instance of the
156 extension. This member I<must not> be changed in any way.
158 =item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
160 Dynamically enable the given hooks (named without the C<on_> prefix) for
161 this extension, replacing any previous hook. This is useful when you want
162 to overwrite time-critical hooks only temporarily.
164 =item $self->disable ($hook_name[, $hook_name..])
166 Dynamically disable the given hooks.
172 The following subroutines can be declared in extension files, and will be
173 called whenever the relevant event happens.
175 The first argument passed to them is an extension oject as described in
176 the in the C<Extension Objects> section.
178 B<All> of these hooks must return a boolean value. If it is true, then the
179 event counts as being I<consumed>, and the invocation of other hooks is
180 skipped, and the relevant action might not be carried out by the C++ code.
182 I<< When in doubt, return a false value (preferably C<()>). >>
188 Called after a new terminal object has been initialized, but before
189 windows are created or the command gets run. Most methods are unsafe to
190 call or deliver senseless data, as terminal size and other characteristics
191 have not yet been determined. You can safely query and change resources,
196 Called after the screen is "reset" for any reason, such as resizing or
197 control sequences. Here is where you can react on changes to size-related
202 Called at the very end of initialisation of a new terminal, just before
203 returning to the mainloop.
205 =item on_sel_make $term, $eventtime
207 Called whenever a selection has been made by the user, but before the
208 selection text is copied, so changes to the beginning, end or type of the
209 selection will be honored.
211 Returning a true value aborts selection making by urxvt, in which case you
212 have to make a selection yourself by calling C<< $term->selection_grab >>.
214 =item on_sel_grab $term, $eventtime
216 Called whenever a selection has been copied, but before the selection is
217 requested from the server. The selection text can be queried and changed
218 by calling C<< $term->selection >>.
220 Returning a true value aborts selection grabbing. It will still be hilighted.
222 =item on_sel_extend $term
224 Called whenever the user tries to extend the selection (e.g. with a double
225 click) and is either supposed to return false (normal operation), or
226 should extend the selection itelf and return true to suppress the built-in
229 See the F<selection> example extension.
231 =item on_view_change $term, $offset
233 Called whenever the view offset changes, i..e the user or program
234 scrolls. Offset C<0> means display the normal terminal, positive values
235 show this many lines of scrollback.
237 =item on_scroll_back $term, $lines, $saved
239 Called whenever lines scroll out of the terminal area into the scrollback
240 buffer. C<$lines> is the number of lines scrolled out and may be larger
241 than the scroll back buffer or the terminal.
243 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
244 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
245 number of lines that will be in the scrollback buffer.
247 =item on_osc_seq $term, $string
249 Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
250 operating system command) is processed. Cursor position and other state
251 information is up-to-date when this happens. For interoperability, the
252 string should start with the extension name and a colon, to distinguish
253 it from commands for other extensions, and this might be enforced in the
256 Be careful not ever to trust (in a security sense) the data you receive,
257 as its source can not easily be controleld (e-mail content, messages from
258 other users on the same system etc.).
260 =item on_add_lines $term, $string
262 Called whenever text is about to be output, with the text as argument. You
263 can filter/change and output the text yourself by returning a true value
264 and calling C<< $term->scr_add_lines >> yourself. Please note that this
265 might be very slow, however, as your hook is called for B<all> text being
268 =item on_tt_write $term, $octets
270 Called whenever some data is written to the tty/pty and can be used to
271 suppress or filter tty input.
273 =item on_line_update $term, $row
275 Called whenever a line was updated or changed. Can be used to filter
276 screen output (e.g. underline urls or other useless stuff). Only lines
277 that are being shown will be filtered, and, due to performance reasons,
278 not always immediately.
280 The row number is always the topmost row of the line if the line spans
283 Please note that, if you change the line, then the hook might get called
284 later with the already-modified line (e.g. if unrelated parts change), so
285 you cannot just toggle rendition bits, but only set them.
287 =item on_refresh_begin $term
289 Called just before the screen gets redrawn. Can be used for overlay
290 or similar effects by modify terminal contents in refresh_begin, and
291 restoring them in refresh_end. The built-in overlay and selection display
292 code is run after this hook, and takes precedence.
294 =item on_refresh_end $term
296 Called just after the screen gets redrawn. See C<on_refresh_begin>.
298 =item on_keyboard_command $term, $string
300 Called whenever the user presses a key combination that has a
301 C<perl:string> action bound to it (see description of the B<keysym>
302 resource in the @@RXVT_NAME@@(1) manpage).
304 =item on_focus_in $term
306 Called whenever the window gets the keyboard focus, before rxvt-unicode
307 does focus in processing.
309 =item on_focus_out $term
311 Called wheneever the window loses keyboard focus, before rxvt-unicode does
312 focus out processing.
314 =item on_key_press $term, $event, $keysym, $octets
316 =item on_key_release $term, $event, $keysym
318 =item on_button_press $term, $event
320 =item on_button_release $term, $event
322 =item on_motion_notify $term, $event
324 =item on_map_notify $term, $event
326 =item on_unmap_notify $term, $event
328 Called whenever the corresponding X event is received for the terminal If
329 the hook returns true, then the even will be ignored by rxvt-unicode.
331 The event is a hash with most values as named by Xlib (see the XEvent
332 manpage), with the additional members C<row> and C<col>, which are the row
333 and column under the mouse cursor.
335 C<on_key_press> additionally receives the string rxvt-unicode would
336 output, if any, in locale-specific encoding.
342 =head2 Variables in the C<urxvt> Package
348 The current terminal. This variable stores the current C<urxvt::term>
349 object, whenever a callback/hook is executing.
353 =head2 Functions in the C<urxvt> Package
357 =item $term = new urxvt [arg...]
359 Creates a new terminal, very similar as if you had started it with
360 C<system $binfile, arg...>. Croaks (and probably outputs an error message)
361 if the new instance couldn't be created. Returns C<undef> if the new
362 instance didn't initialise perl, and the terminal object otherwise. The
363 C<init> and C<start> hooks will be called during the call.
365 =item urxvt::fatal $errormessage
367 Fatally aborts execution with the given error message. Avoid at all
368 costs! The only time this is acceptable is when the terminal process
371 =item urxvt::warn $string
373 Calls C<rxvt_warn> with the given string which should not include a
374 newline. The module also overwrites the C<warn> builtin with a function
375 that calls this function.
377 Using this function has the advantage that its output ends up in the
378 correct place, e.g. on stderr of the connecting urxvtc client.
380 =item $is_safe = urxvt::safe
382 Returns true when it is safe to do potentially unsafe things, such as
383 evaluating perl code specified by the user. This is true when urxvt was
384 started setuid or setgid.
386 =item $time = urxvt::NOW
388 Returns the "current time" (as per the event loop).
390 =item urxvt::CurrentTime
392 =item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
393 Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
394 Button4Mask, Button5Mask, AnyModifier
396 Various constants for use in X calls and event processing.
402 Rendition bitsets contain information about colour, font, font styles and
403 similar information for each screen cell.
405 The following "macros" deal with changes in rendition sets. You should
406 never just create a bitset, you should always modify an existing one,
407 as they contain important information required for correct operation of
412 =item $rend = urxvt::DEFAULT_RSTYLE
414 Returns the default rendition, as used when the terminal is starting up or
415 being reset. Useful as a base to start when creating renditions.
417 =item $rend = urxvt::OVERLAY_RSTYLE
419 Return the rendition mask used for overlays by default.
421 =item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
423 Return the bit that enabled bold, italic, blink, reverse-video and
424 underline, respectively. To enable such a style, just logically OR it into
427 =item $foreground = urxvt::GET_BASEFG $rend
429 =item $background = urxvt::GET_BASEBG $rend
431 Return the foreground/background colour index, respectively.
433 =item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
435 =item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
437 Replace the foreground/background colour in the rendition mask with the
440 =item $value = urxvt::GET_CUSTOM ($rend)
442 Return the "custom" value: Every rendition has 5 bits for use by
443 extensions. They can be set and changed as you like and are initially
446 =item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
448 Change the custom value.
465 our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
476 # overwrite perl's warn
477 *CORE::GLOBAL::warn = sub {
478 my $msg = join "", @_;
480 unless $msg =~ /\n$/;
486 delete $ENV{BASH_ENV};
487 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
491 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
494 my ($level, $msg) = @_;
495 warn "$msg\n" if $level <= $verbosity;
498 my $extension_pkg = "extension0000";
501 # load a single script into its own package, once only
502 sub extension_package($) {
505 $extension_pkg{$path} ||= do {
506 my $pkg = "urxvt::" . ($extension_pkg++);
508 verbose 3, "loading extension '$path' into package '$pkg'";
510 open my $fh, "<:raw", $path
514 "package $pkg; use strict; use utf8;\n"
515 . "use base urxvt::term::extension::;\n"
516 . "#line 1 \"$path\"\n{\n"
517 . (do { local $/; <$fh> })
527 our $retval; # return value for urxvt
529 # called by the rxvt core
534 if ($htype == 0) { # INIT
535 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
539 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
540 if ($_ eq "default") {
541 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
542 } elsif (/^-(.*)$/) {
544 } elsif (/^([^<]+)<(.*)>$/) {
545 push @{ $ext_arg{$1} }, $2;
551 while (my ($ext, $argv) = each %ext_arg) {
552 my @files = grep -f $_, map "$_/$ext", @dirs;
555 $TERM->register_package (extension_package $files[0], $argv);
557 warn "perl extension '$ext' not found in perl library search path\n";
561 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
567 if (my $cb = $TERM->{_hook}[$htype]) {
568 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
573 while (my ($pkg, $cb) = each %$cb) {
574 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
578 $TERM->ungrab; # better to lose the grab than the session
584 if ($htype == 1) { # DESTROY
585 if (my $hook = delete $TERM->{_hook}) {
586 for my $htype (0..$#$hook) {
587 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
588 or set_should_invoke $htype, 0;
592 # clear package objects
593 %$_ = () for values %{ $TERM->{_pkg} };
602 # urxvt::term::extension
604 package urxvt::term::extension;
607 my ($self, %hook) = @_;
608 my $pkg = $self->{_pkg};
610 while (my ($name, $cb) = each %hook) {
611 my $htype = $HOOKTYPE{uc $name};
613 or Carp::croak "unsupported hook type '$name'";
615 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
616 $hook_count[$htype]++
617 or urxvt::set_should_invoke $htype, 1;
620 $self->{term}{_hook}[$htype]{$pkg} = $cb;
625 my ($self, @hook) = @_;
626 my $pkg = $self->{_pkg};
628 for my $name (@hook) {
629 my $htype = $HOOKTYPE{uc $name};
631 or Carp::croak "unsupported hook type '$name'";
633 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
634 --$hook_count[$htype]
635 or urxvt::set_should_invoke $htype, 0;
643 $AUTOLOAD =~ /:([^:]+)$/
644 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
649 \$proxy->{term}->$1 (\@_)
652 } or die "FATAL: unable to compile method forwarder: $@";
661 # urxvt::destroy_hook
663 sub urxvt::destroy_hook::DESTROY {
667 sub urxvt::destroy_hook(&) {
668 bless \shift, urxvt::destroy_hook::
671 package urxvt::anyevent;
673 =head2 The C<urxvt::anyevent> Class
675 The sole purpose of this class is to deliver an interface to the
676 C<AnyEvent> module - any module using it will work inside urxvt without
677 further work. The only exception is that you cannot wait on condition
678 variables, but non-blocking condvar use is ok. What this means is that you
679 cannot use blocking APIs, but the non-blocking variant should work.
685 $INC{"urxvt/anyevent.pm"} = 1; # mark us as there
686 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
689 my ($class, %arg) = @_;
695 ->start (urxvt::NOW + $arg{after})
697 $_[0]->stop; # need to cancel manually
703 my ($class, %arg) = @_;
707 bless [$arg{fh}, urxvt::iow
709 ->fd (fileno $arg{fh})
710 ->events (($arg{poll} =~ /r/ ? 1 : 0)
711 | ($arg{poll} =~ /w/ ? 2 : 0))
714 $cb->(($_[1] & 1 ? 'r' : '')
715 . ($_[1] & 2 ? 'w' : ''));
725 bless \my $flag, urxvt::anyevent::condvar::
728 sub urxvt::anyevent::condvar::broadcast {
732 sub urxvt::anyevent::condvar::wait {
734 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
740 =head2 The C<urxvt::term> Class
746 # find on_xxx subs in the package and register them
748 sub register_package {
749 my ($self, $pkg, $argv) = @_;
755 Scalar::Util::weaken ($proxy->{term} = $self);
757 $self->{_pkg}{$pkg} = $proxy;
759 for my $name (@HOOKNAME) {
760 if (my $ref = $pkg->can ("on_" . lc $name)) {
761 $proxy->enable ($name => $ref);
768 Destroy the terminal object (close the window, free resources etc.).
770 =item $isset = $term->option ($optval[, $set])
772 Returns true if the option specified by C<$optval> is enabled, and
773 optionally change it. All option values are stored by name in the hash
774 C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
776 Here is a a likely non-exhaustive list of option names, please see the
777 source file F</src/optinc.h> to see the actual list:
779 borderLess console cursorBlink cursorUnderline hold iconic insecure
780 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
781 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
782 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
783 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
784 tripleclickwords utmpInhibit visualBell
786 =item $value = $term->resource ($name[, $newval])
788 Returns the current resource value associated with a given name and
789 optionally sets a new value. Setting values is most useful in the C<init>
790 hook. Unset resources are returned and accepted as C<undef>.
792 The new value must be properly encoded to a suitable character encoding
793 before passing it to this method. Similarly, the returned value may need
794 to be converted from the used encoding to text.
796 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
797 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
800 Please note that resource strings will currently only be freed when the
801 terminal is destroyed, so changing options frequently will eat memory.
803 Here is a a likely non-exhaustive list of resource names, not all of which
804 are supported in every build, please see the source file F</src/rsinc.h>
805 to see the actual list:
807 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
808 borderLess color cursorBlink cursorUnderline cutchars delete_key
809 display_name embed ext_bwidth fade font geometry hold iconName
810 imFont imLocale inputMethod insecure int_bwidth intensityStyles
811 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
812 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
813 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
814 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
815 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
816 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
817 shade term_name title transparent transparent_all tripleclickwords
818 utmpInhibit visualBell
823 my ($self, $name) = (shift, shift);
824 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
825 &urxvt::term::_resource
828 =item $success = $term->parse_keysym ($keysym_spec, $command_string)
830 Adds a keymap translation exactly as specified via a resource. See the
831 C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
833 =item $rend = $term->rstyle ([$new_rstyle])
835 Return and optionally change the current rendition. Text that is output by
836 the terminal application will use this style.
838 =item ($row, $col) = $term->screen_cur ([$row, $col])
840 Return the current coordinates of the text cursor position and optionally
841 set it (which is usually bad as applications don't expect that).
843 =item ($row, $col) = $term->selection_mark ([$row, $col])
845 =item ($row, $col) = $term->selection_beg ([$row, $col])
847 =item ($row, $col) = $term->selection_end ([$row, $col])
849 Return the current values of the selection mark, begin or end positions,
850 and optionally set them to new values.
852 =item $success = $term->selection_grab ($eventtime)
854 Try to request the primary selection from the server (for example, as set
857 =item $oldtext = $term->selection ([$newtext])
859 Return the current selection text and optionally replace it by C<$newtext>.
861 =item $term->overlay_simple ($x, $y, $text)
863 Create a simple multi-line overlay box. See the next method for details.
868 my ($self, $x, $y, $text) = @_;
870 my @lines = split /\n/, $text;
872 my $w = List::Util::max map $self->strwidth ($_), @lines;
874 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
875 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
880 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
882 Create a new (empty) overlay at the given position with the given
883 width/height. C<$rstyle> defines the initial rendition style
884 (default: C<OVERLAY_RSTYLE>).
886 If C<$border> is C<2> (default), then a decorative border will be put
889 If either C<$x> or C<$y> is negative, then this is counted from the
890 right/bottom side, respectively.
892 This method returns an urxvt::overlay object. The overlay will be visible
893 as long as the perl object is referenced.
895 The methods currently supported on C<urxvt::overlay> objects are:
899 =item $overlay->set ($x, $y, $text, $rend)
901 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
902 text in rxvt-unicode's special encoding and an array of rendition values
903 at a specific position inside the overlay.
907 If visible, hide the overlay, but do not destroy it.
911 If hidden, display the overlay again.
915 =item $popup = $term->popup ($event)
917 Creates a new C<urxvt::popup> object that implements a popup menu. The
918 C<$event> I<must> be the event causing the menu to pop up (a button event,
924 my ($self, $event) = @_;
926 $self->grab ($event->{time}, 1)
934 Scalar::Util::weaken $popup->{term};
936 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
937 Scalar::Util::weaken $self->{_destroy}{$popup};
942 =item $cellwidth = $term->strwidth ($string)
944 Returns the number of screen-cells this string would need. Correctly
945 accounts for wide and combining characters.
947 =item $octets = $term->locale_encode ($string)
949 Convert the given text string into the corresponding locale encoding.
951 =item $string = $term->locale_decode ($octets)
953 Convert the given locale-encoded octets into a perl string.
955 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
957 XORs the rendition values in the given span with the provided value
958 (default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
961 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
963 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
964 whitespace will additionally be xored with the C<$rstyle2>, which defaults
965 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
968 =item $term->scr_bell
972 =item $term->scr_add_lines ($string)
974 Write the given text string to the screen, as if output by the application
975 running inside the terminal. It may not contain command sequences (escape
976 codes), but is free to use line feeds, carriage returns and tabs. The
977 string is a normal text string, not in locale-dependent encoding.
979 Normally its not a good idea to use this function, as programs might be
980 confused by changes in cursor position or scrolling. Its useful inside a
981 C<on_add_lines> hook, though.
983 =item $term->cmd_parse ($octets)
985 Similar to C<scr_add_lines>, but the argument must be in the
986 locale-specific encoding of the terminal and can contain command sequences
987 (escape codes) that will be interpreted.
989 =item $term->tt_write ($octets)
991 Write the octets given in C<$data> to the tty (i.e. as program input). To
992 pass characters instead of octets, you should convert your strings first
993 to the locale-specific encoding using C<< $term->locale_encode >>.
995 =item $old_events = $term->pty_ev_events ([$new_events])
997 Replaces the event mask of the pty watcher by the given event mask. Can
998 be used to suppress input and output handling to the pty/tty. See the
999 description of C<< urxvt::timer->events >>. Make sure to always restore
1002 =item $windowid = $term->parent
1004 Return the window id of the toplevel window.
1006 =item $windowid = $term->vt
1008 Return the window id of the terminal window.
1010 =item $window_width = $term->width
1012 =item $window_height = $term->height
1014 =item $font_width = $term->fwidth
1016 =item $font_height = $term->fheight
1018 =item $font_ascent = $term->fbase
1020 =item $terminal_rows = $term->nrow
1022 =item $terminal_columns = $term->ncol
1024 =item $has_focus = $term->focus
1026 =item $is_mapped = $term->mapped
1028 =item $max_scrollback = $term->saveLines
1030 =item $nrow_plus_saveLines = $term->total_rows
1032 =item $lines_in_scrollback = $term->nsaved
1034 Return various integers describing terminal characteristics.
1036 =item $lc_ctype = $term->locale
1038 Returns the LC_CTYPE category string used by this rxvt-unicode.
1040 =item $x_display = $term->display_id
1042 Return the DISPLAY used by rxvt-unicode.
1044 =item $modifiermask = $term->ModLevel3Mask
1046 =item $modifiermask = $term->ModMetaMask
1048 =item $modifiermask = $term->ModNumLockMask
1050 Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1051 AltGr), the meta key (often Alt) and the num lock key, if applicable.
1053 =item $view_start = $term->view_start ([$newvalue])
1055 Returns the negative row number of the topmost line. Minimum value is
1056 C<0>, which displays the normal terminal contents. Larger values scroll
1057 this many lines into the scrollback buffer.
1059 =item $term->want_refresh
1061 Requests a screen refresh. At the next opportunity, rxvt-unicode will
1062 compare the on-screen display with its stored representation. If they
1063 differ, it redraws the differences.
1065 Used after changing terminal contents to display them.
1067 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1069 Returns the text of the entire row with number C<$row_number>. Row C<0>
1070 is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
1071 terminal line. The scrollback buffer starts at line C<-1> and extends to
1072 line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
1075 If C<$new_text> is specified, it will replace characters in the current
1076 line, starting at column C<$start_col> (default C<0>), which is useful
1077 to replace only parts of a line. The font index in the rendition will
1078 automatically be updated.
1080 C<$text> is in a special encoding: tabs and wide characters that use more
1081 than one cell when displayed are padded with urxvt::NOCHAR characters
1082 (C<chr 65535>). Characters with combining characters and other characters
1083 that do not fit into the normal tetx encoding will be replaced with
1084 characters in the private use area.
1086 You have to obey this encoding when changing text. The advantage is
1087 that C<substr> and similar functions work on screen cells and not on
1090 The methods C<< $term->special_encode >> and C<< $term->special_decode >>
1091 can be used to convert normal strings into this encoding and vice versa.
1093 =item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1095 Like C<< $term->ROW_t >>, but returns an arrayref with rendition
1096 bitsets. Rendition bitsets contain information about colour, font, font
1097 styles and similar information. See also C<< $term->ROW_t >>.
1099 When setting rendition, the font mask will be ignored.
1101 See the section on RENDITION, above.
1103 =item $length = $term->ROW_l ($row_number[, $new_length])
1105 Returns the number of screen cells that are in use ("the line
1106 length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
1107 line is joined with the following one.
1109 =item $bool = $term->is_longer ($row_number)
1111 Returns true if the row is part of a multiple-row logical "line" (i.e.
1112 joined with the following row), which means all characters are in use
1113 and it is continued on the next row (and possibly a continuation of the
1116 =item $line = $term->line ($row_number)
1118 Create and return a new C<urxvt::line> object that stores information
1119 about the logical line that row C<$row_number> is part of. It supports the
1124 =item $text = $line->t ([$new_text])
1126 Returns or replaces the full text of the line, similar to C<ROW_t>
1128 =item $rend = $line->r ([$new_rend])
1130 Returns or replaces the full rendition array of the line, similar to C<ROW_r>
1132 =item $length = $line->l
1134 Returns the length of the line in cells, similar to C<ROW_l>.
1136 =item $rownum = $line->beg
1138 =item $rownum = $line->end
1140 Return the row number of the first/last row of the line, respectively.
1142 =item $offset = $line->offset_of ($row, $col)
1144 Returns the character offset of the given row|col pair within the logical
1147 =item ($row, $col) = $line->coord_of ($offset)
1149 Translates a string offset into terminal coordinates again.
1156 my ($self, $row) = @_;
1158 my $maxrow = $self->nrow - 1;
1160 my ($beg, $end) = ($row, $row);
1162 --$beg while $self->ROW_is_longer ($beg - 1);
1163 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1169 ncol => $self->ncol,
1170 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1174 sub urxvt::line::t {
1179 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1180 for $self->{beg} .. $self->{end};
1183 defined wantarray &&
1184 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1188 sub urxvt::line::r {
1193 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1194 for $self->{beg} .. $self->{end};
1197 if (defined wantarray) {
1199 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1201 $#$rend = $self->{len} - 1;
1208 sub urxvt::line::beg { $_[0]{beg} }
1209 sub urxvt::line::end { $_[0]{end} }
1210 sub urxvt::line::l { $_[0]{len} }
1212 sub urxvt::line::offset_of {
1213 my ($self, $row, $col) = @_;
1215 ($row - $self->{beg}) * $self->{ncol} + $col
1218 sub urxvt::line::coord_of {
1219 my ($self, $offset) = @_;
1224 $offset / $self->{ncol} + $self->{beg},
1225 $offset % $self->{ncol}
1229 =item $text = $term->special_encode $string
1231 Converts a perl string into the special encoding used by rxvt-unicode,
1232 where one character corresponds to one screen cell. See
1233 C<< $term->ROW_t >> for details.
1235 =item $string = $term->special_decode $text
1237 Converts rxvt-unicodes text reprsentation into a perl string. See
1238 C<< $term->ROW_t >> for details.
1240 =item $success = $term->grab_button ($button, $modifiermask)
1242 Registers a synchronous button grab. See the XGrabButton manpage.
1244 =item $success = $term->grab ($eventtime[, $sync])
1246 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1247 synchronous (C<$sync> is true). Also remembers the grab timestampe.
1249 =item $term->allow_events_async
1251 Calls XAllowEvents with AsyncBoth for the most recent grab.
1253 =item $term->allow_events_sync
1255 Calls XAllowEvents with SyncBoth for the most recent grab.
1257 =item $term->allow_events_replay
1259 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1264 Calls XUngrab for the most recent grab. Is called automatically on
1265 evaluation errors, as it is better to lose the grab in the error case as
1272 package urxvt::popup;
1274 =head2 The C<urxvt::popup> Class
1281 my ($self, $item) = @_;
1283 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1284 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1285 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1287 $item->{render} ||= sub { $_[0]{text} };
1289 push @{ $self->{item} }, $item;
1293 my ($self, $sep) = @_;
1298 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1300 render => sub { $sep x $self->{term}->ncol },
1301 activate => sub { },
1306 my ($self, $title) = @_;
1309 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1311 activate => sub { },
1316 my ($self, $text, $cb) = @_;
1318 $self->add_item ({ type => "button", text => $text, activate => $cb});
1322 my ($self, $text, $cb, $value) = @_;
1328 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1329 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); },
1332 $self->add_item ($item);
1338 local $urxvt::popup::self = $self;
1340 local $ENV{LC_ALL} = $self->{term}->locale;
1342 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1343 "--transient-for" => $self->{term}->parent,
1344 "-display" => $self->{term}->display_id,
1345 "-pe" => "urxvt-popup")
1346 or die "unable to create popup window\n";
1352 delete $self->{term}{_destroy}{$self};
1353 $self->{term}->ungrab;
1356 =head2 The C<urxvt::timer> Class
1358 This class implements timer watchers/events. Time is represented as a
1359 fractional number of seconds since the epoch. Example:
1361 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1362 $term->{timer} = urxvt::timer
1366 $term->{overlay}->set (0, 0,
1367 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1372 =item $timer = new urxvt::timer
1374 Create a new timer object in started state. It is scheduled to fire
1377 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1379 Set the callback to be called when the timer triggers.
1381 =item $tstamp = $timer->at
1383 Return the time this watcher will fire next.
1385 =item $timer = $timer->set ($tstamp)
1387 Set the time the event is generated to $tstamp.
1389 =item $timer = $timer->interval ($interval)
1391 Normally (and when C<$interval> is C<0>), the timer will automatically
1392 stop after it has fired once. If C<$interval> is non-zero, then the timer
1393 is automatically rescheduled at the given intervals.
1395 =item $timer = $timer->start
1399 =item $timer = $timer->start ($tstamp)
1401 Set the event trigger time to C<$tstamp> and start the timer.
1403 =item $timer = $timer->stop
1409 =head2 The C<urxvt::iow> Class
1411 This class implements io watchers/events. Example:
1413 $term->{socket} = ...
1414 $term->{iow} = urxvt::iow
1416 ->fd (fileno $term->{socket})
1417 ->events (urxvt::EVENT_READ)
1420 my ($iow, $revents) = @_;
1421 # $revents must be 1 here, no need to check
1422 sysread $term->{socket}, my $buf, 8192
1429 =item $iow = new urxvt::iow
1431 Create a new io watcher object in stopped state.
1433 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1435 Set the callback to be called when io events are triggered. C<$reventmask>
1436 is a bitset as described in the C<events> method.
1438 =item $iow = $iow->fd ($fd)
1440 Set the filedescriptor (not handle) to watch.
1442 =item $iow = $iow->events ($eventmask)
1444 Set the event mask to watch. The only allowed values are
1445 C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1446 together, or C<urxvt::EVENT_NONE>.
1448 =item $iow = $iow->start
1450 Start watching for requested events on the given handle.
1452 =item $iow = $iow->stop
1454 Stop watching for events on the given filehandle.
1460 =head2 URXVT_PERL_VERBOSITY
1462 This variable controls the verbosity level of the perl extension. Higher
1463 numbers indicate more verbose output.
1467 =item == 0 - fatal messages
1469 =item >= 3 - script loading and management
1471 =item >=10 - all events received
1477 Marc Lehmann <pcg@goof.com>
1478 http://software.schmorp.de/pkg/rxvt-unicode