3 rxvtperl - rxvt-unicode's embedded perl interpreter
7 * Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically.
9 * Each script will only be loaded once, even in urxvtd, and will be valid
12 * Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
13 thus must be encoded as UTF-8.
16 warn "you selected ", $_[0]->selection;
26 The following subroutines can be declared in loaded scripts, and will be called
27 whenever the relevant event happens.
29 All of them must return a boolean value. If it is true, then the event
30 counts as being I<consumed>, and the invocation of other hooks is skipped,
31 and the relevant action might not be carried out by the C++ code.
33 When in doubt, return a false value (preferably C<()>).
39 Called after a new terminal object has been initialized, but before
40 windows are created or the command gets run.
44 Called after the screen is "reset" for any reason, such as resizing or
45 control sequences. Here is where you can react on changes to size-related
50 Called at the very end of initialisation of a new terminal, just before
51 returning to the mainloop.
53 =item on_sel_make $term, $eventtime
55 Called whenever a selection has been made by the user, but before the
56 selection text is copied, so changes to the beginning, end or type of the
57 selection will be honored.
59 Returning a true value aborts selection making by urxvt, in which case you
60 have to make a selection yourself by calling C<< $term->selection_grab >>.
62 =item on_sel_grab $term, $eventtime
64 Called whenever a selection has been copied, but before the selection is
65 requested from the server. The selection text can be queried and changed
66 by calling C<< $term->selection >>.
68 Returning a true value aborts selection grabbing. It will still be hilighted.
70 =item on_focus_in $term
72 Called whenever the window gets the keyboard focus, before urxvt does
75 =item on_focus_out $term
77 Called wheneever the window loses keyboard focus, before urxvt does focus
80 =item on_view_change $term, $offset
82 Called whenever the view offset changes, i..e the user or program
83 scrolls. Offset C<0> means display the normal terminal, positive values
84 show this many lines of scrollback.
86 =item on_scroll_back $term, $lines, $saved
88 Called whenever lines scroll out of the terminal area into the scrollback
89 buffer. C<$lines> is the number of lines scrolled out and may be larger
90 than the scroll back buffer or the terminal.
92 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
93 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
94 number of lines that will be in the scrollback buffer.
96 =item on_tty_activity $term *NYI*
98 Called whenever the program(s) running in the urxvt window send output.
100 =item on_refresh_begin $term
102 Called just before the screen gets redrawn. Can be used for overlay
103 or similar effects by modify terminal contents in refresh_begin, and
104 restoring them in refresh_end. The built-in overlay and selection display
105 code is run after this hook, and takes precedence.
107 =item on_refresh_end $term
109 Called just after the screen gets redrawn. See C<on_refresh_begin>.
113 =head2 Functions in the C<urxvt> Package
117 =item urxvt::fatal $errormessage
119 Fatally aborts execution with the given error message. Avoid at all
120 costs! The only time this is acceptable is when the terminal process
123 =item urxvt::warn $string
125 Calls C<rxvt_warn> witht eh given string which should not include a
126 newline. The module also overwrites the C<warn> builtin with a function
127 that calls this function.
129 Using this function has the advantage that its output ends up in the
130 correct place, e.g. on stderr of the connecting urxvtc client.
132 =item $cellwidth = urxvt::wcswidth $string
134 Returns the number of screen-cells this string would need. Correctly
135 accounts for wide and combining characters.
137 =item $time = urxvt::NOW
139 Returns the "current time" (as per the event loop).
154 # overwrite perl's warn
155 *CORE::GLOBAL::warn = sub {
156 my $msg = join "", @_;
158 unless $msg =~ /\n$/;
163 my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10;
166 my ($level, $msg) = @_;
172 # called by the rxvt core
177 my $cb = $invoke_cb[$htype];
179 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
182 while (my ($k, $v) = each %$cb) {
183 return 1 if $v->($term, @_);
189 # find on_xxx subs in the package and register them
191 sub register_package($) {
194 for my $hook (0.. $#HOOKNAME) {
195 my $name = $HOOKNAME[$hook];
197 my $ref = $pkg->can ("on_" . lc $name)
200 $invoke_cb[$hook]{$ref*1} = $ref;
201 set_should_invoke $hook, 1;
205 my $script_pkg = "script0000";
208 # load a single script into its own package, once only
212 $script_pkg{$path} ||= do {
213 my $pkg = $script_pkg++;
214 verbose 3, "loading script '$path' into package '$pkg'";
216 open my $fh, "<:raw", $path
219 eval "package $pkg; use strict; use utf8;\n"
220 . "#line 1 \"$path\"\n"
221 . do { local $/; <$fh> }
224 register_package $pkg;
230 load_script $_ for grep -f $_, <$LIBDIR/perl-ext/*>;
234 =head2 The C<urxvt::term> Class
238 =item $value = $term->resource ($name[, $newval])
240 Returns the current resource value associated with a given name and
241 optionally sets a new value. Setting values is most useful in the C<init>
242 hook. Unset resources are returned and accepted as C<undef>.
244 The new value must be properly encoded to a suitable character encoding
245 before passing it to this method. Similarly, the returned value may need
246 to be converted from the used encoding to text.
248 Resource names are as defined in F<src/rsinc.h>. Colours can be specified
249 as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
252 Please note that resource strings will currently only be freed when the
253 terminal is destroyed, so changing options frequently will eat memory.
255 Here is a a likely non-exhaustive list of resource names, not all of which
256 are supported in every build, please see the source to see the actual
259 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
260 borderLess color cursorBlink cursorUnderline cutchars delete_key
261 display_name embed ext_bwidth fade font geometry hold iconName
262 imFont imLocale inputMethod insecure int_bwidth intensityStyles
263 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8
264 modifier mouseWheelScrollPage name pastableTabs path pointerBlank
265 pointerBlankDelay preeditType print_pipe pty_fd reverseVideo saveLines
266 scrollBar scrollBar_align scrollBar_floating scrollBar_right
267 scrollBar_thickness scrollTtyKeypress scrollTtyOutput scrollWithBuffer
268 scrollstyle secondaryScreen secondaryScroll selectstyle shade term_name
269 title transparent transparent_all tripleclickwords utmpInhibit
274 sub urxvt::term::resource($$;$) {
275 my ($self, $name) = (shift, shift);
276 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
277 goto &urxvt::term::_resource;
280 =item ($row, $col) = $term->selection_mark ([$row, $col])
282 =item ($row, $col) = $term->selection_beg ([$row, $col])
284 =item ($row, $col) = $term->selection_end ([$row, $col])
286 Return the current values of the selection mark, begin or end positions,
287 and optionally set them to new values.
289 =item $success = $term->selection_grab ($eventtime)
291 Try to request the primary selection from the server (for example, as set
294 =item $oldtext = $term->selection ([$newtext])
296 Return the current selection text and optionally replace it by C<$newtext>.
298 =item $term->scr_overlay ($x, $y, $text)
300 Create a simple multi-line overlay box. See the next method for details.
304 sub urxvt::term::scr_overlay {
305 my ($self, $x, $y, $text) = @_;
307 my @lines = split /\n/, $text;
310 for (map urxvt::wcswidth $_, @lines) {
314 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
315 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
318 =item $term->scr_overlay_new ($x, $y, $width, $height)
320 Create a new (empty) overlay at the given position with the given
321 width/height. A border will be put around the box. If either C<$x> or
322 C<$y> is negative, then this is counted from the right/bottom side,
325 =item $term->scr_overlay_off
327 Switch the overlay off again.
329 =item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
331 Put a single character (specified numerically) at the given overlay
334 =item $term->scr_overlay_set ($x, $y, $text)
336 Write a string at the given position into the overlay.
340 =head2 The C<urxvt::timer> Class
342 This class implements timer watchers/events. Time is represented as a
343 fractional number of seconds since the epoch. Example:
345 # create a digital clock display in upper right corner
346 $term->{timer} = urxvt::timer
351 my $time = $timer->at;
352 $timer->start ($time + 1);
353 $self->scr_overlay (-1, 0,
354 POSIX::strftime "%H:%M:%S", localtime $time);
359 =item $timer = new urxvt::timer
361 Create a new timer object in stopped state.
363 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
365 Set the callback to be called when the timer triggers.
367 =item $tstamp = $timer->at
369 Return the time this watcher will fire next.
371 =item $timer = $timer->set ($tstamp)
373 Set the time the event is generated to $tstamp.
375 =item $timer = $timer->start
379 =item $timer = $timer->start ($tstamp)
381 Set the event trigger time to C<$tstamp> and start the timer.
383 =item $timer = $timer->stop
389 =head2 The C<urxvt::iow> Class
391 This class implements io watchers/events. Example:
393 $term->{socket} = ...
394 $term->{iow} = urxvt::iow
396 ->fd (fileno $term->{socket})
397 ->events (1) # wait for read data
400 my ($iow, $revents) = @_;
401 # $revents must be 1 here, no need to check
402 sysread $term->{socket}, my $buf, 8192
409 =item $iow = new urxvt::iow
411 Create a new io watcher object in stopped state.
413 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
415 Set the callback to be called when io events are triggered. C<$reventmask>
416 is a bitset as described in the C<events> method.
418 =item $iow = $iow->fd ($fd)
420 Set the filedescriptor (not handle) to watch.
422 =item $iow = $iow->events ($eventmask)
424 Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
425 data, Bit #1 (value C<2>) enables watching for write data.
427 =item $iow = $iow->start
429 Start watching for requested events on the given handle.
431 =item $iow = $iow->stop
433 Stop watching for events on the given filehandle.
439 =head2 URXVT_PERL_VERBOSITY
441 This variable controls the verbosity level of the perl extension. Higher
442 numbers indicate more verbose output.
446 =item 0 - only fatal messages
448 =item 3 - script loading and management
450 =item 10 - all events received
456 Marc Lehmann <pcg@goof.com>
457 http://software.schmorp.de/pkg/rxvt-unicode