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

ENVIRONMENT

1181   URXVT_PERL_VERBOSITY
1182       This variable controls the verbosity level of the perl extension.
1183       Higher numbers indicate more verbose output.
1184
1185       == 0 - fatal messages
1186       >= 3 - script loading and management
1187       >=10 - all called hooks
1188       >=11 - hook return values
1189

AUTHOR

1191        Marc Lehmann <schmorp@schmorp.de>
1192        http://software.schmorp.de/pkg/rxvt-unicode
1193
1194
1195
11969.26                              2021-05-14                      urxvtperl(3)
Impressum