3 urxvt - rxvt-unicode's embedded perl interpreter
7 Put your scripts into $LIBDIR/perl-init/, 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 written in utf-8.
16 warn "you selected ", $_[0]->selection;
25 The following subroutines can be declared in loaded scripts, and will be called
26 whenever the relevant event happens.
28 All of them must return a boolean value. If it is true, then the event
29 counts as being I<consumed>, and the invocation of other hooks is skipped,
30 and the relevant action might not be carried out by the C++ code.
32 When in doubt, return a false value (preferably C<()>).
38 Called after a new terminal object has been initialized, but before
39 windows are created or the command gets run.
43 Called after the screen is "reset" for any reason, such as resizing or
44 control sequences. Here is where you can react on changes to size-related
49 Called at the very end of initialisation of a new terminal, just before
50 returning to the mainloop.
52 =item on_sel_make $term, $eventtime
54 Called whenever a selection has been made by the user, but before the
55 selection text is copied, so changes to the beginning, end or type of the
56 selection will be honored.
58 Returning a true value aborts selection making by urxvt, in which case you
59 have to make a selection yourself by calling C<< $term->selection_grab >>.
61 =item on_sel_grab $term, $eventtime
63 Called whenever a selection has been copied, but before the selection is
64 requested from the server. The selection text can be queried and changed
65 by calling C<< $term->selection >>.
67 Returning a true value aborts selection grabbing. It will still be hilighted.
69 =item on_focus_in $term
71 Called whenever the window gets the keyboard focus, before urxvt does
74 =item on_focus_out $term
76 Called wheneever the window loses keyboard focus, before urxvt does focus
79 =item on_view_change $term, $offset
81 Called whenever the view offset changes, i..e the user or program
82 scrolls. Offset C<0> means display the normal terminal, positive values
83 show this many lines of scrollback.
85 =item on_scroll_back $term, $lines, $saved
87 Called whenever lines scroll out of the terminal area into the scrollback
88 buffer. C<$lines> is the number of lines scrolled out and may be larger
89 than the scroll back buffer or the terminal.
91 It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
92 $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
93 number of lines that will be in the scrollback buffer.
95 =item on_tty_activity $term *NYI*
97 Called whenever the program(s) running in the urxvt window send output.
99 =item on_refresh_begin $term
101 Called just before the screen gets redrawn. Can be used for overlay
102 or similar effects by modify terminal contents in refresh_begin, and
103 restoring them in refresh_end. The built-in overlay and selection display
104 code is run after this hook, and takes precedence.
106 =item on_refresh_end $term
108 Called just after the screen gets redrawn. See C<on_refresh_begin>.
112 =head2 Functions in the C<urxvt> Package
116 =item urxvt::fatal $errormessage
118 Fatally aborts execution with the given error message. Avoid at all
119 costs! The only time this is acceptable is when the terminal process
122 =item urxvt::warn $string
124 Calls C<rxvt_warn> witht eh given string which should not include a
125 newline. The module also overwrites the C<warn> builtin with a function
126 that calls this function.
128 Using this function has the advantage that its output ends up in the
129 correct place, e.g. on stderr of the connecting urxvtc client.
131 =item $cellwidth = urxvt::wcswidth $string
133 Returns the number of screen-cells this string would need. Correctly
134 accounts for wide and combining characters.
136 =item $time = urxvt::NOW
138 Returns the "current time" (as per the event loop).
153 # overwrite perl's warn
154 *CORE::GLOBAL::warn = sub {
155 my $msg = join "", @_;
157 unless $msg =~ /\n$/;
162 my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10;
165 my ($level, $msg) = @_;
171 # called by the rxvt core
176 my $cb = $invoke_cb[$htype];
178 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
181 while (my ($k, $v) = each %$cb) {
182 return 1 if $v->($term, @_);
188 # find on_xxx subs in the package and register them
190 sub register_package($) {
193 for my $hook (0.. $#HOOKNAME) {
194 my $name = $HOOKNAME[$hook];
196 my $ref = $pkg->can ("on_" . lc $name)
199 $invoke_cb[$hook]{$ref*1} = $ref;
200 set_should_invoke $hook, 1;
204 my $script_pkg = "script0000";
207 # load a single script into its own package, once only
211 $script_pkg{$path} ||= do {
212 my $pkg = $script_pkg++;
213 verbose 3, "loading script '$path' into package '$pkg'";
215 open my $fh, "<:raw", $path
218 eval "package $pkg; use strict; use utf8;\n"
219 . "#line 1 \"$path\"\n"
220 . do { local $/; <$fh> }
223 register_package $pkg;
229 load_script $_ for grep -f $_, <$LIBDIR/perl-ext/*>;
234 =head2 The C<urxvt::term> Class
238 =item ($row, $col) = $term->selection_mark ([$row, $col])
240 =item ($row, $col) = $term->selection_beg ([$row, $col])
242 =item ($row, $col) = $term->selection_end ([$row, $col])
244 Return the current values of the selection mark, begin or end positions,
245 and optionally set them to new values.
247 =item $success = $term->selection_grab ($eventtime)
249 Try to request the primary selection from the server (for example, as set
252 =item $oldtext = $term->selection ([$newtext])
254 Return the current selection text and optionally replace it by C<$newtext>.
256 =item $term->scr_overlay ($x, $y, $text)
258 Create a simple multi-line overlay box. See the next method for details.
262 sub urxvt::term::scr_overlay {
263 my ($self, $x, $y, $text) = @_;
265 my @lines = split /\n/, $text;
268 for (map urxvt::wcswidth $_, @lines) {
272 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
273 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
276 =item $term->scr_overlay_new ($x, $y, $width, $height)
278 Create a new (empty) overlay at the given position with the given
279 width/height. A border will be put around the box. If either C<$x> or
280 C<$y> is negative, then this is counted from the right/bottom side,
283 =item $term->scr_overlay_off
285 Switch the overlay off again.
287 =item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
289 Put a single character (specified numerically) at the given overlay
292 =item $term->scr_overlay_set ($x, $y, $text)
294 Write a string at the given position into the overlay.
298 =head2 The C<urxvt::timer> Class
300 This class implements timer watchers/events. Time is represented as a
301 fractional number of seconds since the epoch. Example:
303 # create a digital clock display in upper right corner
304 $term->{timer} = urxvt::timer
309 my $time = $timer->at;
310 $timer->start ($time + 1);
311 $self->scr_overlay (-1, 0,
312 POSIX::strftime "%H:%M:%S", localtime $time);
317 =item $timer = new urxvt::timer
319 Create a new timer object in stopped state.
321 =item $timer = $timer->cb (sub { my ($timer) = @_; ... })
323 Set the callback to be called when the timer triggers.
325 =item $tstamp = $timer->at
327 Return the time this watcher will fire next.
329 =item $timer = $timer->set ($tstamp)
331 Set the time the event is generated to $tstamp.
333 =item $timer = $timer->start
337 =item $timer = $timer->start ($tstamp)
339 Set the event trigger time to C<$tstamp> and start the timer.
341 =item $timer = $timer->stop
347 =head2 The C<urxvt::iow> Class
349 This class implements io watchers/events. Example:
351 $term->{socket} = ...
352 $term->{iow} = urxvt::iow
354 ->fd (fileno $term->{socket})
355 ->events (1) # wait for read data
358 my ($iow, $revents) = @_;
359 # $revents must be 1 here, no need to check
360 sysread $term->{socket}, my $buf, 8192
367 =item $iow = new urxvt::iow
369 Create a new io watcher object in stopped state.
371 =item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
373 Set the callback to be called when io events are triggered. C<$reventmask>
374 is a bitset as described in the C<events> method.
376 =item $iow = $iow->fd ($fd)
378 Set the filedescriptor (not handle) to watch.
380 =item $iow = $iow->events ($eventmask)
382 Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
383 data, Bit #1 (value C<2>) enables watching for write data.
385 =item $iow = $iow->start
387 Start watching for requested events on the given handle.
389 =item $iow = $iow->stop
391 Stop watching for events on the given filehandle.
397 Marc Lehmann <pcg@goof.com>
398 http://software.schmorp.de/pkg/rxvt-unicode