1urxvtperl(3)                     RXVT-UNICODE                     urxvtperl(3)
2
3
4

NAME

6       urxvtperl - rxvt-unicode's embedded perl interpreter
7

SYNOPSIS

9          # create a file grab_test in some directory:
10
11          sub on_sel_grab {
12             warn "you selected ", $_[0]->selection;
13             ()
14          }
15
16          # start a urxvt instance using it:
17
18          urxvt --perl-lib path/to/somedirectory -pe grab_test
19

DESCRIPTION

21       Every time a terminal object gets created, extension scripts specified
22       via the "perl" resource are loaded and associated with it.
23
24       Scripts are compiled in a 'use strict qw(vars subs)' and 'use utf8'
25       environment, and thus must be encoded as UTF-8.
26
27       Each script will only ever be loaded once, even in urxvtd, where
28       scripts will be shared (but not enabled) for all terminals.
29
30       You can disable the embedded perl interpreter by setting both "perl-
31       ext" and "perl-ext-common" resources to the empty string.
32

PREPACKAGED EXTENSIONS

34       A number of extensions are delivered with this release. You can find
35       them in <libdir>/urxvt/perl/, and the documentation can be viewed using
36       man urxvt-<EXTENSIONNAME>.
37
38       You can activate them like this:
39
40         urxvt -pe <extensionname>
41
42       Or by adding them to the resource for extensions loaded by default:
43
44         URxvt.perl-ext-common: default,selection-autotransform
45
46       Extensions may add additional resources and "actions", i.e., methods
47       which can be bound to a key and invoked by the user. An extension can
48       define the resources it support using so called META comments,
49       described below. Similarly to builtin resources, extension resources
50       can also be specified on the command line as long options (with "."
51       replaced by "-"), in which case the corresponding extension is loaded
52       automatically. For this to work the extension must define META comments
53       for its resources.
54

API DOCUMENTATION

56   General API Considerations
57       All objects (such as terminals, time watchers etc.) are typical
58       reference-to-hash objects. The hash can be used to store anything you
59       like. All members starting with an underscore (such as "_ptr" or
60       "_hook") are reserved for internal uses and MUST NOT be accessed or
61       modified).
62
63       When objects are destroyed on the C++ side, the perl object hashes are
64       emptied, so its best to store related objects such as time watchers and
65       the like inside the terminal object so they get destroyed as soon as
66       the terminal is destroyed.
67
68       Argument names also often indicate the type of a parameter. Here are
69       some hints on what they mean:
70
71       $text
72           Rxvt-unicode's special way of encoding text, where one "unicode"
73           character always represents one screen cell. See ROW_t for a
74           discussion of this format.
75
76       $string
77           A perl text string, with an emphasis on text. It can store all
78           unicode characters and is to be distinguished with text encoded in
79           a specific encoding (often locale-specific) and binary data.
80
81       $octets
82           Either binary data or - more common - a text string encoded in a
83           locale-specific way.
84
85       $keysym
86           an integer that is a valid X11 keysym code. You can convert a
87           string into a keysym and viceversa by using "XStringToKeysym" and
88           "XKeysymToString".
89
90   Extension Objects
91       Every perl extension is a perl class. A separate perl object is created
92       for each terminal, and each terminal has its own set of extension
93       objects, which are passed as the first parameter to hooks. So
94       extensions can use their $self object without having to think about
95       clashes with other extensions or other terminals, with the exception of
96       methods and members that begin with an underscore character "_": these
97       are reserved for internal use.
98
99       Although it isn't a "urxvt::term" object, you can call all methods of
100       the "urxvt::term" class on this object.
101
102       Additional methods only supported for extension objects are described
103       in the "urxvt::extension" section below.
104
105   META comments
106       Rxvt-unicode recognizes special meta comments in extensions that define
107       different types of metadata. These comments are scanned whenever a
108       terminal is created and are typically used to autoload extensions when
109       their resources or command line parameters are used.
110
111       Currently, it recognises these comments below. Individual components
112       are separated by colons (":"), and should not contain colons themselves
113       - there is also currently no escaping mechanism provided for this.
114
115       #:META:RESOURCE:name:type:desc
116           The RESOURCE comment defines a resource used by the extension,
117           where "name" is the resource name, "type" is the resource type,
118           "boolean" or "string", and "desc" is the resource description.
119
120           The extension will be autoloaded when this resource is specified or
121           used as a command line parameter.
122
123           Example: matcher provides the "matcher.launcher" resource by having
124           this comment:
125
126              #:META:RESOURCE:%.launcher:string:default launcher command
127
128           Example: load this extension when the "-tr" command line option or
129           resource name is used.
130
131              #:META:RESOURCE:tr:boolean:set root pixmap as background
132
133       #:META:OSC:number:desc
134           The OSC comment specifies an OSC sequence, where "number" is the
135           numerical OSC code and "desc" is a short description that is
136           currently unused.
137
138           This will cause the extension to be autoloaded when the OSC
139           sequence is used for the first time.
140
141           Note that autoloading carries some extra responsibilities with it:
142           although the terminal cannot really protect itself against
143           malicious sources of command sequences, therefore relying on the
144           programs running inside to sanitize data that they output, it is
145           very common for programs to emit command sequences from untrusted
146           sources.
147
148           While this means that extensions should, as a defense-in-depth
149           mechanism, always consider whether OSC sequences are safe,
150           autoloading automatically exposes any autoloaded extension in all
151           terminal windows, so extra care should be taken.
152
153           Example: the background extension registers OSC 20 like this:
154
155              #:META:OSC:20:change/query background image
156
157       #:META:OSC_PERL:prefix:desc
158           The same as the OSC comment, but for the Perl OSC sequence (777).
159           The "prefix" should be unique among extensions, of course, which is
160           most easily arranged by using the extension name, although this is
161           not required.
162
163           Example: the overlay-osc extension registers its Perl OSC like
164           this:
165
166              #:META:OSC_PERL:overlay:man overlay-osc
167
168   Hooks
169       The following subroutines can be declared in extension files, and will
170       be called whenever the relevant event happens.
171
172       The first argument passed to them is an extension object as described
173       in the in the "Extension Objects" section.
174
175       All of these hooks must return a boolean value. If any of the called
176       hooks returns true, then the event counts as being consumed, and the
177       relevant action might not be carried out by the C++ code.
178
179       When in doubt, return a false value (preferably "()").
180
181       on_attach $term
182           Called when an extension package is attached to a running terminal
183           instance. Must return true in all cases, and runs with the same
184           limitations as "on_init".
185
186           Unlike "on_init" or "on_start", this is called when the extension
187           is attached to a terminal, regardless of whether the extension is
188           loaded before or after the terminal is started. Extensions that
189           need to do something before they work can do it in this callback,
190           as opposed to e.g.  "on_init", which might not be called.
191
192       on_init $term
193           Called after a new terminal object has been initialized, but before
194           windows are created or the command gets run. Most methods are
195           unsafe to call or deliver senseless data, as terminal size and
196           other characteristics have not yet been determined. You can safely
197           query and change resources and options, though. For many purposes
198           the "on_start" hook is a better place.
199
200       on_start $term
201           Called at the very end of initialisation of a new terminal, just
202           before trying to map (display) the toplevel and returning to the
203           main loop.
204
205       on_destroy $term
206           Called whenever something tries to destroy terminal, when the
207           terminal is still fully functional (not for long, though).
208
209       on_reset $term
210           Called after the screen is "reset" for any reason, such as resizing
211           or control sequences. Here is where you can react on changes to
212           size-related variables.
213
214       on_child_start $term, $pid
215           Called just after the child process has been "fork"ed.
216
217       on_child_exit $term, $status
218           Called just after the child process has exited. $status is the
219           status from "waitpid".
220
221       on_sel_make $term, $eventtime
222           Called whenever a selection has been made by the user, but before
223           the selection text is copied, so changes to the beginning, end or
224           type of the selection will be honored.
225
226           Returning a true value aborts selection making by urxvt, in which
227           case you have to make a selection yourself by calling
228           "$term->selection_grab".
229
230       on_sel_grab $term, $eventtime
231           Called whenever a selection has been copied, but before the
232           selection is requested from the server.  The selection text can be
233           queried and changed by calling "$term->selection".
234
235           Returning a true value aborts selection grabbing. It will still be
236           highlighted.
237
238       on_sel_extend $term
239           Called whenever the user tries to extend the selection (e.g. with a
240           double click) and is either supposed to return false (normal
241           operation), or should extend the selection itself and return true
242           to suppress the built-in processing. This can happen multiple
243           times, as long as the callback returns true, it will be called on
244           every further click by the user and is supposed to enlarge the
245           selection more and more, if possible.
246
247           See the selection example extension.
248
249       on_view_change $term, $offset
250           Called whenever the view offset changes, i.e. the user or program
251           scrolls. Offset 0 means display the normal terminal, positive
252           values show this many lines of scrollback.
253
254       on_scroll_back $term, $lines, $saved
255           Called whenever lines scroll out of the terminal area into the
256           scrollback buffer. $lines is the number of lines scrolled out and
257           may be larger than the scroll back buffer or the terminal.
258
259           It is called before lines are scrolled out (so rows 0 .. min
260           ($lines - 1, $nrow - 1) represent the lines to be scrolled out).
261           $saved is the total number of lines that will be in the scrollback
262           buffer.
263
264       on_osc_seq $term, $op, $args, $resp
265           Called on every OSC sequence and can be used to suppress it or
266           modify its behaviour. The default should be to return an empty
267           list. A true value suppresses execution of the request completely.
268           Make sure you don't get confused by recursive invocations when you
269           output an OSC sequence within this callback.
270
271           "on_osc_seq_perl" should be used for new behaviour.
272
273       on_osc_seq_perl $term, $args, $resp
274           Called whenever the ESC ] 777 ; prefix ; string ST command sequence
275           (OSC = operating system command) is processed. Cursor position and
276           other state information is up-to-date when this happens. For
277           interoperability, the argument should start with the extension name
278           (sans -osc) or some other suitable prefix, and a semicolon, to
279           distinguish it from commands for other extensions.
280
281           For example, "overlay-osc" uses this:
282
283              sub on_osc_seq_perl {
284                 my ($self, $osc, $resp) = @_;
285
286                 return unless $osc =~ s/^overlay;//;
287
288                 ... process remaining $osc string
289              }
290
291           Be careful not ever to trust (in a security sense) the data you
292           receive, as its source can not easily be controlled (e-mail
293           content, messages from other users on the same system etc.).
294
295           For responses, $resp contains the end-of-args separator used by the
296           sender.
297
298       on_add_lines $term, $string
299           Called whenever text is about to be output, with the text as
300           argument. You can filter/change and output the text yourself by
301           returning a true value and calling "$term->scr_add_lines" yourself.
302           Please note that this might be very slow, however, as your hook is
303           called for all text being output.
304
305       on_tt_write $term, $octets
306           Called whenever some data is written to the tty/pty and can be used
307           to suppress or filter tty input.
308
309       on_tt_paste $term, $octets
310           Called whenever text is about to be pasted, with the text as
311           argument. You can filter/change and paste the text yourself by
312           returning a true value and calling "$term->tt_paste" yourself.
313           $octets is locale-encoded.
314
315       on_line_update $term, $row
316           Called whenever a line was updated or changed. Can be used to
317           filter screen output (e.g. underline urls or other useless stuff).
318           Only lines that are being shown will be filtered, and, due to
319           performance reasons, not always immediately.
320
321           The row number is always the topmost row of the line if the line
322           spans multiple rows.
323
324           Please note that, if you change the line, then the hook might get
325           called later with the already-modified line (e.g. if unrelated
326           parts change), so you cannot just toggle rendition bits, but only
327           set them.
328
329       on_refresh_begin $term
330           Called just before the screen gets redrawn. Can be used for overlay
331           or similar effects by modifying the terminal contents in
332           refresh_begin, and restoring them in refresh_end. The built-in
333           overlay and selection display code is run after this hook, and
334           takes precedence.
335
336       on_refresh_end $term
337           Called just after the screen gets redrawn. See "on_refresh_begin".
338
339       on_action $term, $string
340           Called whenever an action is invoked for the corresponding
341           extension (e.g. via a "extension:string" builtin action bound to a
342           key, see description of the keysym resource in the urxvt(1)
343           manpage). The event is simply the action string. Note that an
344           action event is always associated to a single extension.
345
346       on_user_command $term, $string *DEPRECATED*
347           Called whenever a user-configured event is being activated (e.g.
348           via a "perl:string" action bound to a key, see description of the
349           keysym resource in the urxvt(1) manpage).
350
351           The event is simply the action string. This interface is going away
352           in preference to the "on_action" hook.
353
354       on_resize_all_windows $term, $new_width, $new_height
355           Called just after the new window size has been calculated, but
356           before windows are actually being resized or hints are being set.
357           If this hook returns a true value, setting of the window hints is
358           being skipped.
359
360       on_x_event $term, $event
361           Called on every X event received on the vt window (and possibly
362           other windows). Should only be used as a last resort. Most event
363           structure members are not passed.
364
365       on_root_event $term, $event
366           Like "on_x_event", but is called for events on the root window.
367
368       on_focus_in $term
369           Called whenever the window gets the keyboard focus, before rxvt-
370           unicode does focus in processing.
371
372       on_focus_out $term
373           Called whenever the window loses keyboard focus, before rxvt-
374           unicode does focus out processing.
375
376       on_configure_notify $term, $event
377       on_property_notify $term, $event
378       on_key_press $term, $event, $keysym, $octets
379       on_key_release $term, $event, $keysym
380       on_button_press $term, $event
381       on_button_release $term, $event
382       on_motion_notify $term, $event
383       on_map_notify $term, $event
384       on_unmap_notify $term, $event
385           Called whenever the corresponding X event is received for the
386           terminal. If the hook returns true, then the event will be ignored
387           by rxvt-unicode.
388
389           The event is a hash with most values as named by Xlib (see the
390           XEvent manpage), with the additional members "row" and "col", which
391           are the (real, not screen-based) row and column under the mouse
392           cursor.
393
394           "on_key_press" additionally receives the string rxvt-unicode would
395           output, if any, in locale-specific encoding.
396
397       on_client_message $term, $event
398       on_wm_protocols $term, $event
399       on_wm_delete_window $term, $event
400           Called when various types of ClientMessage events are received (all
401           with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
402
403       on_bell $term
404           Called on receipt of a bell character.
405
406   Variables in the "urxvt" Package
407       $urxvt::LIBDIR
408           The rxvt-unicode library directory, where, among other things, the
409           perl modules and scripts are stored.
410
411       $urxvt::RESCLASS, $urxvt::RESCLASS
412           The resource class and name rxvt-unicode uses to look up X
413           resources.
414
415       $urxvt::RXVTNAME
416           The basename of the installed binaries, usually "urxvt".
417
418       $urxvt::TERM
419           The current terminal. This variable stores the current
420           "urxvt::term" object, whenever a callback/hook is executing.
421
422       @urxvt::TERM_INIT
423           All code references in this array will be called as methods of the
424           next newly created "urxvt::term" object (during the "on_init"
425           phase). The array gets cleared before the code references that were
426           in it are being executed, so references can push themselves onto it
427           again if they so desire.
428
429           This complements to the perl-eval command line option, but gets
430           executed first.
431
432       @urxvt::TERM_EXT
433           Works similar to @TERM_INIT, but contains perl package/class names,
434           which get registered as normal extensions after calling the hooks
435           in @TERM_INIT but before other extensions. Gets cleared just like
436           @TERM_INIT.
437
438   Functions in the "urxvt" Package
439       urxvt::fatal $errormessage
440           Fatally aborts execution with the given error message (which should
441           include a trailing newline). Avoid at all costs! The only time this
442           is acceptable (and useful) is in the init hook, where it prevents
443           the terminal from starting up.
444
445       urxvt::warn $string
446           Calls "rxvt_warn" with the given string which should include a
447           trailing newline. The module also overwrites the "warn" builtin
448           with a function that calls this function.
449
450           Using this function has the advantage that its output ends up in
451           the correct place, e.g. on stderr of the connecting urxvtc client.
452
453           Messages have a size limit of 1023 bytes currently.
454
455       @terms = urxvt::termlist
456           Returns all urxvt::term objects that exist in this process,
457           regardless of whether they are started, being destroyed etc., so be
458           careful. Only term objects that have perl extensions attached will
459           be returned (because there is no urxvt::term object associated with
460           others).
461
462       $time = urxvt::NOW
463           Returns the "current time" (as per the event loop).
464
465       urxvt::CurrentTime
466       urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
467       Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
468       Button5Mask, AnyModifier
469       urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
470       ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
471       PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
472       Button3MotionMask, Button4MotionMask, Button5MotionMask,
473       ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
474       StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
475       SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
476       ColormapChangeMask, OwnerGrabButtonMask
477       urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
478       EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
479       GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify,
480       DestroyNotify, UnmapNotify, MapNotify, MapRequest, ReparentNotify,
481       ConfigureNotify, ConfigureRequest, GravityNotify, ResizeRequest,
482       CirculateNotify, CirculateRequest, PropertyNotify, SelectionClear,
483       SelectionRequest, SelectionNotify, ColormapNotify, ClientMessage,
484       MappingNotify
485           Various constants for use in X calls and event processing.
486
487       urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo,
488       PrivMode_relOrigin, PrivMode_Screen, PrivMode_Autowrap,
489       PrivMode_aplCUR, PrivMode_aplKP, PrivMode_HaveBackSpace,
490       PrivMode_BackSpace, PrivMode_ShiftKeys, PrivMode_VisibleCursor,
491       PrivMode_MouseX10, PrivMode_MouseX11, PrivMode_scrollBar,
492       PrivMode_TtyOutputInh, PrivMode_Keypress, PrivMode_smoothScroll,
493       PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
494       PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8,
495       PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report,
496       PrivMode_Default
497           Constants for checking DEC private modes.
498
499   RENDITION
500       Rendition bitsets contain information about colour, font, font styles
501       and similar information for each screen cell.
502
503       The following "macros" deal with changes in rendition sets. You should
504       never just create a bitset, you should always modify an existing one,
505       as they contain important information required for correct operation of
506       rxvt-unicode.
507
508       $rend = urxvt::DEFAULT_RSTYLE
509           Returns the default rendition, as used when the terminal is
510           starting up or being reset. Useful as a base to start when creating
511           renditions.
512
513       $rend = urxvt::OVERLAY_RSTYLE
514           Return the rendition mask used for overlays by default.
515
516       $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
517       urxvt::RS_RVid, urxvt::RS_Uline
518           Return the bit that enabled bold, italic, blink, reverse-video and
519           underline, respectively. To enable such a style, just logically OR
520           it into the bitset.
521
522       $foreground = urxvt::GET_BASEFG $rend
523       $background = urxvt::GET_BASEBG $rend
524           Return the foreground/background colour index, respectively.
525
526       $rend = urxvt::SET_FGCOLOR $rend, $new_colour
527       $rend = urxvt::SET_BGCOLOR $rend, $new_colour
528       $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
529           Replace the foreground/background colour in the rendition mask with
530           the specified one.
531
532       $value = urxvt::GET_CUSTOM $rend
533           Return the "custom" value: Every rendition has 5 bits for use by
534           extensions. They can be set and changed as you like and are
535           initially zero.
536
537       $rend = urxvt::SET_CUSTOM $rend, $new_value
538           Change the custom value.
539
540   The "urxvt::term::extension" class
541       Each extension attached to a terminal object is represented by a
542       "urxvt::term::extension" object.
543
544       You can use these objects, which are passed to all callbacks to store
545       any state related to the terminal and extension instance.
546
547       The methods (And data members) documented below can be called on
548       extension objects, in addition to call methods documented for the
549       <urxvt::term> class.
550
551       $urxvt_term = $self->{term}
552           Returns the "urxvt::term" object associated with this instance of
553           the extension. This member must not be changed in any way.
554
555       $self->enable ($hook_name => $cb[, $hook_name => $cb..])
556           Dynamically enable the given hooks (named without the "on_" prefix)
557           for this extension, replacing any hook previously installed via
558           "enable" in this extension.
559
560           This is useful when you want to overwrite time-critical hooks only
561           temporarily.
562
563           To install additional callbacks for the same hook, you can use the
564           "on" method of the "urxvt::term" class.
565
566       $self->disable ($hook_name[, $hook_name..])
567           Dynamically disable the given hooks.
568
569       $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..])
570           Similar to the "enable" enable, but installs additional callbacks
571           for the given hook(s) (that is, it doesn't replace existing
572           callbacks), and returns a guard object. When the guard object is
573           destroyed the callbacks are disabled again.
574
575       $self->bind_action ($hotkey, $action)
576       $self->x_resource ($pattern)
577       $self->x_resource_boolean ($pattern)
578           These methods support an additional "%" prefix for $action or
579           $pattern when called on an extension object, compared to the
580           "urxvt::term" methods of the same name - see the description of
581           these methods in the "urxvt::term" class for details.
582
583   The "urxvt::anyevent" Class
584       The sole purpose of this class is to deliver an interface to the
585       "AnyEvent" module - any module using it will work inside urxvt without
586       further programming. The only exception is that you cannot wait on
587       condition variables, but non-blocking condvar use is ok.
588
589       In practical terms this means is that you cannot use blocking APIs, but
590       the non-blocking variant should work.
591
592   The "urxvt::term" Class
593       $term = new urxvt::term $envhashref, $rxvtname, [arg...]
594           Creates a new terminal, very similar as if you had started it with
595           system "$rxvtname, arg...". $envhashref must be a reference to a
596           %ENV-like hash which defines the environment of the new terminal.
597
598           Croaks (and probably outputs an error message) if the new instance
599           couldn't be created.  Returns "undef" if the new instance didn't
600           initialise perl, and the terminal object otherwise. The "init" and
601           "start" hooks will be called before this call returns, and are free
602           to refer to global data (which is race free).
603
604       $term->destroy
605           Destroy the terminal object (close the window, free resources
606           etc.). Please note that urxvt will not exit as long as any event
607           watchers (timers, io watchers) are still active.
608
609       $term->exec_async ($cmd[, @args])
610           Works like the combination of the "fork"/"exec" builtins, which
611           executes ("starts") programs in the background. This function takes
612           care of setting the user environment before exec'ing the command
613           (e.g. "PATH") and should be preferred over explicit calls to "exec"
614           or "system".
615
616           It also sets the "URXVT_EXT_WINDOWID" environment variable to the
617           window ID of the terminal ("$self->parent"), similar to the
618           "WINDOWID" variable set for the process spawned inside the
619           terminal.
620
621           Returns the pid of the subprocess or "undef" on error.
622
623       $isset = $term->option ($optval[, $set])
624           Returns true if the option specified by $optval is enabled, and
625           optionally change it. All option values are stored by name in the
626           hash %urxvt::OPTION. Options not enabled in this binary are not in
627           the hash.
628
629           Here is a likely non-exhaustive list of option names, please see
630           the source file /src/optinc.h to see the actual list:
631
632            borderLess buffered console cursorBlink cursorUnderline hold iconic
633            insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
634            mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
635            pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
636            scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
637            secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
638            urgentOnBell utmpInhibit visualBell disablePasteBrackets
639
640       $value = $term->resource ($name[, $newval])
641           Returns the current resource value associated with a given name and
642           optionally sets a new value. Setting values is most useful in the
643           "init" hook. Unset resources are returned and accepted as "undef".
644
645           The new value must be properly encoded to a suitable character
646           encoding before passing it to this method. Similarly, the returned
647           value may need to be converted from the used encoding to text.
648
649           Resource names are as defined in src/rsinc.h. Colours can be
650           specified as resource names of the form "color+<index>", e.g.
651           "color+5". (will likely change).
652
653           Please note that resource strings will currently only be freed when
654           the terminal is destroyed, so changing options frequently will eat
655           memory.
656
657           Here is a likely non-exhaustive list of resource names, not all of
658           which are supported in every build, please see the source file
659           /src/rsinc.h to see the actual list:
660
661             answerbackstring backgroundPixmap backspace_key blurradius
662             boldFont boldItalicFont borderLess buffered chdir color cursorBlink
663             cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
664             fade font geometry hold iconName iconfile imFont imLocale inputMethod
665             insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
666             jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
667             mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
668             perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
669             preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
670             scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
671             scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
672             secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
673             term_name title transient_for transparent tripleclickwords urgentOnBell
674             utmpInhibit visualBell rewrapMode disablePasteBrackets
675
676       $value = $term->x_resource ($pattern)
677           Returns the X-Resource for the given pattern, excluding the program
678           or class name, i.e.  "$term->x_resource ("boldFont")" should return
679           the same value as used by this instance of rxvt-unicode. Returns
680           "undef" if no resource with that pattern exists.
681
682           Extensions that define extra resources also need to call this
683           method to access their values.
684
685           If the method is called on an extension object (basically, from an
686           extension), then the special prefix "%." will be replaced by the
687           name of the extension and a dot, and the lone string "%" will be
688           replaced by the extension name itself. This makes it possible to
689           code extensions so you can rename them and get a new set of
690           resources without having to change the actual code.
691
692           This method should only be called during the "on_start" hook, as
693           there is only one resource database per display, and later
694           invocations might return the wrong resources.
695
696       $value = $term->x_resource_boolean ($pattern)
697           Like "x_resource", above, but interprets the string value as a
698           boolean and returns 1 for true values, 0 for false values and
699           "undef" if the resource or option isn't specified.
700
701           You should always use this method to parse boolean resources.
702
703       $action = $term->lookup_keysym ($keysym, $state)
704           Returns the action bound to key combination "($keysym, $state)", if
705           a binding for it exists, and "undef" otherwise.
706
707       $success = $term->bind_action ($key, $action)
708           Adds a key binding exactly as specified via a "keysym" resource.
709           See the "keysym" resource in the urxvt(1) manpage.
710
711           To add default bindings for actions, an extension should call
712           "->bind_action" in its "init" hook for every such binding. Doing it
713           in the "init" hook allows users to override or remove the binding
714           again.
715
716           Example: the "searchable-scrollback" by default binds itself on
717           "Meta-s", using "$self->bind_action", which calls
718           "$term->bind_action".
719
720              sub init {
721                 my ($self) = @_;
722
723                 $self->bind_action ("M-s" => "%:start");
724              }
725
726       $rend = $term->rstyle ([$new_rstyle])
727           Return and optionally change the current rendition. Text that is
728           output by the terminal application will use this style.
729
730       ($row, $col) = $term->screen_cur ([$row, $col])
731           Return the current coordinates of the text cursor position and
732           optionally set it (which is usually bad as applications don't
733           expect that).
734
735       ($row, $col) = $term->selection_mark ([$row, $col])
736       ($row, $col) = $term->selection_beg ([$row, $col])
737       ($row, $col) = $term->selection_end ([$row, $col])
738           Return the current values of the selection mark, begin or end
739           positions.
740
741           When arguments are given, then the selection coordinates are set to
742           $row and $col, and the selection screen is set to the current
743           screen.
744
745       $screen = $term->selection_screen ([$screen])
746           Returns the current selection screen, and then optionally sets it.
747
748       $term->selection_make ($eventtime[, $rectangular])
749           Tries to make a selection as set by "selection_beg" and
750           "selection_end". If $rectangular is true (default: false), a
751           rectangular selection will be made. This is the preferred function
752           to make a selection.
753
754       $success = $term->selection_grab ($eventtime[, $clipboard])
755           Try to acquire ownership of the primary (clipboard if $clipboard is
756           true) selection from the server. The corresponding text can be set
757           with the next method. No visual feedback will be given. This
758           function is mostly useful from within "on_sel_grab" hooks.
759
760       $oldtext = $term->selection ([$newtext, $clipboard])
761           Return the current selection (clipboard if $clipboard is true) text
762           and optionally replace it by $newtext.
763
764       $term->selection_clear ([$clipboard])
765           Revoke ownership of the primary (clipboard if $clipboard is true)
766           selection.
767
768       $term->overlay_simple ($x, $y, $text)
769           Create a simple multi-line overlay box. See the next method for
770           details.
771
772       $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
773           Create a new (empty) overlay at the given position with the given
774           width/height. $rstyle defines the initial rendition style (default:
775           "OVERLAY_RSTYLE").
776
777           If $border is 2 (default), then a decorative border will be put
778           around the box.
779
780           If either $x or $y is negative, then this is counted from the
781           right/bottom side, respectively.
782
783           This method returns an urxvt::overlay object. The overlay will be
784           visible as long as the perl object is referenced.
785
786           The methods currently supported on "urxvt::overlay" objects are:
787
788           $overlay->set ($x, $y, $text[, $rend])
789               Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
790               text in rxvt-unicode's special encoding and an array of
791               rendition values at a specific position inside the overlay.
792
793               If $rend is missing, then the rendition will not be changed.
794
795           $overlay->hide
796               If visible, hide the overlay, but do not destroy it.
797
798           $overlay->show
799               If hidden, display the overlay again.
800
801       $popup = $term->popup ($event)
802           Creates a new "urxvt::popup" object that implements a popup menu.
803           The $event must be the event causing the menu to pop up (a button
804           event, currently).
805
806       $cellwidth = $term->strwidth ($string)
807           Returns the number of screen-cells this string would need.
808           Correctly accounts for wide and combining characters.
809
810       $octets = $term->locale_encode ($string)
811           Convert the given text string into the corresponding locale
812           encoding. Returns "undef" if $string is "undef".
813
814       $string = $term->locale_decode ($octets)
815           Convert the given locale-encoded octets into a perl string. Returns
816           "undef" if $octets is "undef".
817
818       $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
819           XORs the rendition values in the given span with the provided value
820           (default: "RS_RVid"), which MUST NOT contain font styles. Useful in
821           refresh hooks to provide effects similar to the selection.
822
823       $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[,
824       $rstyle1[, $rstyle2]])
825           Similar to "scr_xor_span", but xors a rectangle instead. Trailing
826           whitespace will additionally be xored with the $rstyle2, which
827           defaults to "RS_RVid | RS_Uline", which removes reverse video again
828           and underlines it instead. Both styles MUST NOT contain font
829           styles.
830
831       $term->scr_bell
832           Ring the bell!
833
834       $term->scr_add_lines ($string)
835           Write the given text string to the screen, as if output by the
836           application running inside the terminal. It may not contain command
837           sequences (escape codes - see "cmd_parse" for that), but is free to
838           use line feeds, carriage returns and tabs. The string is a normal
839           text string, not in locale-dependent encoding.
840
841           Normally its not a good idea to use this function, as programs
842           might be confused by changes in cursor position or scrolling. Its
843           useful inside a "on_add_lines" hook, though.
844
845       $term->scr_change_screen ($screen)
846           Switch to given screen - 0 primary, 1 secondary.
847
848       $term->cmd_parse ($octets)
849           Similar to "scr_add_lines", but the argument must be in the locale-
850           specific encoding of the terminal and can contain command sequences
851           (escape codes) that will be interpreted.
852
853       $term->tt_write ($octets)
854           Write the octets given in $octets to the tty (i.e. as user input to
855           the program, see "cmd_parse" for the opposite direction). To pass
856           characters instead of octets, you should convert your strings first
857           to the locale-specific encoding using "$term->locale_encode".
858
859       $term->tt_write_user_input ($octets)
860           Like "tt_write", but should be used when writing strings in
861           response to the user pressing a key, to invoke the additional
862           actions requested by the user for that case ("tt_write" doesn't do
863           that).
864
865           The typical use case would be inside "on_action" hooks.
866
867       $term->tt_paste ($octets)
868           Write the octets given in $octets to the tty as a paste, converting
869           NL to CR and bracketing the data with control sequences if
870           bracketed paste mode is set.
871
872       $old_events = $term->pty_ev_events ([$new_events])
873           Replaces the event mask of the pty watcher by the given event mask.
874           Can be used to suppress input and output handling to the pty/tty.
875           See the description of "urxvt::timer->events". Make sure to always
876           restore the previous value.
877
878       $fd = $term->pty_fd
879           Returns the master file descriptor for the pty in use, or "-1" if
880           no pty is used.
881
882       $windowid = $term->parent
883           Return the window id of the toplevel window.
884
885       $windowid = $term->vt
886           Return the window id of the terminal window.
887
888       $term->vt_emask_add ($x_event_mask)
889           Adds the specified events to the vt event mask. Useful e.g. when
890           you want to receive pointer events all the times:
891
892              $term->vt_emask_add (urxvt::PointerMotionMask);
893
894       $term->set_urgency ($set)
895           Enable/disable the urgency hint on the toplevel window.
896
897       $term->focus_in
898       $term->focus_out
899       $term->key_press ($state, $keycode[, $time])
900       $term->key_release ($state, $keycode[, $time])
901           Deliver various fake events to to terminal.
902
903       $window_width = $term->width ([$new_value])
904       $window_height = $term->height ([$new_value])
905       $font_width = $term->fwidth ([$new_value])
906       $font_height = $term->fheight ([$new_value])
907       $font_ascent = $term->fbase ([$new_value])
908       $terminal_rows = $term->nrow ([$new_value])
909       $terminal_columns = $term->ncol ([$new_value])
910       $has_focus = $term->focus ([$new_value])
911       $is_mapped = $term->mapped ([$new_value])
912       $max_scrollback = $term->saveLines ([$new_value])
913       $nrow_plus_saveLines = $term->total_rows ([$new_value])
914       $topmost_scrollback_row = $term->top_row ([$new_value])
915           Return various integers describing terminal characteristics. If an
916           argument is given, changes the value and returns the previous one.
917
918       $x_display = $term->display_id
919           Return the DISPLAY used by rxvt-unicode.
920
921       $lc_ctype = $term->locale
922           Returns the LC_CTYPE category string used by this rxvt-unicode.
923
924       $env = $term->env
925           Returns a copy of the environment in effect for the terminal as a
926           hashref similar to "\%ENV".
927
928       @envv = $term->envv
929           Returns the environment as array of strings of the form
930           "VAR=VALUE".
931
932       @argv = $term->argv
933           Return the argument vector as this terminal, similar to @ARGV, but
934           includes the program name as first element.
935
936       $modifiermask = $term->ModLevel3Mask
937       $modifiermask = $term->ModMetaMask
938       $modifiermask = $term->ModNumLockMask
939           Return the modifier masks corresponding to the "ISO Level 3 Shift"
940           (often AltGr), the meta key (often Alt) and the num lock key, if
941           applicable.
942
943       $screen = $term->current_screen
944           Returns the currently displayed screen (0 primary, 1 secondary).
945
946       $cursor_is_hidden = $term->hidden_cursor
947           Returns whether the cursor is currently hidden or not.
948
949       $priv_modes = $term->priv_modes
950           Returns a bitset with the state of DEC private modes.
951
952           Example:
953
954             if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
955                 # mouse reporting is turned on
956             }
957
958       $view_start = $term->view_start ([$newvalue])
959           Returns the row number of the topmost displayed line and changes
960           it, if an argument is given. Values greater than or equal to 0
961           display the terminal contents. Lower values scroll this many lines
962           into the scrollback buffer.
963
964       $term->want_refresh
965           Requests a screen refresh. At the next opportunity, rxvt-unicode
966           will compare the on-screen display with its stored representation.
967           If they differ, it redraws the differences.
968
969           Used after changing terminal contents to display them.
970
971       $term->refresh_check
972           Checks if a refresh has been requested and, if so, schedules one.
973
974       $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
975           Returns the text of the entire row with number $row_number. Row
976           "$term->top_row" is the topmost terminal line, row "$term->nrow-1"
977           is the bottommost terminal line. Nothing will be returned if a
978           nonexistent line is requested.
979
980           If $new_text is specified, it will replace characters in the
981           current line, starting at column $start_col (default 0), which is
982           useful to replace only parts of a line. The font index in the
983           rendition will automatically be updated.
984
985           $text is in a special encoding: tabs and wide characters that use
986           more than one cell when displayed are padded with $urxvt::NOCHAR
987           (chr 65535) characters. Characters with combining characters and
988           other characters that do not fit into the normal text encoding will
989           be replaced with characters in the private use area.
990
991           You have to obey this encoding when changing text. The advantage is
992           that "substr" and similar functions work on screen cells and not on
993           characters.
994
995           The methods "$term->special_encode" and "$term->special_decode" can
996           be used to convert normal strings into this encoding and vice
997           versa.
998
999       $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1000           Like "$term->ROW_t", but returns an arrayref with rendition
1001           bitsets. Rendition bitsets contain information about colour, font,
1002           font styles and similar information. See also "$term->ROW_t".
1003
1004           When setting rendition, the font mask will be ignored.
1005
1006           See the section on RENDITION, above.
1007
1008       $length = $term->ROW_l ($row_number[, $new_length])
1009           Returns the number of screen cells that are in use ("the line
1010           length"). Unlike the urxvt core, this returns "$term->ncol" if the
1011           line is joined with the following one.
1012
1013       $bool = $term->is_longer ($row_number)
1014           Returns true if the row is part of a multiple-row logical "line"
1015           (i.e.  joined with the following row), which means all characters
1016           are in use and it is continued on the next row (and possibly a
1017           continuation of the previous row(s)).
1018
1019       $line = $term->line ($row_number)
1020           Create and return a new "urxvt::line" object that stores
1021           information about the logical line that row $row_number is part of.
1022           It supports the following methods:
1023
1024           $text = $line->t ([$new_text])
1025               Returns or replaces the full text of the line, similar to
1026               "ROW_t"
1027
1028           $rend = $line->r ([$new_rend])
1029               Returns or replaces the full rendition array of the line,
1030               similar to "ROW_r"
1031
1032           $length = $line->l
1033               Returns the length of the line in cells, similar to "ROW_l".
1034
1035           $rownum = $line->beg
1036           $rownum = $line->end
1037               Return the row number of the first/last row of the line,
1038               respectively.
1039
1040           $offset = $line->offset_of ($row, $col)
1041               Returns the character offset of the given row|col pair within
1042               the logical line. Works for rows outside the line, too, and
1043               returns corresponding offsets outside the string.
1044
1045           ($row, $col) = $line->coord_of ($offset)
1046               Translates a string offset into terminal coordinates again.
1047
1048       $text = $term->special_encode ($string)
1049           Converts a perl string into the special encoding used by rxvt-
1050           unicode, where one character corresponds to one screen cell. See
1051           "$term->ROW_t" for details.
1052
1053       $string = $term->special_decode ($text)
1054           Converts rxvt-unicode's text representation into a perl string. See
1055           "$term->ROW_t" for details.
1056
1057       $success = $term->grab_button ($button, $modifiermask[, $window =
1058       $term->vt])
1059       $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
1060           Register/unregister a synchronous button grab. See the XGrabButton
1061           manpage.
1062
1063       $success = $term->grab ($eventtime[, $sync])
1064           Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1065           synchronous ($sync is true). Also remembers the grab timestamp.
1066
1067       $term->allow_events_async
1068           Calls XAllowEvents with AsyncBoth for the most recent grab.
1069
1070       $term->allow_events_sync
1071           Calls XAllowEvents with SyncBoth for the most recent grab.
1072
1073       $term->allow_events_replay
1074           Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for
1075           the most recent grab.
1076
1077       $term->ungrab
1078           Calls XUngrabPointer and XUngrabKeyboard for the most recent grab.
1079           Is called automatically on evaluation errors, as it is better to
1080           lose the grab in the error case as the session.
1081
1082       $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1083       $atom_name = $term->XGetAtomName ($atom)
1084       @atoms = $term->XListProperties ($window)
1085       ($type,$format,$octets) = $term->XGetWindowProperty ($window,
1086       $property)
1087       $term->XChangeProperty ($window, $property, $type, $format, $octets)
1088       $term->XDeleteProperty ($window, $property)
1089       $window = $term->DefaultRootWindow
1090       $term->XReparentWindow ($window, $parent, [$x, $y])
1091       $term->XMapWindow ($window)
1092       $term->XUnmapWindow ($window)
1093       $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1094       ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
1095       $y)
1096       $term->XChangeInput ($window, $add_events[, $del_events])
1097       $keysym = $term->XStringToKeysym ($string)
1098       $string = $term->XKeysymToString ($keysym)
1099           Various X or X-related functions. The $term object only serves as
1100           the source of the display, otherwise those functions map more-or-
1101           less directly onto the X functions of the same name.
1102
1103   The "urxvt::popup" Class
1104       $popup->add_title ($title)
1105           Adds a non-clickable title to the popup.
1106
1107       $popup->add_separator ([$sepchr])
1108           Creates a separator, optionally using the character given as
1109           $sepchr.
1110
1111       $popup->add_button ($text, $cb)
1112           Adds a clickable button to the popup. $cb is called whenever it is
1113           selected.
1114
1115       $popup->add_toggle ($text, $initial_value, $cb)
1116           Adds a toggle/checkbox item to the popup. The callback gets called
1117           whenever it gets toggled, with a boolean indicating its new value
1118           as its first argument.
1119
1120       $popup->show
1121           Displays the popup (which is initially hidden).
1122
1123   The "urxvt::timer" Class
1124       This class implements timer watchers/events. Time is represented as a
1125       fractional number of seconds since the epoch. Example:
1126
1127          $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
1128          $term->{timer} = urxvt::timer
1129                           ->new
1130                           ->interval (1)
1131                           ->cb (sub {
1132                              $term->{overlay}->set (0, 0,
1133                                 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
1134                           });
1135
1136       $timer = new urxvt::timer
1137           Create a new timer object in started state. It is scheduled to fire
1138           immediately.
1139
1140       $timer = $timer->cb (sub { my ($timer) = @_; ... })
1141           Set the callback to be called when the timer triggers.
1142
1143       $timer = $timer->set ($tstamp[, $interval])
1144           Set the time the event is generated to $tstamp (and optionally
1145           specifies a new $interval).
1146
1147       $timer = $timer->interval ($interval)
1148           By default (and when $interval is 0), the timer will automatically
1149           stop after it has fired once. If $interval is non-zero, then the
1150           timer is automatically rescheduled at the given intervals.
1151
1152       $timer = $timer->start
1153           Start the timer.
1154
1155       $timer = $timer->start ($tstamp[, $interval])
1156           Set the event trigger time to $tstamp and start the timer.
1157           Optionally also replaces the interval.
1158
1159       $timer = $timer->after ($delay[, $interval])
1160           Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
1161
1162       $timer = $timer->stop
1163           Stop the timer.
1164
1165   The "urxvt::iow" Class
1166       This class implements io watchers/events. Example:
1167
1168         $term->{socket} = ...
1169         $term->{iow} = urxvt::iow
1170                        ->new
1171                        ->fd (fileno $term->{socket})
1172                        ->events (urxvt::EV_READ)
1173                        ->start
1174                        ->cb (sub {
1175                          my ($iow, $revents) = @_;
1176                          # $revents must be 1 here, no need to check
1177                          sysread $term->{socket}, my $buf, 8192
1178                             or end-of-file;
1179                        });
1180
1181       $iow = new urxvt::iow
1182           Create a new io watcher object in stopped state.
1183
1184       $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
1185           Set the callback to be called when io events are triggered.
1186           $reventmask is a bitset as described in the "events" method.
1187
1188       $iow = $iow->fd ($fd)
1189           Set the file descriptor (not handle) to watch.
1190
1191       $iow = $iow->events ($eventmask)
1192           Set the event mask to watch. The only allowed values are
1193           "urxvt::EV_READ" and "urxvt::EV_WRITE", which might be ORed
1194           together, or "urxvt::EV_NONE".
1195
1196       $iow = $iow->start
1197           Start watching for requested events on the given handle.
1198
1199       $iow = $iow->stop
1200           Stop watching for events on the given file handle.
1201
1202   The "urxvt::iw" Class
1203       This class implements idle watchers, that get called automatically when
1204       the process is idle. They should return as fast as possible, after
1205       doing some useful work.
1206
1207       $iw = new urxvt::iw
1208           Create a new idle watcher object in stopped state.
1209
1210       $iw = $iw->cb (sub { my ($iw) = @_; ... })
1211           Set the callback to be called when the watcher triggers.
1212
1213       $timer = $timer->start
1214           Start the watcher.
1215
1216       $timer = $timer->stop
1217           Stop the watcher.
1218
1219   The "urxvt::pw" Class
1220       This class implements process watchers. They create an event whenever a
1221       process exits, after which they stop automatically.
1222
1223          my $pid = fork;
1224          ...
1225          $term->{pw} = urxvt::pw
1226                           ->new
1227                           ->start ($pid)
1228                           ->cb (sub {
1229                              my ($pw, $exit_status) = @_;
1230                              ...
1231                           });
1232
1233       $pw = new urxvt::pw
1234           Create a new process watcher in stopped state.
1235
1236       $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1237           Set the callback to be called when the timer triggers.
1238
1239       $pw = $timer->start ($pid)
1240           Tells the watcher to start watching for process $pid.
1241
1242       $pw = $pw->stop
1243           Stop the watcher.
1244

ENVIRONMENT

1246   URXVT_PERL_VERBOSITY
1247       This variable controls the verbosity level of the perl extension.
1248       Higher numbers indicate more verbose output.
1249
1250       == 0 - fatal messages only
1251       >= 2 - general warnings (default level)
1252       >= 3 - script loading and management
1253       >=10 - all called hooks
1254       >=11 - hook return values
1255

AUTHOR

1257        Marc Lehmann <schmorp@schmorp.de>
1258        http://software.schmorp.de/pkg/rxvt-unicode
1259
1260
1261
12629.31                              2023-01-03                      urxvtperl(3)
Impressum