rxvt-unicode/doc/rxvtperl.3.txt

NAME
    rxvtperl - rxvt-unicode's embedded perl interpreter

SYNOPSIS
    * Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be
    loaded automatically.

    * Scripts are evaluated in a 'use strict' and 'use utf8' environment,
    and thus must be encoded as UTF-8.

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

       1

DESCRIPTION
    Everytime a terminal object gets created, scripts specified via the
    "perl" resource are associated with it.

    Each script will only ever be loaded once, even in rxvtd, where scripts
    will be shared (But not enabled) for all terminals.

  General API Considerations
    All objects (such as terminals, time watchers etc.) are typical
    reference-to-hash objects. The hash can be used to store anything you
    like. All members starting with an underscore (such as "_ptr" or
    "_hook") are reserved for internal uses and must not be accessed or
    modified).

    When objects are destroyed on the C++ side, the perl object hashes are
    emptied, so its best to store related objects such as time watchers and
    the like inside the terminal object so they get destroyed as soon as the
    terminal is destroyed.

  Hooks
    The following subroutines can be declared in loaded scripts, and will be
    called whenever the relevant event happens.

    All of them must return a boolean value. If it is true, then the event
    counts as being *consumed*, and the invocation of other hooks is
    skipped, and the relevant action might not be carried out by the C++
    code.

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

    on_init $term
        Called after a new terminal object has been initialized, but before
        windows are created or the command gets run.

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

    on_start $term
        Called at the very end of initialisation of a new terminal, just
        before returning to the mainloop.

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

        Returning a true value aborts selection making by urxvt, in which
        case you have to make a selection yourself by calling
        "$term->selection_grab".

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

        Returning a true value aborts selection grabbing. It will still be
        hilighted.

    on_focus_in $term
        Called whenever the window gets the keyboard focus, before urxvt
        does focus in processing.

    on_focus_out $term
        Called wheneever the window loses keyboard focus, before urxvt does
        focus out processing.

    on_view_change $term, $offset
        Called whenever the view offset changes, i..e the user or program
        scrolls. Offset 0 means display the normal terminal, positive values
        show this many lines of scrollback.

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

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

    on_tty_activity $term *NYI*
        Called whenever the program(s) running in the urxvt window send
        output.

    on_refresh_begin $term
        Called just before the screen gets redrawn. Can be used for overlay
        or similar effects by modify terminal contents in refresh_begin, and
        restoring them in refresh_end. The built-in overlay and selection
        display code is run after this hook, and takes precedence.

    on_refresh_end $term
        Called just after the screen gets redrawn. See "on_refresh_begin".

  Functions in the "urxvt" Package
    urxvt::fatal $errormessage
        Fatally aborts execution with the given error message. Avoid at all
        costs! The only time this is acceptable is when the terminal process
        starts up.

    urxvt::warn $string
        Calls "rxvt_warn" with the given string which should not include a
        newline. The module also overwrites the "warn" builtin with a
        function that calls this function.

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

    $time = urxvt::NOW
        Returns the "current time" (as per the event loop).

  The "urxvt::term" Class
    $value = $term->resource ($name[, $newval])
        Returns the current resource value associated with a given name and
        optionally sets a new value. Setting values is most useful in the
        "init" hook. Unset resources are returned and accepted as "undef".

        The new value must be properly encoded to a suitable character
        encoding before passing it to this method. Similarly, the returned
        value may need to be converted from the used encoding to text.

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

        Please note that resource strings will currently only be freed when
        the terminal is destroyed, so changing options frequently will eat
        memory.

        Here is a a likely non-exhaustive list of resource names, not all of
        which are supported in every build, please see the source to see the
        actual list:

          answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
          borderLess color cursorBlink cursorUnderline cutchars delete_key
          display_name embed ext_bwidth fade font geometry hold iconName
          imFont imLocale inputMethod insecure int_bwidth intensityStyles
          italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
          mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
          perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
          reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
          scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
          scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
          shade term_name title transparent transparent_all tripleclickwords
          utmpInhibit visualBell

    ($row, $col) = $term->selection_mark ([$row, $col])
    ($row, $col) = $term->selection_beg ([$row, $col])
    ($row, $col) = $term->selection_end ([$row, $col])
        Return the current values of the selection mark, begin or end
        positions, and optionally set them to new values.

    $success = $term->selection_grab ($eventtime)
        Try to request the primary selection from the server (for example,
        as set by the next method).

    $oldtext = $term->selection ([$newtext])
        Return the current selection text and optionally replace it by
        $newtext.

    $term->scr_overlay ($x, $y, $text)
        Create a simple multi-line overlay box. See the next method for
        details.

    $term->scr_overlay_new ($x, $y, $width, $height)
        Create a new (empty) overlay at the given position with the given
        width/height. A border will be put around the box. If either $x or
        $y is negative, then this is counted from the right/bottom side,
        respectively.

    $term->scr_overlay_off
        Switch the overlay off again.

    $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
        Put a single character (specified numerically) at the given overlay
        position.

    $term->scr_overlay_set ($x, $y, $text)
        Write a string at the given position into the overlay.

    $cellwidth = $term->strwidth $string
        Returns the number of screen-cells this string would need. Correctly
        accounts for wide and combining characters.

    $octets = $term->locale_encode $string
        Convert the given text string into the corresponding locale
        encoding.

    $string = $term->locale_decode $octets
        Convert the given locale-encoded octets into a perl string.

    $term->tt_write ($octets)
        Write the octets given in $data to the tty (i.e. as program input).
        To pass characters instead of octets, you should convetr you strings
        first to the locale-specific encoding using "$term->locale_encode".

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

       # create a digital clock display in upper right corner
       $term->{timer} = urxvt::timer
                        ->new
                        ->start (urxvt::NOW)
                        ->cb (sub {
                           my ($timer) = @_;
                           my $time = $timer->at;
                           $timer->start ($time + 1);
                           $self->scr_overlay (-1, 0, 
                              POSIX::strftime "%H:%M:%S", localtime $time);
                        });

    $timer = new urxvt::timer
        Create a new timer object in stopped state.

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

    $tstamp = $timer->at
        Return the time this watcher will fire next.

    $timer = $timer->set ($tstamp)
        Set the time the event is generated to $tstamp.

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

    $timer = $timer->start ($tstamp)
        Set the event trigger time to $tstamp and start the timer.

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

  The "urxvt::iow" Class
    This class implements io watchers/events. Example:

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

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

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

    $iow = $iow->fd ($fd)
        Set the filedescriptor (not handle) to watch.

    $iow = $iow->events ($eventmask)
        Set the event mask to watch. Bit #0 (value 1) enables watching for
        read data, Bit #1 (value 2) enables watching for write data.

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

    $iow = $iow->stop
        Stop watching for events on the given filehandle.

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

    0 - only fatal messages
    3 - script loading and management
    10 - all events received

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

Revision:	1.2
Committed:	Mon Jan 2 20:35:39 2006 UTC (18 years, 6 months ago) by root
Content type:	text/plain
Branch:	MAIN
Changes since 1.1:	+5 -9 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NAME
2			rxvtperl - rxvt-unicode's embedded perl interpreter
3
4			SYNOPSIS
5			* Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be
6			loaded automatically.
7
8			* Scripts are evaluated in a 'use strict' and 'use utf8' environment,
9			and thus must be encoded as UTF-8.
10
11			sub on_sel_grab {
12			warn "you selected ", $_[0]->selection;
13			()
14			}
15
16			1
17
18			DESCRIPTION
19	root	1.2	Everytime a terminal object gets created, scripts specified via the
20			"perl" resource are associated with it.
21	root	1.1
22			Each script will only ever be loaded once, even in rxvtd, where scripts
23	root	1.2	will be shared (But not enabled) for all terminals.
24	root	1.1
25			General API Considerations
26			All objects (such as terminals, time watchers etc.) are typical
27			reference-to-hash objects. The hash can be used to store anything you
28			like. All members starting with an underscore (such as "_ptr" or
29			"_hook") are reserved for internal uses and must not be accessed or
30			modified).
31
32			When objects are destroyed on the C++ side, the perl object hashes are
33			emptied, so its best to store related objects such as time watchers and
34			the like inside the terminal object so they get destroyed as soon as the
35			terminal is destroyed.
36
37			Hooks
38			The following subroutines can be declared in loaded scripts, and will be
39			called whenever the relevant event happens.
40
41			All of them must return a boolean value. If it is true, then the event
42			counts as being consumed, and the invocation of other hooks is
43			skipped, and the relevant action might not be carried out by the C++
44			code.
45
46			When in doubt, return a false value (preferably "()").
47
48			on_init $term
49			Called after a new terminal object has been initialized, but before
50			windows are created or the command gets run.
51
52			on_reset $term
53			Called after the screen is "reset" for any reason, such as resizing
54			or control sequences. Here is where you can react on changes to
55			size-related variables.
56
57			on_start $term
58			Called at the very end of initialisation of a new terminal, just
59			before returning to the mainloop.
60
61			on_sel_make $term, $eventtime
62			Called whenever a selection has been made by the user, but before
63			the selection text is copied, so changes to the beginning, end or
64			type of the selection will be honored.
65
66			Returning a true value aborts selection making by urxvt, in which
67			case you have to make a selection yourself by calling
68			"$term->selection_grab".
69
70			on_sel_grab $term, $eventtime
71			Called whenever a selection has been copied, but before the
72			selection is requested from the server. The selection text can be
73			queried and changed by calling "$term->selection".
74
75			Returning a true value aborts selection grabbing. It will still be
76			hilighted.
77
78			on_focus_in $term
79			Called whenever the window gets the keyboard focus, before urxvt
80			does focus in processing.
81
82			on_focus_out $term
83			Called wheneever the window loses keyboard focus, before urxvt does
84			focus out processing.
85
86			on_view_change $term, $offset
87			Called whenever the view offset changes, i..e the user or program
88			scrolls. Offset 0 means display the normal terminal, positive values
89			show this many lines of scrollback.
90
91			on_scroll_back $term, $lines, $saved
92			Called whenever lines scroll out of the terminal area into the
93			scrollback buffer. $lines is the number of lines scrolled out and
94			may be larger than the scroll back buffer or the terminal.
95
96			It is called before lines are scrolled out (so rows 0 .. min ($lines
97			- 1, $nrow - 1) represent the lines to be scrolled out). $saved is
98			the total number of lines that will be in the scrollback buffer.
99
100			on_tty_activity $term NYI
101			Called whenever the program(s) running in the urxvt window send
102			output.
103
104			on_refresh_begin $term
105			Called just before the screen gets redrawn. Can be used for overlay
106			or similar effects by modify terminal contents in refresh_begin, and
107			restoring them in refresh_end. The built-in overlay and selection
108			display code is run after this hook, and takes precedence.
109
110			on_refresh_end $term
111			Called just after the screen gets redrawn. See "on_refresh_begin".
112
113			Functions in the "urxvt" Package
114			urxvt::fatal $errormessage
115			Fatally aborts execution with the given error message. Avoid at all
116			costs! The only time this is acceptable is when the terminal process
117			starts up.
118
119			urxvt::warn $string
120			Calls "rxvt_warn" with the given string which should not include a
121			newline. The module also overwrites the "warn" builtin with a
122			function that calls this function.
123
124			Using this function has the advantage that its output ends up in the
125			correct place, e.g. on stderr of the connecting urxvtc client.
126
127			$time = urxvt::NOW
128			Returns the "current time" (as per the event loop).
129
130			The "urxvt::term" Class
131			$value = $term->resource ($name[, $newval])
132			Returns the current resource value associated with a given name and
133			optionally sets a new value. Setting values is most useful in the
134			"init" hook. Unset resources are returned and accepted as "undef".
135
136			The new value must be properly encoded to a suitable character
137			encoding before passing it to this method. Similarly, the returned
138			value may need to be converted from the used encoding to text.
139
140			Resource names are as defined in src/rsinc.h. Colours can be
141			specified as resource names of the form "color+<index>", e.g.
142			"color+5". (will likely change).
143
144			Please note that resource strings will currently only be freed when
145			the terminal is destroyed, so changing options frequently will eat
146			memory.
147
148			Here is a a likely non-exhaustive list of resource names, not all of
149			which are supported in every build, please see the source to see the
150			actual list:
151
152			answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
153			borderLess color cursorBlink cursorUnderline cutchars delete_key
154			display_name embed ext_bwidth fade font geometry hold iconName
155			imFont imLocale inputMethod insecure int_bwidth intensityStyles
156	root	1.2	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
157			mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
158	root	1.1	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
159			reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
160			scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
161			scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
162			shade term_name title transparent transparent_all tripleclickwords
163			utmpInhibit visualBell
164
165			($row, $col) = $term->selection_mark ([$row, $col])
166			($row, $col) = $term->selection_beg ([$row, $col])
167			($row, $col) = $term->selection_end ([$row, $col])
168			Return the current values of the selection mark, begin or end
169			positions, and optionally set them to new values.
170
171			$success = $term->selection_grab ($eventtime)
172			Try to request the primary selection from the server (for example,
173			as set by the next method).
174
175			$oldtext = $term->selection ([$newtext])
176			Return the current selection text and optionally replace it by
177			$newtext.
178
179			$term->scr_overlay ($x, $y, $text)
180			Create a simple multi-line overlay box. See the next method for
181			details.
182
183			$term->scr_overlay_new ($x, $y, $width, $height)
184			Create a new (empty) overlay at the given position with the given
185			width/height. A border will be put around the box. If either $x or
186			$y is negative, then this is counted from the right/bottom side,
187			respectively.
188
189			$term->scr_overlay_off
190			Switch the overlay off again.
191
192			$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
193			Put a single character (specified numerically) at the given overlay
194			position.
195
196			$term->scr_overlay_set ($x, $y, $text)
197			Write a string at the given position into the overlay.
198
199			$cellwidth = $term->strwidth $string
200			Returns the number of screen-cells this string would need. Correctly
201			accounts for wide and combining characters.
202
203			$octets = $term->locale_encode $string
204			Convert the given text string into the corresponding locale
205			encoding.
206
207			$string = $term->locale_decode $octets
208			Convert the given locale-encoded octets into a perl string.
209
210			$term->tt_write ($octets)
211			Write the octets given in $data to the tty (i.e. as program input).
212			To pass characters instead of octets, you should convetr you strings
213			first to the locale-specific encoding using "$term->locale_encode".
214
215			The "urxvt::timer" Class
216			This class implements timer watchers/events. Time is represented as a
217			fractional number of seconds since the epoch. Example:
218
219			# create a digital clock display in upper right corner
220			$term->{timer} = urxvt::timer
221			->new
222			->start (urxvt::NOW)
223			->cb (sub {
224			my ($timer) = @_;
225			my $time = $timer->at;
226			$timer->start ($time + 1);
227			$self->scr_overlay (-1, 0,
228			POSIX::strftime "%H:%M:%S", localtime $time);
229			});
230
231			$timer = new urxvt::timer
232			Create a new timer object in stopped state.
233
234			$timer = $timer->cb (sub { my ($timer) = @_; ... })
235			Set the callback to be called when the timer triggers.
236
237			$tstamp = $timer->at
238			Return the time this watcher will fire next.
239
240			$timer = $timer->set ($tstamp)
241			Set the time the event is generated to $tstamp.
242
243			$timer = $timer->start
244			Start the timer.
245
246			$timer = $timer->start ($tstamp)
247			Set the event trigger time to $tstamp and start the timer.
248
249			$timer = $timer->stop
250			Stop the timer.
251
252			The "urxvt::iow" Class
253			This class implements io watchers/events. Example:
254
255			$term->{socket} = ...
256			$term->{iow} = urxvt::iow
257			->new
258			->fd (fileno $term->{socket})
259			->events (1) # wait for read data
260			->start
261			->cb (sub {
262			my ($iow, $revents) = @_;
263			# $revents must be 1 here, no need to check
264			sysread $term->{socket}, my $buf, 8192
265			or end-of-file;
266			});
267
268			$iow = new urxvt::iow
269			Create a new io watcher object in stopped state.
270
271			$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
272			Set the callback to be called when io events are triggered.
273			$reventmask is a bitset as described in the "events" method.
274
275			$iow = $iow->fd ($fd)
276			Set the filedescriptor (not handle) to watch.
277
278			$iow = $iow->events ($eventmask)
279			Set the event mask to watch. Bit #0 (value 1) enables watching for
280			read data, Bit #1 (value 2) enables watching for write data.
281
282			$iow = $iow->start
283			Start watching for requested events on the given handle.
284
285			$iow = $iow->stop
286			Stop watching for events on the given filehandle.
287
288			ENVIRONMENT
289			URXVT_PERL_VERBOSITY
290			This variable controls the verbosity level of the perl extension. Higher
291			numbers indicate more verbose output.
292
293			0 - only fatal messages
294			3 - script loading and management
295			10 - all events received
296
297			AUTHOR
298			Marc Lehmann <pcg@goof.com>
299			http://software.schmorp.de/pkg/rxvt-unicode
300