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
    On startup, rxvt will scan /opt/rxvt/lib/urxvt/perl-ext/ for files and
    will load them. Everytime a terminal object gets created, the directory
    specified by the "perl-lib" resource will be additionally scanned.

    Each script will only ever be loaded once, even in rxvtd, where scripts
    will be shared for all terminals.

    Hooks in scripts specified by "perl-lib" will only be called for the
    terminals created with that specific option value.

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