urxvtperl(3)

📦
version 9.31 · 14 versions
, in opensuse-leap 16.0

🎀 NAME 🎀

urxvtperl — bestie, it's rxvt-unicode's embedded perl interpreter! 💖 that's the whole vibe. (And yeah, you're reading the urxvtperl(3) page from the RXVT-UNICODE manual, in case you needed the receipts. 🧾)

🫶 SYNOPSIS 🫶

okay so the classic move is: you drop a little file somewhere, and then you point urxvt at it. watch this:

# create a file grab_test in some directory:

sub on_sel_grab {
   warn "you selected ", $_[0]->selection;
   ()
}

# start a urxvt instance using it:

urxvt --perl-lib path/to/somedirectory -pe grab_test

that's it. that's the whole ritual. 🔥

🌸 DESCRIPTION 🌸

okay so real talk — every single time a terminal object gets created, all the extension scripts you specified via the perl resource get loaded and associated with it. like, instantly. 💫

Scripts are compiled inside a 'use strict qw(vars subs)' and 'use utf8' environment — which means, yeah, they must be encoded as UTF-8. no exceptions, no cap. 😤

And listen: each script will only ever be loaded once. even in urxvtd, where scripts will be shared (but not enabled) for all terminals. one load, shared across the whole little family. 🫶

wanna shut the embedded perl interpreter all the way off? set both perl-ext and perl-ext-common resources to the empty string. that's the off switch. 🔌

🎁 PREPACKAGED EXTENSIONS 🎁

A number of extensions are delivered with this release. you can find them chillin' in <libdir>/urxvt/perl/, and the documentation can be viewed using man urxvt-<EXTENSIONNAME>. every one's got receipts. 📚

You can activate them like this:

urxvt -pe <extensionname>

Or by adding them to the resource for extensions loaded by default:

URxvt.perl-ext-common: default,selection-autotransform

Extensions may add additional resources and "actions" — i.e., methods which can be bound to a key and invoked by the user. 👑 An extension can define the resources it supports using so called META comments, described below, iykyk. And similarly to builtin resources, extension resources can also be specified on the command line as long options (with . replaced by -), in which case the corresponding extension is loaded automatically. 🪄 For this to work the extension must define META comments for its resources — so no META comments, no magic. 💅

🧚 API DOCUMENTATION 🧚

💜 General API Considerations 💜

All objects (such as terminals, time watchers etc.) are typical reference-to-hash objects. the hash is yours — use it to store literally anything you like. 🍓 But all members starting with an underscore (such as _ptr or _hook) are reserved for internal uses and MUST NOT be accessed or modified. hands off, bestie. 🙈

When objects are destroyed on the C++ side, the perl object hashes are emptied — so it's best to store related objects such as time watchers and the like inside the terminal object, so they get destroyed as soon as the terminal is destroyed. nesting = self-cleaning, we love to see it. ✨

Argument names also often indicate the type of a parameter. here are some hints on what they mean:

  • $text — rxvt-unicode's special way of encoding text, where one "unicode" character always represents one screen cell. see ROW_t for a discussion of this format.
  • $string — a perl text string, with an emphasis on text. it can store all unicode characters, and is to be distinguished with text encoded in a specific encoding (often locale-specific) and binary data.
  • $octets — either binary data or — more common — a text string encoded in a locale-specific way.
  • $keysym — an integer that is a valid X11 keysym code. you can convert a string into a keysym and viceversa by using XStringToKeysym and XKeysymToString.

🦋 Extension Objects 🦋

Every perl extension is a perl class. 💅 A separate perl object is created for each terminal, and each terminal has its own set of extension objects, which are passed as the first parameter to hooks. so extensions can use their $self object without having to think about clashes with other extensions or other terminals — with the exception of methods and members that begin with an underscore character _: those are reserved for internal use. 🙅

Although it isn't a urxvt::term object, you can call all methods of the urxvt::term class on this object. iconic behaviour, honestly. 👑

Additional methods only supported for extension objects are described in the urxvt::extension section below. 👇

🧾 META comments 🧾

Rxvt-unicode recognises special meta comments in extensions that define different types of metadata. these comments are scanned whenever a terminal is created, and are typically used to autoload extensions when their resources or command line parameters are used. 🔍

Currently, it recognises these comments below. individual components are separated by colons (:), and should not contain colons themselves — there is also currently no escaping mechanism provided for this. so like, plan accordingly. 💀

🌈 #:META:RESOURCE:name:type:desc

The RESOURCE comment defines a resource used by the extension, where name is the resource name, type is the resource type — boolean or string — and desc is the resource description.

The extension will be autoloaded when this resource is specified or used as a command line parameter. 🪄

Example: matcher provides the matcher.launcher resource by having this comment:

#:META:RESOURCE:%.launcher:string:default launcher command

Example: load this extension when the -tr command line option or resource name is used:

#:META:RESOURCE:tr:boolean:set root pixmap as background

🌈 #:META:OSC:number:desc

The OSC comment specifies an OSC sequence, where number is the numerical OSC code and desc is a short description that is currently unused.

This will cause the extension to be autoloaded when the OSC sequence is used for the first time.

⚠️ Note that autoloading carries some extra responsibilities with it: although the terminal cannot really protect itself against malicious sources of command sequences — therefore relying on the programs running inside to sanitize data that they output — it is very common for programs to emit command sequences from untrusted sources. While this means that extensions should, as a defense-in-depth mechanism, always consider whether OSC sequences are safe, autoloading automatically exposes any autoloaded extension in all terminal windows, so extra care should be taken. 🔥

Example: the background extension registers OSC 20 like this:

#:META:OSC:20:change/query background image

🌈 #:META:OSC_PERL:prefix:desc

The same as the OSC comment, but for the Perl OSC sequence (777). the prefix should be unique among extensions, of course — most easily arranged by using the extension name, although this is not required.

Example: the overlay-osc extension registers its Perl OSC like this:

#:META:OSC_PERL:overlay:man overlay-osc

🎀 Hooks 🎀

The following subroutines can be declared in extension files, and will be called whenever the relevant event happens. 🎉

The first argument passed to them is an extension object as described in the "Extension Objects" section.

All of these hooks must return a boolean value. If any of the called hooks returns true, then the event counts as being consumed, and the relevant action might not be carried out by the C++ code. 😬

When in doubt, return a false value (preferably ()). 🫶

⭐ on_attach $term

Called when an extension package is attached to a running terminal instance. Must return true in all cases, and runs with the same limitations as on_init.

Unlike on_init or on_start, this is called when the extension is attached to a terminal, regardless of whether the extension is loaded before or after the terminal is started. Extensions that need to do something before they work can do it in this callback — as opposed to, e.g., on_init, which might not be called. 💡

⭐ on_init $term

Called after a new terminal object has been initialized, but before windows are created or the command gets run. most methods are unsafe to call or deliver senseless data, as terminal size and other characteristics have not yet been determined. you can safely query and change resources and options, though. For many purposes the on_start hook is a better place. 👍

⭐ on_start $term

Called at the very end of initialisation of a new terminal — just before trying to map (display) the toplevel and returning to the main loop. the final boss of startup, basically. 🏁

⭐ on_destroy $term

Called whenever something tries to destroy terminal, when the terminal is still fully functional (not for long, though 😭).

⭐ on_reset $term

Called after the screen is "reset" for any reason, such as resizing or control sequences. this is where you can react on changes to size-related variables. 📐

⭐ on_child_start $term, $pid

Called just after the child process has been forked. 🍴

⭐ on_child_exit $term, $status

Called just after the child process has exited. $status is the status from waitpid. 🫡

⭐ on_sel_make $term, $eventtime

Called whenever a selection has been made by the user, but before the selection text is copied — so changes to the beginning, end or type of the selection will be honored. 💖

Returning a true value aborts selection making by urxvt, in which case you have to make a selection yourself by calling $term->selection_grab. (congrats, you're the main character now 👑)

⭐ on_sel_grab $term, $eventtime

Called whenever a selection has been copied, but before the selection is requested from the server. the selection text can be queried and changed by calling $term->selection.

Returning a true value aborts selection grabbing. it will still be highlighted, though. ✨

⭐ on_sel_extend $term

Called whenever the user tries to extend the selection (e.g. with a double click) and is either supposed to return false (normal operation), or should extend the selection itself and return true to suppress the built-in processing. this can happen multiple times — as long as the callback returns true, it will be called on every further click by the user and is supposed to enlarge the selection more and more, if possible. 🖱️

See the selection example extension. 📚

⭐ on_view_change $term, $offset

Called whenever the view offset changes — i.e. the user or program scrolls. Offset 0 means display the normal terminal; positive values show this many lines of scrollback. 📜

⭐ on_scroll_back $term, $lines, $saved

Called whenever lines scroll out of the terminal area into the scrollback buffer. $lines is the number of lines scrolled out and may be larger than the scroll back buffer or the terminal.

It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, $nrow - 1) represent the lines to be scrolled out). $saved is the total number of lines that will be in the scrollback buffer. 🧮

on_osc_seq $term, $op, $args, $resp

okay so this one fires on every single OSC sequence, and it's your moment to suppress it or change how it behaves. ✨ The default vibe should be returning an empty list. If you return a true value, execution of the request gets suppressed completely — like, gone gone. Just… be careful you don't get tangled up in recursive invocations when you output an OSC sequence from inside this callback, bestie. 😭 That's a whole loop situation.

Heads up: on_osc_seq_perl should be used for new behaviour. This one's the old way, iykyk.

on_osc_seq_perl $term, $args, $resp

Called whenever the ESC ] 777 ; prefix ; string ST command sequence gets processed (OSC = operating system command, for the uninitiated 💅). The cute part? Cursor position and other state info are already up-to-date when this happens. 🎀

For interoperability, your argument should start with the extension name (sans -osc) or some other suitable prefix, plus a semicolon, so it doesn't get confused with commands meant for other extensions. Like, stay in your lane bestie.

For example, overlay-osc uses this:

sub on_osc_seq_perl {
   my ($self, $osc, $resp) = @_;

   return unless $osc =~ s/^overlay;//;

   ... process remaining $osc string
}
🔥 Security moment, no cap: be careful to never trust the data you receive in a security sense — its source can't easily be controlled (e-mail content, messages from other users on the same system, etc.). Like, don't let strangers into the group chat.

For responses, $resp contains the end-of-args separator used by the sender. 🫶

on_add_lines $term, $string

Called whenever text is about to be output, with the text as the argument. You can filter/change it and output the text yourself by returning a true value and calling $term->scr_add_lines yourself. 💖

⚠️ But please note this might be very slow, because your hook gets called for all the text being output. Every single bit. 😭

on_tt_write $term, $octets

Called whenever some data is written to the tty/pty. Use it to suppress or filter tty input. Clean and simple, we love her. ✨

on_tt_paste $term, $octets

Called whenever text is about to be pasted, with the text as the argument. You can filter/change it and paste the text yourself by returning a true value and calling $term->tt_paste yourself. 🎀 Note that $octets is locale-encoded — keep that in mind!

on_line_update $term, $row

Called whenever a line was updated or changed. Perfect for filtering screen output (e.g. underlining urls or other useless stuff 👀). Only lines that are actually being shown get filtered, and — for performance reasons — not always immediately.

The row number is always the topmost row of the line if the line spans multiple rows.

🚨 Real talk: if you change the line, the hook might get called later with the already-modified line (like, if unrelated parts change), so you can't just toggle rendition bits — you can only set them. No take-backsies.

on_refresh_begin $term

Called just before the screen gets redrawn. Slay for overlay or similar effects — modify the terminal contents in refresh_begin and restore them in refresh_end. 🦋

Note: the built-in overlay and selection display code runs after this hook, and takes precedence. So it's giving main character energy and will absolutely steal your spotlight.

on_refresh_end $term

Called just after the screen gets redrawn. See on_refresh_begin above — they're a matching set, periodt. 💅

on_action $term, $string

Called whenever an action is invoked for the corresponding extension (e.g. via an extension:string builtin action bound to a key — see the description of the keysym resource in the urxvt(1) manpage). The event is simply the action string. Note that an action event is always associated to a single extension. 🌸

on_user_command $term, $string DEPRECATED

Called whenever a user-configured event is being activated (e.g. via a perl:string action bound to a key — see the description of the keysym resource in the urxvt(1) manpage). The event is simply the action string.

💀 This interface is going away in preference to the on_action hook. She's retiring, let her go gracefully.

on_resize_all_windows $term, $new_width, $new_height

Called just after the new window size has been calculated, but before windows are actually being resized or hints are being set. If this hook returns a true value, setting of the window hints gets skipped. 🪟✨

on_x_event $term, $event

Called on every X event received on the vt window (and possibly other windows). Should only be used as a last resort — most event structure members are not passed. 🙈

on_root_event $term, $event

Like on_x_event, but it's called for events on the root window. 🌈

on_focus_in $term

Called whenever the window gets the keyboard focus, before rxvt-unicode does focus in processing. 👑

on_focus_out $term

Called whenever the window loses keyboard focus, before rxvt-unicode does focus out processing. 🥲

on_configure_notify $term, $event

on_property_notify $term, $event

on_key_press $term, $event, $keysym, $octets

on_key_release $term, $event, $keysym

on_button_press $term, $event

on_button_release $term, $event

on_motion_notify $term, $event

on_map_notify $term, $event

on_unmap_notify $term, $event

Called whenever the corresponding X event is received for the terminal. If the hook returns true, then the event gets ignored by rxvt-unicode. ✨

The $event is a hash with most values as named by Xlib (see the XEvent manpage), with the additional members row and col, which are the (real, not screen-based) row and column under the mouse cursor. 🖱️💖

on_key_press additionally receives the string rxvt-unicode would output, if any, in locale-specific encoding.

on_client_message $term, $event

on_wm_protocols $term, $event

on_wm_delete_window $term, $event

Called when various types of ClientMessage events are received (all with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).

on_bell $term

Called on receipt of a bell character. 🔔 Ding ding, bestie.

🫶 Variables in the urxvt Package

$urxvt::LIBDIR

The rxvt-unicode library directory, where — among other things — the perl modules and scripts are stored. 📁

$urxvt::RESCLASS, $urxvt::RESCLASS

The resource class and name rxvt-unicode uses to look up X resources.

$urxvt::RXVTNAME

The basename of the installed binaries, usually urxvt. 🎀

$urxvt::TERM

The current terminal. This variable stores the current urxvt::term object whenever a callback/hook is executing. Like a little "you are here" map. 👑

@urxvt::TERM_INIT

All code references in this array get called as methods of the next newly created urxvt::term object (during the on_init phase). The array gets cleared before the code references that were in it are being executed, so references can push themselves onto it again if they so desire. ✨

This complements the perl-eval command line option, but it gets executed first.

@urxvt::TERM_EXT

Works similar to @TERM_INIT, but contains perl package/class names, which get registered as normal extensions after calling the hooks in @TERM_INIT but before other extensions. Gets cleared just like @TERM_INIT. 🌸

💜 Functions in the urxvt Package

urxvt::fatal $errormessage

Fatally aborts execution with the given error message (which should include a trailing newline — don't forget it!).

🚨 Avoid at all costs! The only time this is acceptable (and useful) is in the init hook, where it prevents the terminal from starting up. That's it. That's the one use case. Fr fr.

urxvt::warn $string

Calls rxvt_warn with the given string, which should include a trailing newline. The module also overwrites the warn builtin with a function that calls this function. 😌

Using this function has the advantage that its output ends up in the correct place, e.g. on stderr of the connecting urxvtc client. 🎯

Messages have a size limit of 1023 bytes currently. Keep it snappy, bestie.

@terms = urxvt::termlist

Returns all urxvt::term objects that exist in this process — regardless of whether they are started, being destroyed, etc., so be careful. 👀 Only term objects that have perl extensions attached will be returned (because there is no urxvt::term object associated with the others).

$time = urxvt::NOW

Returns the "current time" (as per the event loop). ⏰

X constants ✨

urxvt::CurrentTime

urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, AnyModifier

urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask

urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose, GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify, UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify, ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, SelectionNotify, ColormapNotify, ClientMessage, MappingNotify

Various constants for use in X calls and event processing. 🦋

DEC private mode constants 💅

urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo, PrivMode_relOrigin, PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP, PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys, PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11, PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress, PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent, PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8, PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report, PrivMode_Default

Constants for checking DEC private modes. 👑

🎨 RENDITION

Rendition bitsets contain information about colour, font, font styles and similar information for each screen cell. 🖌️✨

⚠️ The following "macros" deal with changes in rendition sets. You should never just create a bitset — you should always modify an existing one, as they contain important information required for correct operation of rxvt-unicode. Like, do not cook from scratch here, bestie. Fr fr.

$rend = urxvt::DEFAULT_RSTYLE

Returns the default rendition, as used when the terminal is starting up or being reset. Useful as a base to start from when creating renditions. 🎀

$rend = urxvt::OVERLAY_RSTYLE

Returns the rendition mask used for overlays by default. 🌈

  • $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink, urxvt::RS_RVid, urxvt::RS_Uline — hands you the bit that turns on bold, italic, blink, reverse-video and underline respectively 💅 and to actually enable one of those styles you just logically OR it into the bitset. slay.
  • $foreground = urxvt::GET_BASEFG $rend and $background = urxvt::GET_BASEBG $rend — grab the foreground / background colour index respectively, no cap.
  • $rend = urxvt::SET_FGCOLOR $rend, $new_colour — swap the foreground colour in the rendition mask for the one you picked.
  • $rend = urxvt::SET_BGCOLOR $rend, $new_colour — same vibe, but for the background colour.
  • $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg — do both at once, foreground and background, in a single glow-up ✨
  • $value = urxvt::GET_CUSTOM $rend — returns the "custom" value. so every single rendition has 5 bits reserved just for extensions 🎀 you can set them and change them however you want, and they start out at zero.
  • $rend = urxvt::SET_CUSTOM $rend, $new_value — change that custom value. go off.

💖 The urxvt::term::extension class

okay so every extension that gets attached to a terminal object is represented by a urxvt::term::extension object. icon behavior.

you can absolutely use these objects — they get passed to all the callbacks — to stash any state related to the terminal and the extension instance 🫶

the methods (and data members!!) documented down below can be called on extension objects, on top of the methods documented for the <urxvt::term> class. two-for-one.

  • $urxvt_term = $self->{term} — returns the urxvt::term object associated with this instance of the extension. ⚠️ this member must not be changed in any way — hands off bestie, it's load-bearing.
  • $self->enable ($hook_name => $cb[, $hook_name => $cb..]) — dynamically enables the given hooks (named without the on_ prefix) for this extension, replacing any hook previously installed via enable in this extension. so useful when you wanna overwrite time-critical hooks only temporarily 👑
  • $self->disable ($hook_name[, $hook_name..]) — dynamically disables the given hooks. bye felicia.
  • $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..]) — same energy as enable, except it adds callbacks for the given hook(s) instead of replacing what's already there, and it returns a guard object. when that guard object gets destroyed, the callbacks get disabled again 🦋 very set-it-and-forget-it of it.
  • $self->bind_action ($hotkey, $action), $self->x_resource ($pattern), $self->x_resource_boolean ($pattern) — these all support an extra "%" prefix for $action or $pattern when you call them on an extension object, compared to the urxvt::term methods of the same name 🌸 head to the description of those methods in the urxvt::term class for the deets.

🧚 The urxvt::anyevent Class

the whole entire purpose of this class is to serve up an interface to the AnyEvent module — meaning any module that uses it will just work inside urxvt with no further programming required 😌 the only exception is that you cannot wait on condition variables, but non-blocking condvar use is totally fine.

in practical terms that means you can't use blocking APIs, but the non-blocking variant should work. simple as.

👑 The urxvt::term Class

  • $term = new urxvt::term $envhashref, $rxvtname, [arg...] — creates a brand-new terminal, basically identical to if you'd started it with "$rxvtname, arg...". $envhashref must be a reference to a %ENV-like hash that defines the environment of the new terminal.

it croaks (and probably prints an error message) if the new instance couldn't be created 😭 and it returns undef if the new instance didn't initialise perl, otherwise you get the terminal object. the init and start hooks will be called before this call returns, and they're free to refer to global data (which is race free). iconic.

  • $term->destroy — destroys the terminal object (closes the window, frees resources, all that). ⚠️ but please note: urxvt will not exit as long as any event watchers (timers, io watchers) are still active. so like, clean those up too bestie.
  • $term->exec_async ($cmd[, @args]) — works like a combo of the fork/exec builtins, i.e. it executes ("starts") programs in the background. this function takes care of setting the user environment before exec'ing the command (like PATH) and honestly you should prefer it over explicitly calling exec or system 💅

it also sets the URXVT_EXT_WINDOWID environment variable to the window ID of the terminal ($self->parent), similar to the WINDOWID variable that gets set for the process spawned inside the terminal.

returns the pid of the subprocess, or undef on error.

  • $isset = $term->option ($optval[, $set]) — returns true if the option specified by $optval is enabled, and optionally changes it. all option values are stored by name in the hash %urxvt::OPTION 🎀 options that aren't enabled in this binary just aren't in the hash, sorry not sorry.

here's a likely non-exhaustive list of option names — see the source file /src/optinc.h for the actual list:

 borderLess buffered console cursorBlink cursorUnderline hold iconic
 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
 urgentOnBell utmpInhibit visualBell disablePasteBrackets
  • $value = $term->resource ($name[, $newval]) — returns the current resource value for a given name, and optionally sets a new value. setting values is most useful in the init hook ✨ unset resources are returned and accepted as undef.

the new value must be properly encoded to a suitable character encoding before you pass it to this method. same deal on the way out — the returned value may need converting from the used encoding to text.

resource names are as defined in src/rsinc.h. colours can be specified as resource names of the form "color+<index>", e.g. "color+5". (will likely change).

🚨 heads up: resource strings will currently only be freed when the terminal is destroyed, so changing options frequently will eat memory. fr fr, mind that.

here's a likely non-exhaustive list of resource names, not all of which are supported in every build — see the source file /src/rsinc.h for the actual list:

  answerbackstring backgroundPixmap backspace_key blurradius
  boldFont boldItalicFont borderLess buffered chdir color cursorBlink
  cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
  fade font geometry hold iconName iconfile imFont imLocale inputMethod
  insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
  jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
  mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
  perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
  preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
  scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
  scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
  secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
  term_name title transient_for transparent tripleclickwords urgentOnBell
  utmpInhibit visualBell rewrapMode disablePasteBrackets
  • $value = $term->x_resource ($pattern) — returns the X-Resource for the given pattern, excluding the program or class name. so like "$term->x_resource ("boldFont")" should return the same value that this instance of rxvt-unicode actually used 🦋 returns undef if no resource with that pattern exists.

extensions that define extra resources also need to call this method to get at their values, iykyk.

if you call the method on an extension object (basically, from inside an extension), then the special prefix "%." gets replaced by the name of the extension plus a dot, and a lone string "%" gets replaced by the extension name itself 💖 this is what makes it possible to write extensions so you can rename them and get a whole new set of resources without touching the actual code. obsessed.

⭐ this method should only be called during the on_start hook, because there's only one resource database per display, and later invocations might hand you the wrong resources.
  • $value = $term->x_resource_boolean ($pattern) — like x_resource above, but it interprets the string value as a boolean and returns 1 for true values, 0 for false values, and undef if the resource or option isn't specified. you should always use this method to parse boolean resources 🎀 no exceptions.
  • $action = $term->lookup_keysym ($keysym, $state) — returns the action bound to the key combination "($keysym, $state)" if a binding for it exists, and undef otherwise.
  • $success = $term->bind_action ($key, $action) — adds a key binding exactly as specified via a keysym resource. check the keysym resource in the urxvt(1) manpage for that ✨

to add default bindings for actions, an extension should call ->bind_action in its init hook for every such binding. doing it in the init hook means users can override or remove the binding again later — very considerate of them 💅

example: the searchable-scrollback by default binds itself on Meta-s, using $self->bind_action, which calls $term->bind_action:

sub init {
   my ($self) = @_;

   $self->bind_action ("M-s" => "%:start");
}
  • $rend = $term->rstyle ([$new_rstyle]) — returns and optionally changes the current rendition. text output by the terminal application will use this style. main character energy for your text.
  • ($row, $col) = $term->screen_cur ([$row, $col]) — returns the current coordinates of the text cursor position, and optionally sets it. ⚠️ setting it is usually a bad idea because applications don't expect that — you'll freak them out.
  • ($row, $col) = $term->selection_mark ([$row, $col]) — returns the current value of the selection mark position.
  • ($row, $col) = $term->selection_beg ([$row, $col]) — same thing but for the selection begin position.
  • ($row, $col) = $term->selection_end ([$row, $col]) — and this one's the selection end position.

when arguments are given to any of these three, the selection coordinates get set to $row and $col, and the selection screen gets set to the current screen 🫶

  • $screen = $term->selection_screen ([$screen]) — returns the current selection screen, and then optionally sets it.
  • $term->selection_make ($eventtime[, $rectangular]) — tries to make a selection as set by selection_beg and selection_end. if $rectangular is true (default: false), a rectangular selection gets made 🎀 this is the preferred function for making a selection, so use this one bestie, not the others.
  • $success = $term->selection_grab ($eventtime[, $clipboard]) — okay so this one tries to snag ownership of the primary selection from the server (or the clipboard instead, if $clipboard is true 💖). The actual text gets set with the next method. Heads up: no visual feedback whatsoever, so don't go looking for a cute highlight, it's not coming. This is mostly useful from inside on_sel_grab hooks.
  • $oldtext = $term->selection ([$newtext, $clipboard]) — returns the current selection text (clipboard if $clipboard is true, you know the drill) and, if you feel like it, swaps it out for $newtext ✨.
  • $term->selection_clear ([$clipboard]) — revokes ownership of the primary selection (or the clipboard if $clipboard is true). Bye bestie 👋.
  • $term->overlay_simple ($x, $y, $text) — makes a simple multi-line overlay box. See the next method for the deets.
  • $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) — creates a brand new (empty!) overlay at the position you give it, with the width/height you give it. $rstyle sets the initial rendition style (default: "OVERLAY_RSTYLE").

If $border is 2 (that's the default), a decorative border goes around the box 🎀.

If either $x or $y is negative, it gets counted from the right/bottom side respectively — iconique.

This method returns an urxvt::overlay object. The overlay stays visible for as long as the perl object is referenced (so like, keep a reference, bestie).

The methods currently supported on urxvt::overlay objects are:

  • $overlay->set ($x, $y, $text[, $rend]) — similar to $term->ROW_t and $term->ROW_r in that it puts text in rxvt-unicode's special encoding plus an array of rendition values at a specific position inside the overlay.

If $rend is missing, the rendition will not be changed.

  • $overlay->hide — if it's visible, hide the overlay, but don't destroy it.
  • $overlay->show — if it's hidden, display the overlay again 🌸.
  • $popup = $term->popup ($event) — creates a new urxvt::popup object that implements a popup menu. The $event must be the event causing the menu to pop up (a button event, currently).
  • $cellwidth = $term->strwidth ($string) — returns the number of screen-cells this string would need. Correctly accounts for wide and combining characters, no cap 💅.
  • $octets = $term->locale_encode ($string) — converts the given text string into the corresponding locale encoding. Returns undef if $string is undef.
  • $string = $term->locale_decode ($octets) — converts the given locale-encoded octets into a perl string. Returns undef if $octets is undef.
  • $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) — XORs the rendition values in the given span with the provided value (default: RS_RVid), which MUST NOT contain font styles. Useful in refresh hooks to pull off effects similar to the selection ✨.
  • $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]]) — similar to scr_xor_span, but xors a rectangle instead. Trailing whitespace also gets xored with $rstyle2, which defaults to RS_RVid | RS_Uline — that removes reverse video again and underlines it instead. Both styles MUST NOT contain font styles.
  • $term->scr_bell — Ring the bell! 🔔 That's it. That's the whole thing.
  • $term->scr_add_lines ($string) — writes the given text string to the screen, as if the app running inside the terminal output it. It may not contain command sequences (escape codes — see cmd_parse for that), but it's free to use line feeds, carriage returns and tabs. The string is a normal text string, not in locale-dependent encoding.

Normally it's not a good idea to use this function, because programs might get confused by changes in cursor position or scrolling 🙈. It is useful inside an on_add_lines hook, though.

  • $term->scr_change_screen ($screen) — switches to the given screen: 0 primary, 1 secondary.
  • $term->cmd_parse ($octets) — like scr_add_lines, but the argument must be in the locale-specific encoding of the terminal and it can contain command sequences (escape codes) that will be interpreted 🦋.
  • $term->tt_write ($octets) — writes the octets given in $octets to the tty (i.e. as user input to the program — see cmd_parse for the opposite direction). If you want to pass characters instead of octets, convert your strings first to the locale-specific encoding using $term->locale_encode.
  • $term->tt_write_user_input ($octets) — like tt_write, but this one should be used when writing strings in response to the user pressing a key, so the additional actions requested by the user for that case actually get invoked (tt_write doesn't do that 💀). The typical use case is inside on_action hooks.
  • $term->tt_paste ($octets) — writes the octets given in $octets to the tty as a paste, converting NL to CR and bracketing the data with control sequences if bracketed paste mode is set 🎀.
  • $old_events = $term->pty_ev_events ([$new_events]) — replaces the event mask of the pty watcher with the given event mask. Can be used to suppress input and output handling to the pty/tty. See the description of urxvt::timer->events. Make sure to always restore the previous value, okay? No leaving it broken 😭.
  • $fd = $term->pty_fd — returns the master file descriptor for the pty in use, or -1 if no pty is used.
  • $windowid = $term->parent — returns the window id of the toplevel window.
  • $windowid = $term->vt — returns the window id of the terminal window.
  • $term->vt_emask_add ($x_event_mask) — adds the specified events to the vt event mask. Useful e.g. when you want to receive pointer events all the times:
$term->vt_emask_add (urxvt::PointerMotionMask);
  • $term->set_urgency ($set) — enable/disable the urgency hint on the toplevel window.
  • $term->focus_in
  • $term->focus_out
  • $term->key_press ($state, $keycode[, $time])
  • $term->key_release ($state, $keycode[, $time]) — delivers various fake events to the terminal 🫶.
  • $window_width = $term->width ([$new_value])
  • $window_height = $term->height ([$new_value])
  • $font_width = $term->fwidth ([$new_value])
  • $font_height = $term->fheight ([$new_value])
  • $font_ascent = $term->fbase ([$new_value])
  • $terminal_rows = $term->nrow ([$new_value])
  • $terminal_columns = $term->ncol ([$new_value])
  • $has_focus = $term->focus ([$new_value])
  • $is_mapped = $term->mapped ([$new_value])
  • $max_scrollback = $term->saveLines ([$new_value])
  • $nrow_plus_saveLines = $term->total_rows ([$new_value])
  • $topmost_scrollback_row = $term->top_row ([$new_value]) — all of these return various integers describing terminal characteristics. And if you pass an argument, it changes the value and returns the previous one. Sneaky but slay 🔥.
  • $x_display = $term->display_id — returns the DISPLAY used by rxvt-unicode.
  • $lc_ctype = $term->locale — returns the LC_CTYPE category string used by this rxvt-unicode.
  • $env = $term->env — returns a copy of the environment in effect for the terminal as a hashref, similar to \%ENV.
  • @envv = $term->envv — returns the environment as an array of strings of the form VAR=VALUE.
  • @argv = $term->argv — returns the argument vector as this terminal, similar to @ARGV, but it includes the program name as the first element 💜.
  • $modifiermask = $term->ModLevel3Mask
  • $modifiermask = $term->ModMetaMask
  • $modifiermask = $term->ModNumLockMask — these return the modifier masks corresponding to the "ISO Level 3 Shift" (often AltGr), the meta key (often Alt) and the num lock key, if applicable.
  • $screen = $term->current_screen — returns the currently displayed screen (0 primary, 1 secondary).
  • $cursor_is_hidden = $term->hidden_cursor — tells you whether the cursor is currently hidden or not. Peekaboo 🙈.
  • $priv_modes = $term->priv_modes — returns a bitset with the state of DEC private modes.

Example:

if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
    # mouse reporting is turned on
}
  • $view_start = $term->view_start ([$newvalue]) — returns the row number of the topmost displayed line, and changes it if an argument is given. Values greater than or equal to 0 display the terminal contents. Lower values scroll this many lines into the scrollback buffer 🌈.
  • $term->want_refresh — requests a screen refresh. At the next opportunity, rxvt-unicode will compare the on-screen display with its stored representation, and if they differ, it redraws the differences. Use this after changing terminal contents so they actually show up, bestie ✨.
  • $term->refresh_check — checks if a refresh has been requested and, if so, schedules one.
  • $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) — returns the text of the entire row with number $row_number. Row $term->top_row is the topmost terminal line, row $term->nrow-1 is the bottommost terminal line. Nothing gets returned if you ask for a nonexistent line (fair enough 💅).

If $new_text is specified, it replaces characters in the current line, starting at column $start_col (default 0), which is super useful when you only wanna replace parts of a line. The font index in the rendition will automatically be updated.

$text is in a special encoding: tabs and wide characters that use more than one cell when displayed are padded with $urxvt::NOCHAR (chr 65535) characters. Characters with combining characters, and other characters that don't fit into the normal text encoding, get replaced with characters in the private use area 🦋.

You have to obey this encoding when changing text. The upside is that substr and similar functions then work on screen cells and not on characters — which is genuinely iconic.

The methods $term->special_encode and $term->special_decode can be used to convert normal strings into this encoding and vice versa.

  • $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]]) — like $term->ROW_t, but returns an arrayref with rendition bitsets. Rendition bitsets contain information about colour, font, font styles and similar info. See also $term->ROW_t.

When setting rendition, the font mask will be ignored 🙈.

See the section on RENDITION, above.

  • $length = $term->ROW_l ($row_number[, $new_length]) — returns the number of screen cells that are in use ("the line length"). Unlike the urxvt core, this returns $term->ncol if the line is joined with the following one. Note the difference, okay? That's the whole point 💀.
  • $bool = $term->is_longer ($row_number) — returns true if the row is part of a multiple-row logical "line" (i.e. joined with the following row), which means all characters are in use and it's continued on the next row (and possibly a continuation of the previous row(s)) 🧚.

$line = $term->line ($row_number) — ok bestie, this creates and returns a brand-new urxvt::line object that stores info about the logical line that row $row_number is part of. It’s giving line-detective energy 🔍 and it supports these methods:

  • $text = $line->t ([$new_text]) — returns or replaces the full text of the line, similar to ROW_t.
  • $rend = $line->r ([$new_rend]) — returns or replaces the full rendition array of the line, similar to ROW_r.
  • $length = $line->l — returns the length of the line in cells, similar to ROW_l.
  • $rownum = $line->beg
  • $rownum = $line->end — these two return the row number of the first/last row of the line, respectively.
  • $offset = $line->offset_of ($row, $col) — returns the character offset of the given row|col pair within the logical line. Works for rows outside the line too, and returns corresponding offsets outside the string.
  • ($row, $col) = $line->coord_of ($offset) — translates a string offset back into terminal coordinates again.

$text = $term->special_encode ($string) — converts a perl string into the special encoding used by rxvt-unicode, where one character corresponds to one screen cell. See $term->ROW_t for details.

$string = $term->special_decode ($text) — converts rxvt-unicode’s text representation back into a perl string. See $term->ROW_t for details.

$success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) — registers/unregisters a synchronous button grab. See the XGrabButton manpage.

$success = $term->grab ($eventtime[, $sync]) — calls XGrabPointer and XGrabKeyboard in asynchronous mode (the default) or synchronous mode ($sync is true). Also remembers the grab timestamp.

$term->allow_events_async — calls XAllowEvents with AsyncBoth for the most recent grab.

$term->allow_events_sync — calls XAllowEvents with SyncBoth for the most recent grab.

$term->allow_events_replay — calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most recent grab.

$term->ungrab — calls XUngrabPointer and XUngrabKeyboard for the most recent grab. It’s called automatically on evaluation errors, because losing the grab in the error case is better than losing the whole session 💀.

$atom = $term->XInternAtom ($atom_name[, $only_if_exists])
$atom_name = $term->XGetAtomName ($atom)
@atoms = $term->XListProperties ($window)
($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
$term->XChangeProperty ($window, $property, $type, $format, $octets)
$term->XDeleteProperty ($window, $property)
$window = $term->DefaultRootWindow
$term->XReparentWindow ($window, $parent, [$x, $y])
$term->XMapWindow ($window)
$term->XUnmapWindow ($window)
$term->XMoveResizeWindow ($window, $x, $y, $width, $height)
($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
$term->XChangeInput ($window, $add_events[, $del_events])
$keysym = $term->XStringToKeysym ($string)
$string = $term->XKeysymToString ($keysym)

Various X or X-related functions. The $term object only serves as the source of the display — otherwise those functions map more-or-less directly onto the X functions of the same name.

🎀 The urxvt::popup Class 🎀

$popup->add_title ($title) — adds a non-clickable title to the popup. Very demure, very mindful ✨.

$popup->add_separator ([$sepchr]) — creates a separator, optionally using the character given as $sepchr.

$popup->add_button ($text, $cb) — adds a clickable button to the popup. $cb is called whenever it is selected.

$popup->add_toggle ($text, $initial_value, $cb) — adds a toggle/checkbox item to the popup. The callback gets called whenever it gets toggled, with a boolean indicating its new value as its first argument.

$popup->show — displays the popup (which is initially hidden).

⏰ The urxvt::timer Class ⏰

This class implements timer watchers/events. Time is represented as a fractional number of seconds since the epoch. Example:

$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
$term->{timer} = urxvt::timer
                 ->new
                 ->interval (1)
                 ->cb (sub {
                    $term->{overlay}->set (0, 0,
                       sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
                 });

$timer = new urxvt::timer — create a new timer object in started state. It is scheduled to fire immediately.

$timer = $timer->cb (sub { my ($timer) = @_; ... }) — set the callback to be called when the timer triggers.

$timer = $timer->set ($tstamp[, $interval]) — set the time the event is generated to $tstamp (and optionally specifies a new $interval).

$timer = $timer->interval ($interval) — by default (and when $interval is 0), the timer will automatically stop after it has fired once. If $interval is non-zero, then the timer is automatically rescheduled at the given intervals.

$timer = $timer->start — start the timer.

$timer = $timer->start ($tstamp[, $interval]) — set the event trigger time to $tstamp and start the timer. Optionally also replaces the interval.

$timer = $timer->after ($delay[, $interval]) — like start, but sets the expiry timer to urxvt::NOW + $delay.

$timer = $timer->stop — stop the timer.

🦋 The urxvt::iow Class 🦋

This class implements io watchers/events. Example:

$term->{socket} = ...
$term->{iow} = urxvt::iow
               ->new
               ->fd (fileno $term->{socket})
               ->events (urxvt::EV_READ)
               ->start
               ->cb (sub {
                 my ($iow, $revents) = @_;
                 # $revents must be 1 here, no need to check
                 sysread $term->{socket}, my $buf, 8192
                    or end-of-file;
               });

$iow = new urxvt::iow — create a new io watcher object in stopped state.

$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) — set the callback to be called when io events are triggered. $reventmask is a bitset as described in the events method.

$iow = $iow->fd ($fd) — set the file descriptor (not handle) to watch.

$iow = $iow->events ($eventmask) — set the event mask to watch. The only allowed values are urxvt::EV_READ and urxvt::EV_WRITE, which might be ORed together, or urxvt::EV_NONE.

$iow = $iow->start — start watching for requested events on the given handle.

$iow = $iow->stop — stop watching for events on the given file handle.

🌸 The urxvt::iw Class 🌸

This class implements idle watchers, that get called automatically when the process is idle. They should return as fast as possible, after doing some useful work.

$iw = new urxvt::iw — create a new idle watcher object in stopped state.

$iw = $iw->cb (sub { my ($iw) = @_; ... }) — set the callback to be called when the watcher triggers.

$timer = $timer->start — start the watcher. (Yep, the page literally says $timer here — we don’t make the rules 😭.)

$timer = $timer->stop — stop the watcher. (Again with the $timer, iconic copy-paste energy 💀.)

👑 The urxvt::pw Class 👑

This class implements process watchers. They create an event whenever a process exits, after which they stop automatically.

my $pid = fork;
...
$term->{pw} = urxvt::pw
                 ->new
                 ->start ($pid)
                 ->cb (sub {
                    my ($pw, $exit_status) = @_;
                    ...
                 });

$pw = new urxvt::pw — create a new process watcher in stopped state.

$pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... }) — set the callback to be called when the timer triggers.

$pw = $timer->start ($pid) — tells the watcher to start watching for process $pid.

$pw = $pw->stop — stop the watcher.

🌱 ENVIRONMENT 🌱

URXVT_PERL_VERBOSITY

This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output.

  • == 0 — fatal messages only
  • >= 2 — general warnings (default level)
  • >= 3 — script loading and management
  • >=10 — all called hooks
  • >=11 — hook return values

💖 AUTHOR 💖

Marc Lehmann <schmorp@schmorp.de> http://software.schmorp.de/pkg/rxvt-unicode

That’s the whole vibe from urxvtperl(3) — version 9.31, dated 2023-12-02. Go forth and slay your terminal extensions, bestie 🫶💅✨

📦 where this page comes from