rxvt-unicode/doc/rxvtperl.3.txt

NAME
    rxvtperl - rxvt-unicode's embedded perl interpreter

SYNOPSIS
       # create a file grab_test in $HOME:

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

       # start a rxvt using it:

       rxvt --perl-lib $HOME -pe grab_test

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

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

    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".

    on_keyboard_command $term, $string
        Called whenever the user presses a key combination that has a
        "perl:string" action bound to it (see description of the keysym
        resource in the rxvt(1) manpage).

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