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, 5 months ago) by root
Content type:	text/plain
Branch:	MAIN
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			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