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 =head1 PREPACKAGED EXTENSIONS
33 This section describes the extensions delivered with this release. 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 (More) intelligent selection. This extension tries to be more intelligent
45 when the user extends selections (double-click and further clicks). Right
46 now, it tries to select words, urls and complete shell-quoted
47 arguments, which is very convenient, too, if your F<ls> supports
48 C<--quoting-style=shell>.
50 A double-click usually selects the word under the cursor, further clicks
51 will enlarge the selection.
53 The selection works by trying to match a number of regexes and displaying
54 them in increasing order of length. You can add your own regexes by
55 specifying resources of the form:
57 URxvt.selection.pattern-0: perl-regex
58 URxvt.selection.pattern-1: perl-regex
61 The index number (0, 1...) must not have any holes, and each regex must
62 contain at least one pair of capturing parentheses, which will be used for
63 the match. For example, the followign adds a regex that matches everything
64 between two vertical bars:
66 URxvt.selection.pattern-0: \\|([^|]+)\\|
68 You can look at the source of the selection extension to see more
69 interesting uses, such as parsing a line from beginning to end.
71 This extension also offers the following bindable keyboard command:
77 Rot-13 the selection when activated. Used via keyboard trigger:
79 URxvt.keysym.C-M-r: perl:selection:rot13
83 =item option-popup (enabled by default)
85 Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
88 =item selection-popup (enabled by default)
90 Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91 text into various other formats/action (such as uri unescaping, perl
92 evalution, web-browser starting etc.), depending on content.
94 =item searchable-scrollback<hotkey> (enabled by default)
96 Adds regex search functionality to the scrollback buffer, triggered
97 by a hotkey (default: C<M-s>). While in search mode, normal terminal
98 input/output is suspended and a regex is displayed at the bottom of the
101 Inputting characters appends them to the regex and continues incremental
102 search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
103 search upwards/downwards in the scrollback buffer, C<End> jumps to the
104 bottom. C<Escape> leaves search mode and returns to the point where search
105 was started, while C<Enter> or C<Return> stay at the current position and
106 additionally stores the first match in the current line into the primary
109 =item selection-autotransform
111 This selection allows you to do automatic transforms on a selection
112 whenever a selection is made.
114 It works by specifying perl snippets (most useful is a single C<s///>
115 operator) that modify C<$_> as resources:
117 URxvt.selection-autotransform.0: transform
118 URxvt.selection-autotransform.1: transform
121 For example, the following will transform selections of the form
122 C<filename:number>, often seen in compiler messages, into C<vi +$filename
125 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
127 And this example matches the same,but replaces it with vi-commands you can
128 paste directly into your (vi :) editor:
130 URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
132 Of course, this can be modified to suit your needs and your editor :)
134 To expand the example above to typical perl error messages ("XXX at
135 FILENAME line YYY."), you need a slightly more elaborate solution:
137 URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
138 URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
140 The first line tells the selection code to treat the unchanging part of
141 every error message as a selection pattern, and the second line transforms
142 the message into vi commands to load the file.
146 Uses per-line display filtering (C<on_line_update>) to underline urls and
147 make them clickable. When middle-clicked, the program specified in the
148 resource C<urlLauncher> (default C<x-www-browser>) will be started with
149 the URL as first argument.
151 =item block-graphics-to-ascii
153 A not very useful example of filtering all text output to the terminal,
154 by replacing all line-drawing characters (U+2500 .. U+259F) by a
155 similar-looking ascii character.
159 Displays a digital clock using the built-in overlay.
161 =item example-refresh-hooks
163 Displays a very simple digital clock in the upper right corner of the
164 window. Illustrates overwriting the refresh callbacks to create your own
169 =head1 API DOCUMENTATION
171 =head2 General API Considerations
173 All objects (such as terminals, time watchers etc.) are typical
174 reference-to-hash objects. The hash can be used to store anything you
175 like. All members starting with an underscore (such as C<_ptr> or
176 C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
179 When objects are destroyed on the C++ side, the perl object hashes are
180 emptied, so its best to store related objects such as time watchers and
181 the like inside the terminal object so they get destroyed as soon as the
182 terminal is destroyed.
184 Argument names also often indicate the type of a parameter. Here are some
185 hints on what they mean:
191 Rxvt-unicodes special way of encoding text, where one "unicode" character
192 always represents one screen cell. See L<ROW_t> for a discussion of this format.
196 A perl text string, with an emphasis on I<text>. It can store all unicode
197 characters and is to be distinguished with text encoded in a specific
198 encoding (often locale-specific) and binary data.
202 Either binary data or - more common - a text string encoded in a
207 =head2 Extension Objects
209 Very perl extension is a perl class. A separate perl object is created
210 for each terminal and each extension and passed as the first parameter to
211 hooks. So extensions can use their C<$self> object without having to think
212 about other extensions, with the exception of methods and members that
213 begin with an underscore character C<_>: these are reserved for internal
216 Although it isn't a C<urxvt::term> object, you can call all methods of the
217 C<urxvt::term> class on this object.
219 It has the following methods and data members:
223 =item $urxvt_term = $self->{term}
225 Returns the C<urxvt::term> object associated with this instance of the
226 extension. This member I<must not> be changed in any way.
228 =item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
230 Dynamically enable the given hooks (named without the C<on_> prefix) for
231 this extension, replacing any previous hook. This is useful when you want
232 to overwrite time-critical hooks only temporarily.
234 =item $self->disable ($hook_name[, $hook_name..])
236 Dynamically disable the given hooks.
242 The following subroutines can be declared in extension files, and will be
243 called whenever the relevant event happens.
245 The first argument passed to them is an extension oject as described in
246 the in the C<Extension Objects> section.
248 B<All> of these hooks must return a boolean value. If it is true, then the
249 event counts as being I<consumed>, and the invocation of other hooks is
250 skipped, and the relevant action might not be carried out by the C++ code.
252 I<< When in doubt, return a false value (preferably C<()>). >>
258 Called after a new terminal object has been initialized, but before
259 windows are created or the command gets run. Most methods are unsafe to
260 call or deliver senseless data, as terminal size and other characteristics
261 have not yet been determined. You can safely query and change resources,
266 Called after the screen is "reset" for any reason, such as resizing or
267 control sequences. Here is where you can react on changes to size-related
272 Called at the very end of initialisation of a new terminal, just before
273 returning to the mainloop.
275 =item on_sel_make $term, $eventtime
277 Called whenever a selection has been made by the user, but before the
278 selection text is copied, so changes to the beginning, end or type of the
279 selection will be honored.
281 Returning a true value aborts selection making by urxvt, in which case you
282 have to make a selection yourself by calling C<< $term->selection_grab >>.
284 =item on_sel_grab $term, $eventtime
286 Called whenever a selection has been copied, but before the selection is
287 requested from the server. The selection text can be queried and changed
288 by calling C<< $term->selection >>.
290 Returning a true value aborts selection grabbing. It will still be hilighted.
292 =item on_sel_extend $term
294 Called whenever the user tries to extend the selection (e.g. with a double
295 click) and is either supposed to return false (normal operation), or
296 should extend the selection itelf and return true to suppress the built-in
297 processing. This can happen multiple times, as long as the callback
298 returns true, it will be called on every further click by the user and is
299 supposed to enlarge the selection more and more, if possible.
301 See the F<selection> example extension.
303 =item on_view_change $term, $offset
305 Called whenever the view offset changes, i..e the user or program
306 scrolls. Offset C<0> means display the normal terminal, positive values
307 show this many lines of scrollback.
309 =item on_scroll_back $term, $lines, $saved
311 Called whenever lines scroll out of the terminal area into the scrollback
312 buffer. C<$lines> is the number of lines scrolled out and may be larger
313 than the scroll back buffer or the terminal.
315 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
316 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
317 number of lines that will be in the scrollback buffer.
319 =item on_osc_seq $term, $string
321 Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
322 operating system command) is processed. Cursor position and other state
323 information is up-to-date when this happens. For interoperability, the
324 string should start with the extension name and a colon, to distinguish
325 it from commands for other extensions, and this might be enforced in the
328 Be careful not ever to trust (in a security sense) the data you receive,
329 as its source can not easily be controleld (e-mail content, messages from
330 other users on the same system etc.).
332 =item on_add_lines $term, $string
334 Called whenever text is about to be output, with the text as argument. You
335 can filter/change and output the text yourself by returning a true value
336 and calling C<< $term->scr_add_lines >> yourself. Please note that this
337 might be very slow, however, as your hook is called for B<all> text being
340 =item on_tt_write $term, $octets
342 Called whenever some data is written to the tty/pty and can be used to
343 suppress or filter tty input.
345 =item on_line_update $term, $row
347 Called whenever a line was updated or changed. Can be used to filter
348 screen output (e.g. underline urls or other useless stuff). Only lines
349 that are being shown will be filtered, and, due to performance reasons,
350 not always immediately.
352 The row number is always the topmost row of the line if the line spans
355 Please note that, if you change the line, then the hook might get called
356 later with the already-modified line (e.g. if unrelated parts change), so
357 you cannot just toggle rendition bits, but only set them.
359 =item on_refresh_begin $term
361 Called just before the screen gets redrawn. Can be used for overlay
362 or similar effects by modify terminal contents in refresh_begin, and
363 restoring them in refresh_end. The built-in overlay and selection display
364 code is run after this hook, and takes precedence.
366 =item on_refresh_end $term
368 Called just after the screen gets redrawn. See C<on_refresh_begin>.
370 =item on_keyboard_command $term, $string
372 Called whenever the user presses a key combination that has a
373 C<perl:string> action bound to it (see description of the B<keysym>
374 resource in the @@RXVT_NAME@@(1) manpage).
376 =item on_x_event $term, $event
378 Called on every X event received on the vt window (and possibly other
379 windows). Should only be used as a last resort. Most event structure
380 members are not passed.
382 =item on_focus_in $term
384 Called whenever the window gets the keyboard focus, before rxvt-unicode
385 does focus in processing.
387 =item on_focus_out $term
389 Called wheneever the window loses keyboard focus, before rxvt-unicode does
390 focus out processing.
392 =item on_key_press $term, $event, $keysym, $octets
394 =item on_key_release $term, $event, $keysym
396 =item on_button_press $term, $event
398 =item on_button_release $term, $event
400 =item on_motion_notify $term, $event
402 =item on_map_notify $term, $event
404 =item on_unmap_notify $term, $event
406 Called whenever the corresponding X event is received for the terminal If
407 the hook returns true, then the even will be ignored by rxvt-unicode.
409 The event is a hash with most values as named by Xlib (see the XEvent
410 manpage), with the additional members C<row> and C<col>, which are the row
411 and column under the mouse cursor.
413 C<on_key_press> additionally receives the string rxvt-unicode would
414 output, if any, in locale-specific encoding.
433 our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
441 =head2 Variables in the C<urxvt> Package
447 The rxvt-unicode library directory, where, among other things, the perl
448 modules and scripts are stored.
450 =item $urxvt::RESCLASS, $urxvt::RESCLASS
452 The resource class and name rxvt-unicode uses to look up X resources.
454 =item $urxvt::RXVTNAME
456 The basename of the installed binaries, usually C<urxvt>.
460 The current terminal. This variable stores the current C<urxvt::term>
461 object, whenever a callback/hook is executing.
465 =head2 Functions in the C<urxvt> Package
469 =item urxvt::fatal $errormessage
471 Fatally aborts execution with the given error message. Avoid at all
472 costs! The only time this is acceptable is when the terminal process
475 =item urxvt::warn $string
477 Calls C<rxvt_warn> with the given string which should not include a
478 newline. The module also overwrites the C<warn> builtin with a function
479 that calls this function.
481 Using this function has the advantage that its output ends up in the
482 correct place, e.g. on stderr of the connecting urxvtc client.
484 Messages have a size limit of 1023 bytes currently.
486 =item $is_safe = urxvt::safe
488 Returns true when it is safe to do potentially unsafe things, such as
489 evaluating perl code specified by the user. This is true when urxvt was
490 started setuid or setgid.
492 =item $time = urxvt::NOW
494 Returns the "current time" (as per the event loop).
496 =item urxvt::CurrentTime
498 =item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
499 Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
500 Button4Mask, Button5Mask, AnyModifier
502 =item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask,
503 ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask,
504 PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
505 Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask,
506 KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask,
507 ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask,
508 FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
510 =item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
511 EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
512 GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
513 UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
514 ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
515 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
516 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
518 Various constants for use in X calls and event processing.
524 Rendition bitsets contain information about colour, font, font styles and
525 similar information for each screen cell.
527 The following "macros" deal with changes in rendition sets. You should
528 never just create a bitset, you should always modify an existing one,
529 as they contain important information required for correct operation of
534 =item $rend = urxvt::DEFAULT_RSTYLE
536 Returns the default rendition, as used when the terminal is starting up or
537 being reset. Useful as a base to start when creating renditions.
539 =item $rend = urxvt::OVERLAY_RSTYLE
541 Return the rendition mask used for overlays by default.
543 =item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
545 Return the bit that enabled bold, italic, blink, reverse-video and
546 underline, respectively. To enable such a style, just logically OR it into
549 =item $foreground = urxvt::GET_BASEFG $rend
551 =item $background = urxvt::GET_BASEBG $rend
553 Return the foreground/background colour index, respectively.
555 =item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
557 =item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
559 Replace the foreground/background colour in the rendition mask with the
562 =item $value = urxvt::GET_CUSTOM $rend
564 Return the "custom" value: Every rendition has 5 bits for use by
565 extensions. They can be set and changed as you like and are initially
568 =item $rend = urxvt::SET_CUSTOM $rend, $new_value
570 Change the custom value.
579 # overwrite perl's warn
580 *CORE::GLOBAL::warn = sub {
581 my $msg = join "", @_;
583 unless $msg =~ /\n$/;
587 # %ENV is the original startup environment
590 delete $ENV{BASH_ENV};
591 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
594 my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
597 my ($level, $msg) = @_;
598 warn "$msg\n" if $level <= $verbosity;
601 my $extension_pkg = "extension0000";
604 # load a single script into its own package, once only
605 sub extension_package($) {
608 $extension_pkg{$path} ||= do {
609 my $pkg = "urxvt::" . ($extension_pkg++);
611 verbose 3, "loading extension '$path' into package '$pkg'";
613 open my $fh, "<:raw", $path
617 "package $pkg; use strict; use utf8;\n"
618 . "use base urxvt::term::extension::;\n"
619 . "#line 1 \"$path\"\n{\n"
620 . (do { local $/; <$fh> })
630 our $retval; # return value for urxvt
632 # called by the rxvt core
637 if ($htype == 0) { # INIT
638 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
642 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
643 if ($_ eq "default") {
644 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
645 } elsif (/^-(.*)$/) {
647 } elsif (/^([^<]+)<(.*)>$/) {
648 push @{ $ext_arg{$1} }, $2;
654 while (my ($ext, $argv) = each %ext_arg) {
655 my @files = grep -f $_, map "$_/$ext", @dirs;
658 $TERM->register_package (extension_package $files[0], $argv);
660 warn "perl extension '$ext' not found in perl library search path\n";
664 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
670 if (my $cb = $TERM->{_hook}[$htype]) {
671 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
676 while (my ($pkg, $cb) = each %$cb) {
677 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
681 $TERM->ungrab; # better to lose the grab than the session
686 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
690 if ($htype == 1) { # DESTROY
691 # clear package objects
692 %$_ = () for values %{ $TERM->{_pkg} };
705 if !defined $pid or $pid;
707 %ENV = %{ $TERM->env };
713 # urxvt::term::extension
715 package urxvt::term::extension;
718 my ($self, %hook) = @_;
719 my $pkg = $self->{_pkg};
721 while (my ($name, $cb) = each %hook) {
722 my $htype = $HOOKTYPE{uc $name};
724 or Carp::croak "unsupported hook type '$name'";
726 $self->set_should_invoke ($htype, +1)
727 unless exists $self->{term}{_hook}[$htype]{$pkg};
729 $self->{term}{_hook}[$htype]{$pkg} = $cb;
734 my ($self, @hook) = @_;
735 my $pkg = $self->{_pkg};
737 for my $name (@hook) {
738 my $htype = $HOOKTYPE{uc $name};
740 or Carp::croak "unsupported hook type '$name'";
742 $self->set_should_invoke ($htype, -1)
743 if delete $self->{term}{_hook}[$htype]{$pkg};
750 $AUTOLOAD =~ /:([^:]+)$/
751 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
756 \$proxy->{term}->$1 (\@_)
759 } or die "FATAL: unable to compile method forwarder: $@";
768 # urxvt::destroy_hook
770 sub urxvt::destroy_hook::DESTROY {
774 sub urxvt::destroy_hook(&) {
775 bless \shift, urxvt::destroy_hook::
778 package urxvt::anyevent;
780 =head2 The C<urxvt::anyevent> Class
782 The sole purpose of this class is to deliver an interface to the
783 C<AnyEvent> module - any module using it will work inside urxvt without
784 further programming. The only exception is that you cannot wait on
785 condition variables, but non-blocking condvar use is ok. What this means
786 is that you cannot use blocking APIs, but the non-blocking variant should
793 $INC{"urxvt/anyevent.pm"} = 1; # mark us as there
794 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
797 my ($class, %arg) = @_;
803 ->start (urxvt::NOW + $arg{after})
805 $_[0]->stop; # need to cancel manually
811 my ($class, %arg) = @_;
815 bless [$arg{fh}, urxvt::iow
817 ->fd (fileno $arg{fh})
818 ->events (($arg{poll} =~ /r/ ? 1 : 0)
819 | ($arg{poll} =~ /w/ ? 2 : 0))
822 $cb->(($_[1] & 1 ? 'r' : '')
823 . ($_[1] & 2 ? 'w' : ''));
833 bless \my $flag, urxvt::anyevent::condvar::
836 sub urxvt::anyevent::condvar::broadcast {
840 sub urxvt::anyevent::condvar::wait {
842 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
848 =head2 The C<urxvt::term> Class
854 # find on_xxx subs in the package and register them
856 sub register_package {
857 my ($self, $pkg, $argv) = @_;
863 Scalar::Util::weaken ($proxy->{term} = $self);
865 $self->{_pkg}{$pkg} = $proxy;
867 for my $name (@HOOKNAME) {
868 if (my $ref = $pkg->can ("on_" . lc $name)) {
869 $proxy->enable ($name => $ref);
874 =item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
876 Creates a new terminal, very similar as if you had started it with system
877 C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
878 hash which defines the environment of the new terminal.
880 Croaks (and probably outputs an error message) if the new instance
881 couldn't be created. Returns C<undef> if the new instance didn't
882 initialise perl, and the terminal object otherwise. The C<init> and
883 C<start> hooks will be called during this call.
888 my ($class, $env, @args) = @_;
890 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
895 Destroy the terminal object (close the window, free resources
896 etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
897 watchers (timers, io watchers) are still active.
899 =item $isset = $term->option ($optval[, $set])
901 Returns true if the option specified by C<$optval> is enabled, and
902 optionally change it. All option values are stored by name in the hash
903 C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
905 Here is a a likely non-exhaustive list of option names, please see the
906 source file F</src/optinc.h> to see the actual list:
908 borderLess console cursorBlink cursorUnderline hold iconic insecure
909 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
910 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
911 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
912 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
913 tripleclickwords utmpInhibit visualBell
915 =item $value = $term->resource ($name[, $newval])
917 Returns the current resource value associated with a given name and
918 optionally sets a new value. Setting values is most useful in the C<init>
919 hook. Unset resources are returned and accepted as C<undef>.
921 The new value must be properly encoded to a suitable character encoding
922 before passing it to this method. Similarly, the returned value may need
923 to be converted from the used encoding to text.
925 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
926 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
929 Please note that resource strings will currently only be freed when the
930 terminal is destroyed, so changing options frequently will eat memory.
932 Here is a a likely non-exhaustive list of resource names, not all of which
933 are supported in every build, please see the source file F</src/rsinc.h>
934 to see the actual list:
936 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
937 borderLess color cursorBlink cursorUnderline cutchars delete_key
938 display_name embed ext_bwidth fade font geometry hold iconName
939 imFont imLocale inputMethod insecure int_bwidth intensityStyles
940 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
941 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
942 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
943 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
944 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
945 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
946 shade term_name title transparent transparent_all tripleclickwords
947 utmpInhibit visualBell
952 my ($self, $name) = (shift, shift);
953 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
954 &urxvt::term::_resource
957 =item $value = $term->x_resource ($pattern)
959 Returns the X-Resource for the given pattern, excluding the program or
960 class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
961 same value as used by this instance of rxvt-unicode. Returns C<undef> if no
962 resource with that pattern exists.
964 This method should only be called during the C<on_start> hook, as there is
965 only one resource database per display, and later invocations might return
968 =item $success = $term->parse_keysym ($keysym_spec, $command_string)
970 Adds a keymap translation exactly as specified via a resource. See the
971 C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
973 =item $rend = $term->rstyle ([$new_rstyle])
975 Return and optionally change the current rendition. Text that is output by
976 the terminal application will use this style.
978 =item ($row, $col) = $term->screen_cur ([$row, $col])
980 Return the current coordinates of the text cursor position and optionally
981 set it (which is usually bad as applications don't expect that).
983 =item ($row, $col) = $term->selection_mark ([$row, $col])
985 =item ($row, $col) = $term->selection_beg ([$row, $col])
987 =item ($row, $col) = $term->selection_end ([$row, $col])
989 Return the current values of the selection mark, begin or end positions,
990 and optionally set them to new values.
992 =item $term->selection_make ($eventtime[, $rectangular])
994 Tries to make a selection as set by C<selection_beg> and
995 C<selection_end>. If C<$rectangular> is true (default: false), a
996 rectangular selection will be made. This is the prefered function to make
999 =item $success = $term->selection_grab ($eventtime)
1001 Try to request the primary selection text from the server (for example, as
1002 set by the next method). No visual feedback will be given. This function
1003 is mostly useful from within C<on_sel_grab> hooks.
1005 =item $oldtext = $term->selection ([$newtext])
1007 Return the current selection text and optionally replace it by C<$newtext>.
1009 =item $term->overlay_simple ($x, $y, $text)
1011 Create a simple multi-line overlay box. See the next method for details.
1015 sub overlay_simple {
1016 my ($self, $x, $y, $text) = @_;
1018 my @lines = split /\n/, $text;
1020 my $w = List::Util::max map $self->strwidth ($_), @lines;
1022 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
1023 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
1028 =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
1030 Create a new (empty) overlay at the given position with the given
1031 width/height. C<$rstyle> defines the initial rendition style
1032 (default: C<OVERLAY_RSTYLE>).
1034 If C<$border> is C<2> (default), then a decorative border will be put
1037 If either C<$x> or C<$y> is negative, then this is counted from the
1038 right/bottom side, respectively.
1040 This method returns an urxvt::overlay object. The overlay will be visible
1041 as long as the perl object is referenced.
1043 The methods currently supported on C<urxvt::overlay> objects are:
1047 =item $overlay->set ($x, $y, $text, $rend)
1049 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1050 text in rxvt-unicode's special encoding and an array of rendition values
1051 at a specific position inside the overlay.
1053 =item $overlay->hide
1055 If visible, hide the overlay, but do not destroy it.
1057 =item $overlay->show
1059 If hidden, display the overlay again.
1063 =item $popup = $term->popup ($event)
1065 Creates a new C<urxvt::popup> object that implements a popup menu. The
1066 C<$event> I<must> be the event causing the menu to pop up (a button event,
1072 my ($self, $event) = @_;
1074 $self->grab ($event->{time}, 1)
1082 Scalar::Util::weaken $popup->{term};
1084 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1085 Scalar::Util::weaken $self->{_destroy}{$popup};
1090 =item $cellwidth = $term->strwidth ($string)
1092 Returns the number of screen-cells this string would need. Correctly
1093 accounts for wide and combining characters.
1095 =item $octets = $term->locale_encode ($string)
1097 Convert the given text string into the corresponding locale encoding.
1099 =item $string = $term->locale_decode ($octets)
1101 Convert the given locale-encoded octets into a perl string.
1103 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1105 XORs the rendition values in the given span with the provided value
1106 (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1107 refresh hooks to provide effects similar to the selection.
1109 =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1111 Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1112 whitespace will additionally be xored with the C<$rstyle2>, which defaults
1113 to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1114 it instead. Both styles I<MUST NOT> contain font styles.
1116 =item $term->scr_bell
1120 =item $term->scr_add_lines ($string)
1122 Write the given text string to the screen, as if output by the application
1123 running inside the terminal. It may not contain command sequences (escape
1124 codes), but is free to use line feeds, carriage returns and tabs. The
1125 string is a normal text string, not in locale-dependent encoding.
1127 Normally its not a good idea to use this function, as programs might be
1128 confused by changes in cursor position or scrolling. Its useful inside a
1129 C<on_add_lines> hook, though.
1131 =item $term->cmd_parse ($octets)
1133 Similar to C<scr_add_lines>, but the argument must be in the
1134 locale-specific encoding of the terminal and can contain command sequences
1135 (escape codes) that will be interpreted.
1137 =item $term->tt_write ($octets)
1139 Write the octets given in C<$data> to the tty (i.e. as program input). To
1140 pass characters instead of octets, you should convert your strings first
1141 to the locale-specific encoding using C<< $term->locale_encode >>.
1143 =item $old_events = $term->pty_ev_events ([$new_events])
1145 Replaces the event mask of the pty watcher by the given event mask. Can
1146 be used to suppress input and output handling to the pty/tty. See the
1147 description of C<< urxvt::timer->events >>. Make sure to always restore
1150 =item $windowid = $term->parent
1152 Return the window id of the toplevel window.
1154 =item $windowid = $term->vt
1156 Return the window id of the terminal window.
1158 =item $term->vt_emask_add ($x_event_mask)
1160 Adds the specified events to the vt event mask. Useful e.g. when you want
1161 to receive pointer events all the times:
1163 $term->vt_emask_add (urxvt::PointerMotionMask);
1165 =item $window_width = $term->width
1167 =item $window_height = $term->height
1169 =item $font_width = $term->fwidth
1171 =item $font_height = $term->fheight
1173 =item $font_ascent = $term->fbase
1175 =item $terminal_rows = $term->nrow
1177 =item $terminal_columns = $term->ncol
1179 =item $has_focus = $term->focus
1181 =item $is_mapped = $term->mapped
1183 =item $max_scrollback = $term->saveLines
1185 =item $nrow_plus_saveLines = $term->total_rows
1187 =item $topmost_scrollback_row = $term->top_row
1189 Return various integers describing terminal characteristics.
1191 =item $x_display = $term->display_id
1193 Return the DISPLAY used by rxvt-unicode.
1195 =item $lc_ctype = $term->locale
1197 Returns the LC_CTYPE category string used by this rxvt-unicode.
1199 =item $env = $term->env
1201 Returns a copy of the environment in effect for the terminal as a hashref
1202 similar to C<\%ENV>.
1207 if (my $env = $_[0]->_env) {
1208 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1214 =item $modifiermask = $term->ModLevel3Mask
1216 =item $modifiermask = $term->ModMetaMask
1218 =item $modifiermask = $term->ModNumLockMask
1220 Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1221 AltGr), the meta key (often Alt) and the num lock key, if applicable.
1223 =item $view_start = $term->view_start ([$newvalue])
1225 Returns the row number of the topmost displayed line. Maximum value is
1226 C<0>, which displays the normal terminal contents. Lower values scroll
1227 this many lines into the scrollback buffer.
1229 =item $term->want_refresh
1231 Requests a screen refresh. At the next opportunity, rxvt-unicode will
1232 compare the on-screen display with its stored representation. If they
1233 differ, it redraws the differences.
1235 Used after changing terminal contents to display them.
1237 =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1239 Returns the text of the entire row with number C<$row_number>. Row C<0>
1240 is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
1241 terminal line. The scrollback buffer starts at line C<-1> and extends to
1242 line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
1245 If C<$new_text> is specified, it will replace characters in the current
1246 line, starting at column C<$start_col> (default C<0>), which is useful
1247 to replace only parts of a line. The font index in the rendition will
1248 automatically be updated.
1250 C<$text> is in a special encoding: tabs and wide characters that use more
1251 than one cell when displayed are padded with urxvt::NOCHAR characters
1252 (C<chr 65535>). Characters with combining characters and other characters
1253 that do not fit into the normal tetx encoding will be replaced with
1254 characters in the private use area.
1256 You have to obey this encoding when changing text. The advantage is
1257 that C<substr> and similar functions work on screen cells and not on
1260 The methods C<< $term->special_encode >> and C<< $term->special_decode >>
1261 can be used to convert normal strings into this encoding and vice versa.
1263 =item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1265 Like C<< $term->ROW_t >>, but returns an arrayref with rendition
1266 bitsets. Rendition bitsets contain information about colour, font, font
1267 styles and similar information. See also C<< $term->ROW_t >>.
1269 When setting rendition, the font mask will be ignored.
1271 See the section on RENDITION, above.
1273 =item $length = $term->ROW_l ($row_number[, $new_length])
1275 Returns the number of screen cells that are in use ("the line
1276 length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
1277 line is joined with the following one.
1279 =item $bool = $term->is_longer ($row_number)
1281 Returns true if the row is part of a multiple-row logical "line" (i.e.
1282 joined with the following row), which means all characters are in use
1283 and it is continued on the next row (and possibly a continuation of the
1286 =item $line = $term->line ($row_number)
1288 Create and return a new C<urxvt::line> object that stores information
1289 about the logical line that row C<$row_number> is part of. It supports the
1294 =item $text = $line->t ([$new_text])
1296 Returns or replaces the full text of the line, similar to C<ROW_t>
1298 =item $rend = $line->r ([$new_rend])
1300 Returns or replaces the full rendition array of the line, similar to C<ROW_r>
1302 =item $length = $line->l
1304 Returns the length of the line in cells, similar to C<ROW_l>.
1306 =item $rownum = $line->beg
1308 =item $rownum = $line->end
1310 Return the row number of the first/last row of the line, respectively.
1312 =item $offset = $line->offset_of ($row, $col)
1314 Returns the character offset of the given row|col pair within the logical
1315 line. Works for rows outside the line, too, and returns corresponding
1316 offsets outside the string.
1318 =item ($row, $col) = $line->coord_of ($offset)
1320 Translates a string offset into terminal coordinates again.
1327 my ($self, $row) = @_;
1329 my $maxrow = $self->nrow - 1;
1331 my ($beg, $end) = ($row, $row);
1333 --$beg while $self->ROW_is_longer ($beg - 1);
1334 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1340 ncol => $self->ncol,
1341 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1345 sub urxvt::line::t {
1350 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1351 for $self->{beg} .. $self->{end};
1354 defined wantarray &&
1355 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1359 sub urxvt::line::r {
1364 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1365 for $self->{beg} .. $self->{end};
1368 if (defined wantarray) {
1370 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1372 $#$rend = $self->{len} - 1;
1379 sub urxvt::line::beg { $_[0]{beg} }
1380 sub urxvt::line::end { $_[0]{end} }
1381 sub urxvt::line::l { $_[0]{len} }
1383 sub urxvt::line::offset_of {
1384 my ($self, $row, $col) = @_;
1386 ($row - $self->{beg}) * $self->{ncol} + $col
1389 sub urxvt::line::coord_of {
1390 my ($self, $offset) = @_;
1395 $offset / $self->{ncol} + $self->{beg},
1396 $offset % $self->{ncol}
1400 =item $text = $term->special_encode $string
1402 Converts a perl string into the special encoding used by rxvt-unicode,
1403 where one character corresponds to one screen cell. See
1404 C<< $term->ROW_t >> for details.
1406 =item $string = $term->special_decode $text
1408 Converts rxvt-unicodes text reprsentation into a perl string. See
1409 C<< $term->ROW_t >> for details.
1411 =item $success = $term->grab_button ($button, $modifiermask)
1413 Registers a synchronous button grab. See the XGrabButton manpage.
1415 =item $success = $term->grab ($eventtime[, $sync])
1417 Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1418 synchronous (C<$sync> is true). Also remembers the grab timestampe.
1420 =item $term->allow_events_async
1422 Calls XAllowEvents with AsyncBoth for the most recent grab.
1424 =item $term->allow_events_sync
1426 Calls XAllowEvents with SyncBoth for the most recent grab.
1428 =item $term->allow_events_replay
1430 Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1435 Calls XUngrab for the most recent grab. Is called automatically on
1436 evaluation errors, as it is better to lose the grab in the error case as
1443 package urxvt::popup;
1445 =head2 The C<urxvt::popup> Class
1452 my ($self, $item) = @_;
1454 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1455 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1456 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1458 $item->{render} ||= sub { $_[0]{text} };
1460 push @{ $self->{item} }, $item;
1463 =item $popup->add_title ($title)
1465 Adds a non-clickable title to the popup.
1470 my ($self, $title) = @_;
1473 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1475 activate => sub { },
1479 =item $popup->add_separator ([$sepchr])
1481 Creates a separator, optionally using the character given as C<$sepchr>.
1486 my ($self, $sep) = @_;
1491 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1493 render => sub { $sep x $self->{term}->ncol },
1494 activate => sub { },
1498 =item $popup->add_button ($text, $cb)
1500 Adds a clickable button to the popup. C<$cb> is called whenever it is
1506 my ($self, $text, $cb) = @_;
1508 $self->add_item ({ type => "button", text => $text, activate => $cb});
1511 =item $popup->add_toggle ($text, $cb, $initial_value)
1513 Adds a toggle/checkbox item to the popup. Teh callback gets called
1514 whenever it gets toggled, with a boolean indicating its value as its first
1520 my ($self, $text, $cb, $value) = @_;
1526 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1527 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1530 $self->add_item ($item);
1535 Displays the popup (which is initially hidden).
1542 local $urxvt::popup::self = $self;
1544 my $env = $self->{term}->env;
1545 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1546 delete $env->{LC_ALL};
1547 $env->{LC_CTYPE} = $self->{term}->locale;
1549 urxvt::term->new ($env, $self->{term}->resource ("name"),
1550 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1551 "--transient-for" => $self->{term}->parent,
1552 "-display" => $self->{term}->display_id,
1553 "-pe" => "urxvt-popup")
1554 or die "unable to create popup window\n";
1560 delete $self->{term}{_destroy}{$self};
1561 $self->{term}->ungrab;
1566 =head2 The C<urxvt::timer> Class
1568 This class implements timer watchers/events. Time is represented as a
1569 fractional number of seconds since the epoch. Example:
1571 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1572 $term->{timer} = urxvt::timer
1576 $term->{overlay}->set (0, 0,
1577 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1582 =item $timer = new urxvt::timer
1584 Create a new timer object in started state. It is scheduled to fire
1587 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
1589 Set the callback to be called when the timer triggers.
1591 =item $tstamp = $timer->at
1593 Return the time this watcher will fire next.
1595 =item $timer = $timer->set ($tstamp)
1597 Set the time the event is generated to $tstamp.
1599 =item $timer = $timer->interval ($interval)
1601 Normally (and when C<$interval> is C<0>), the timer will automatically
1602 stop after it has fired once. If C<$interval> is non-zero, then the timer
1603 is automatically rescheduled at the given intervals.
1605 =item $timer = $timer->start
1609 =item $timer = $timer->start ($tstamp)
1611 Set the event trigger time to C<$tstamp> and start the timer.
1613 =item $timer = $timer->stop
1619 =head2 The C<urxvt::iow> Class
1621 This class implements io watchers/events. Example:
1623 $term->{socket} = ...
1624 $term->{iow} = urxvt::iow
1626 ->fd (fileno $term->{socket})
1627 ->events (urxvt::EVENT_READ)
1630 my ($iow, $revents) = @_;
1631 # $revents must be 1 here, no need to check
1632 sysread $term->{socket}, my $buf, 8192
1639 =item $iow = new urxvt::iow
1641 Create a new io watcher object in stopped state.
1643 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1645 Set the callback to be called when io events are triggered. C<$reventmask>
1646 is a bitset as described in the C<events> method.
1648 =item $iow = $iow->fd ($fd)
1650 Set the filedescriptor (not handle) to watch.
1652 =item $iow = $iow->events ($eventmask)
1654 Set the event mask to watch. The only allowed values are
1655 C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1656 together, or C<urxvt::EVENT_NONE>.
1658 =item $iow = $iow->start
1660 Start watching for requested events on the given handle.
1662 =item $iow = $iow->stop
1664 Stop watching for events on the given filehandle.
1670 =head2 URXVT_PERL_VERBOSITY
1672 This variable controls the verbosity level of the perl extension. Higher
1673 numbers indicate more verbose output.
1677 =item == 0 - fatal messages
1679 =item >= 3 - script loading and management
1681 =item >=10 - all called hooks
1683 =item >=11 - hook reutrn values
1689 Marc Lehmann <pcg@goof.com>
1690 http://software.schmorp.de/pkg/rxvt-unicode