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, 5 months ago) by root
Content type:	text/plain
Branch:	MAIN
Changes since 1.2:	+13 -7 lines
Log Message:	* empty log message *
#	Content
1	NAME
2	rxvtperl - rxvt-unicode's embedded perl interpreter
3
4	SYNOPSIS
5	# create a file grab_test in $HOME:
6
7	sub on_sel_grab {
8	warn "you selected ", $_[0]->selection;
9	()
10	}
11
12	# start a rxvt using it:
13
14	rxvt --perl-lib $HOME -pe grab_test
15
16	DESCRIPTION
17	Everytime a terminal object gets created, scripts specified via the
18	"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
23	Each script will only ever be loaded once, even in rxvtd, where scripts
24	will be shared (But not enabled) for all terminals.
25
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	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	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	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
163	mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
164	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