ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvtperl.3.txt
(Generate patch)

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.1 by root, Mon Jan 2 19:36:07 2006 UTC vs.
Revision 1.10 by root, Wed Jan 4 05:35:34 2006 UTC

1NAME 1NAME
2 rxvtperl - rxvt-unicode's embedded perl interpreter 2 rxvtperl - rxvt-unicode's embedded perl interpreter
3 3
4SYNOPSIS 4SYNOPSIS
5 * Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be 5 # create a file grab_test in $HOME:
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 6
11 sub on_sel_grab { 7 sub on_sel_grab {
12 warn "you selected ", $_[0]->selection; 8 warn "you selected ", $_[0]->selection;
13 () 9 ()
14 } 10 }
15 11
16 1 12 # start a rxvt using it:
13
14 rxvt --perl-lib $HOME -pe grab_test
17 15
18DESCRIPTION 16DESCRIPTION
19 On startup, rxvt will scan /opt/rxvt/lib/urxvt/perl-ext/ for files and 17 Everytime a terminal object gets created, scripts specified via the
20 will load them. Everytime a terminal object gets created, the directory 18 "perl" resource are loaded and associated with it.
21 specified by the "perl-lib" resource will be additionally scanned. 19
20 Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21 thus must be encoded as UTF-8.
22 22
23 Each script will only ever be loaded once, even in rxvtd, where scripts 23 Each script will only ever be loaded once, even in rxvtd, where scripts
24 will be shared for all terminals. 24 will be shared (but not enabled) for all terminals.
25 25
26 Hooks in scripts specified by "perl-lib" will only be called for the 26 Prepackaged Extensions
27 terminals created with that specific option value. 27 This section describes the extensiosn delivered with this version. You
28 can find them in /opt/rxvt/lib/urxvt/perl/.
29
30 You can activate them like this:
31
32 rxvt -pe <extensionname>
33
34 selection
35 Intelligent selection. This extension tries to be more intelligent
36 when the user extends selections (double-click). Right now, it tries
37 to select urls and complete shell-quoted arguments, which is very
38 convenient, too, if your ls supports "--quoting-style=shell".
39
40 It also offers the following bindable event:
41
42 rot13
43 Rot-13 the selection when activated. Used via keyboard trigger:
44
45 URxvt.keysym.C-M-r: perl:selection:rot13
46
47 digital-clock
48 Displays a digital clock using the built-in overlay.
49
50 example-refresh-hooks
51 Displays a very simple digital clock in the upper right corner of
52 the window. Illustrates overwriting the refresh callbacks to create
53 your own overlays or changes.
28 54
29 General API Considerations 55 General API Considerations
30 All objects (such as terminals, time watchers etc.) are typical 56 All objects (such as terminals, time watchers etc.) are typical
31 reference-to-hash objects. The hash can be used to store anything you 57 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 58 like. All members starting with an underscore (such as "_ptr" or
33 "_hook") are reserved for internal uses and must not be accessed or 59 "_hook") are reserved for internal uses and MUST NOT be accessed or
34 modified). 60 modified).
35 61
36 When objects are destroyed on the C++ side, the perl object hashes are 62 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 63 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 64 the like inside the terminal object so they get destroyed as soon as the
… …
40 66
41 Hooks 67 Hooks
42 The following subroutines can be declared in loaded scripts, and will be 68 The following subroutines can be declared in loaded scripts, and will be
43 called whenever the relevant event happens. 69 called whenever the relevant event happens.
44 70
71 The first argument passed to them is an object private to each terminal
72 and extension package. You can call all "urxvt::term" methods on it, but
73 its not a real "urxvt::term" object. Instead, the real "urxvt::term"
74 object that is shared between all packages is stored in the "term"
75 member.
76
45 All of them must return a boolean value. If it is true, then the event 77 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 78 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++ 79 skipped, and the relevant action might not be carried out by the C++
48 code. 80 code.
49 81
… …
77 queried and changed by calling "$term->selection". 109 queried and changed by calling "$term->selection".
78 110
79 Returning a true value aborts selection grabbing. It will still be 111 Returning a true value aborts selection grabbing. It will still be
80 hilighted. 112 hilighted.
81 113
114 on_sel_extend $term
115 Called whenever the user tries to extend the selection (e.g. with a
116 double click) and is either supposed to return false (normal
117 operation), or should extend the selection itelf and return true to
118 suppress the built-in processing.
119
120 See the selection example extension.
121
82 on_focus_in $term 122 on_focus_in $term
83 Called whenever the window gets the keyboard focus, before urxvt 123 Called whenever the window gets the keyboard focus, before urxvt
84 does focus in processing. 124 does focus in processing.
85 125
86 on_focus_out $term 126 on_focus_out $term
… …
102 the total number of lines that will be in the scrollback buffer. 142 the total number of lines that will be in the scrollback buffer.
103 143
104 on_tty_activity $term *NYI* 144 on_tty_activity $term *NYI*
105 Called whenever the program(s) running in the urxvt window send 145 Called whenever the program(s) running in the urxvt window send
106 output. 146 output.
147
148 on_osc_seq $term, $string
149 Called whenever the ESC ] 777 ; string ST command sequence (OSC =
150 operating system command) is processed. Cursor position and other
151 state information is up-to-date when this happens. For
152 interoperability, the string should start with the extension name
153 and a colon, to distinguish it from commands for other extensions,
154 and this might be enforced in the future.
155
156 Be careful not ever to trust (in a security sense) the data you
157 receive, as its source can not easily be controleld (e-mail content,
158 messages from other users on the same system etc.).
107 159
108 on_refresh_begin $term 160 on_refresh_begin $term
109 Called just before the screen gets redrawn. Can be used for overlay 161 Called just before the screen gets redrawn. Can be used for overlay
110 or similar effects by modify terminal contents in refresh_begin, and 162 or similar effects by modify terminal contents in refresh_begin, and
111 restoring them in refresh_end. The built-in overlay and selection 163 restoring them in refresh_end. The built-in overlay and selection
112 display code is run after this hook, and takes precedence. 164 display code is run after this hook, and takes precedence.
113 165
114 on_refresh_end $term 166 on_refresh_end $term
115 Called just after the screen gets redrawn. See "on_refresh_begin". 167 Called just after the screen gets redrawn. See "on_refresh_begin".
116 168
169 on_keyboard_command $term, $string
170 Called whenever the user presses a key combination that has a
171 "perl:string" action bound to it (see description of the keysym
172 resource in the rxvt(1) manpage).
173
174 Variables in the "urxvt" Package
175 $urxvt::TERM
176 The current terminal. Whenever a callback/Hook is bein executed,
177 this variable stores the current "urxvt::term" object.
178
117 Functions in the "urxvt" Package 179 Functions in the "urxvt" Package
118 urxvt::fatal $errormessage 180 urxvt::fatal $errormessage
119 Fatally aborts execution with the given error message. Avoid at all 181 Fatally aborts execution with the given error message. Avoid at all
120 costs! The only time this is acceptable is when the terminal process 182 costs! The only time this is acceptable is when the terminal process
121 starts up. 183 starts up.
… …
129 correct place, e.g. on stderr of the connecting urxvtc client. 191 correct place, e.g. on stderr of the connecting urxvtc client.
130 192
131 $time = urxvt::NOW 193 $time = urxvt::NOW
132 Returns the "current time" (as per the event loop). 194 Returns the "current time" (as per the event loop).
133 195
196 RENDITION
197 Rendition bitsets contain information about colour, font, font styles
198 and similar information for each screen cell.
199
200 The following "macros" deal with changes in rendition sets. You should
201 never just create a bitset, you should always modify an existing one, as
202 they contain important information required for correct operation of
203 rxvt-unicode.
204
205 $rend = urxvt::DEFAULT_RSTYLE
206 Returns the default rendition, as used when the terminal is starting
207 up or being reset. Useful as a base to start when creating
208 renditions.
209
210 $rend = urxvt::OVERLAY_RSTYLE
211 Return the rendition mask used for overlays by default.
212
213 $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
214 Return the bit that enabled bold, italic, blink, reverse-video and
215 underline, respectively. To enable such a style, just logically OR
216 it into the bitset.
217
218 $foreground = urxvt::GET_BASEFG $rend
219 $background = urxvt::GET_BASEBG $rend
220 Return the foreground/background colour index, respectively.
221
222 $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
223 $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
224 Replace the foreground/background colour in the rendition mask with
225 the specified one.
226
227 $value = urxvt::GET_CUSTOM ($rend)
228 Return the "custom" value: Every rendition has 5 bits for use by
229 extensions. They can be set and changed as you like and are
230 initially zero.
231
232 $rend = urxvt::SET_CUSTOM ($rend, $new_value)
233 Change the custom value.
234
134 The "urxvt::term" Class 235 The "urxvt::term" Class
135 $value = $term->resource ($name[, $newval]) 236 $value = $term->resource ($name[, $newval])
136 Returns the current resource value associated with a given name and 237 Returns the current resource value associated with a given name and
137 optionally sets a new value. Setting values is most useful in the 238 optionally sets a new value. Setting values is most useful in the
138 "init" hook. Unset resources are returned and accepted as "undef". 239 "init" hook. Unset resources are returned and accepted as "undef".
… …
155 256
156 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 257 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
157 borderLess color cursorBlink cursorUnderline cutchars delete_key 258 borderLess color cursorBlink cursorUnderline cutchars delete_key
158 display_name embed ext_bwidth fade font geometry hold iconName 259 display_name embed ext_bwidth fade font geometry hold iconName
159 imFont imLocale inputMethod insecure int_bwidth intensityStyles 260 imFont imLocale inputMethod insecure int_bwidth intensityStyles
160 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 261 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
161 modifier mouseWheelScrollPage name pastableTabs path perl perl_eval 262 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
162 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 263 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
163 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 264 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
164 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 265 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
165 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 266 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
166 shade term_name title transparent transparent_all tripleclickwords 267 shade term_name title transparent transparent_all tripleclickwords
… …
178 279
179 $oldtext = $term->selection ([$newtext]) 280 $oldtext = $term->selection ([$newtext])
180 Return the current selection text and optionally replace it by 281 Return the current selection text and optionally replace it by
181 $newtext. 282 $newtext.
182 283
183 $term->scr_overlay ($x, $y, $text) 284 #=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
184 Create a simple multi-line overlay box. See the next method for 285 overlay box. See the next method for details. # #=cut
185 details.
186 286
187 $term->scr_overlay_new ($x, $y, $width, $height) 287 sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
288
289 my @lines = split /\n/, $text;
290
291 my $w = 0;
292 for (map $self->strwidth ($_), @lines) {
293 $w = $_ if $w < $_;
294 }
295
296 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
297 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
298 }
299
300 $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
188 Create a new (empty) overlay at the given position with the given 301 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 302 width/height. $rstyle defines the initial rendition style (default:
303 "OVERLAY_RSTYLE").
304
305 If $border is 2 (default), then a decorative border will be put
306 around the box.
307
190 $y is negative, then this is counted from the right/bottom side, 308 If either $x or $y is negative, then this is counted from the
191 respectively. 309 right/bottom side, respectively.
192 310
193 $term->scr_overlay_off 311 This method returns an urxvt::overlay object. The overlay will be
194 Switch the overlay off again. 312 visible as long as the perl object is referenced.
195 313
196 $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 314 The methods currently supported on "urxvt::overlay" objects are:
197 Put a single character (specified numerically) at the given overlay
198 position.
199 315
200 $term->scr_overlay_set ($x, $y, $text) 316 $overlay->set ($x, $y, $text, $rend)
201 Write a string at the given position into the overlay. 317 Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
318 text in rxvt-unicode's special encoding and an array of
319 rendition values at a specific position inside the overlay.
320
321 $overlay->hide
322 If visible, hide the overlay, but do not destroy it.
323
324 $overlay->show
325 If hidden, display the overlay again.
202 326
203 $cellwidth = $term->strwidth $string 327 $cellwidth = $term->strwidth $string
204 Returns the number of screen-cells this string would need. Correctly 328 Returns the number of screen-cells this string would need. Correctly
205 accounts for wide and combining characters. 329 accounts for wide and combining characters.
206 330
… …
211 $string = $term->locale_decode $octets 335 $string = $term->locale_decode $octets
212 Convert the given locale-encoded octets into a perl string. 336 Convert the given locale-encoded octets into a perl string.
213 337
214 $term->tt_write ($octets) 338 $term->tt_write ($octets)
215 Write the octets given in $data to the tty (i.e. as program input). 339 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 340 To pass characters instead of octets, you should convert your
217 first to the locale-specific encoding using "$term->locale_encode". 341 strings first to the locale-specific encoding using
342 "$term->locale_encode".
343
344 $nrow = $term->nrow
345 $ncol = $term->ncol
346 Return the number of rows/columns of the terminal window (i.e. as
347 specified by "-geometry", excluding any scrollback).
348
349 $nsaved = $term->nsaved
350 Returns the number of lines in the scrollback buffer.
351
352 $view_start = $term->view_start ([$newvalue])
353 Returns the negative row number of the topmost line. Minimum value
354 is 0, which displays the normal terminal contents. Larger values
355 scroll this many lines into the scrollback buffer.
356
357 $term->want_refresh
358 Requests a screen refresh. At the next opportunity, rxvt-unicode
359 will compare the on-screen display with its stored representation.
360 If they differ, it redraws the differences.
361
362 Used after changing terminal contents to display them.
363
364 $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
365 Returns the text of the entire row with number $row_number. Row 0 is
366 the topmost terminal line, row "$term->$ncol-1" is the bottommost
367 terminal line. The scrollback buffer starts at line -1 and extends
368 to line "-$term->nsaved". Nothing will be returned if a nonexistent
369 line is requested.
370
371 If $new_text is specified, it will replace characters in the current
372 line, starting at column $start_col (default 0), which is useful to
373 replace only parts of a line. The font index in the rendition will
374 automatically be updated.
375
376 $text is in a special encoding: tabs and wide characters that use
377 more than one cell when displayed are padded with urxvt::NOCHAR
378 characters ("chr 65535"). Characters with combining characters and
379 other characters that do not fit into the normal tetx encoding will
380 be replaced with characters in the private use area.
381
382 You have to obey this encoding when changing text. The advantage is
383 that "substr" and similar functions work on screen cells and not on
384 characters.
385
386 The methods "$term->special_encode" and "$term->special_decode" can
387 be used to convert normal strings into this encoding and vice versa.
388
389 $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
390 Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
391 Rendition bitsets contain information about colour, font, font
392 styles and similar information. See also "$term->ROW_t".
393
394 When setting rendition, the font mask will be ignored.
395
396 See the section on RENDITION, above.
397
398 $length = $term->ROW_l ($row_number[, $new_length])
399 Returns the number of screen cells that are in use ("the line
400 length"). Unlike the urxvt core, this returns "$term->ncol" if the
401 line is joined with the following one.
402
403 $bool = $term->is_longer ($row_number)
404 Returns true if the row is part of a multiple-row logical "line"
405 (i.e. joined with the following row), which means all characters are
406 in use and it is continued on the next row (and possibly a
407 continuation of the previous row(s)).
408
409 $line = $term->line ($row_number)
410 Create and return a new "urxvt::line" object that stores information
411 about the logical line that row $row_number is part of. It supports
412 the following methods:
413
414 $text = $line->t
415 Returns the full text of the line, similar to "ROW_t"
416
417 $rend = $line->r
418 Returns the full rendition array of the line, similar to "ROW_r"
419
420 $length = $line->l
421 Returns the length of the line in cells, similar to "ROW_l".
422
423 $rownum = $line->beg
424 $rownum = $line->end
425 Return the row number of the first/last row of the line,
426 respectively.
427
428 $offset = $line->offset_of ($row, $col)
429 Returns the character offset of the given row|col pair within
430 the logical line.
431
432 ($row, $col) = $line->coord_of ($offset)
433 Translates a string offset into terminal coordinates again.
434
435 ($row, $col) = $line->coord_of ($offset) =item $text =
436 $term->special_encode $string
437 Converts a perl string into the special encoding used by
438 rxvt-unicode, where one character corresponds to one screen cell.
439 See "$term->ROW_t" for details.
440
441 $string = $term->special_decode $text
442 Converts rxvt-unicodes text reprsentation into a perl string. See
443 "$term->ROW_t" for details.
218 444
219 The "urxvt::timer" Class 445 The "urxvt::timer" Class
220 This class implements timer watchers/events. Time is represented as a 446 This class implements timer watchers/events. Time is represented as a
221 fractional number of seconds since the epoch. Example: 447 fractional number of seconds since the epoch. Example:
222 448
223 # create a digital clock display in upper right corner 449 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
224 $term->{timer} = urxvt::timer 450 $term->{timer} = urxvt::timer
225 ->new 451 ->new
226 ->start (urxvt::NOW) 452 ->interval (1)
227 ->cb (sub { 453 ->cb (sub {
228 my ($timer) = @_;
229 my $time = $timer->at;
230 $timer->start ($time + 1);
231 $self->scr_overlay (-1, 0, 454 $term->{overlay}->set (0, 0,
232 POSIX::strftime "%H:%M:%S", localtime $time); 455 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
233 }); 456 });
234 457
235 $timer = new urxvt::timer 458 $timer = new urxvt::timer
236 Create a new timer object in stopped state. 459 Create a new timer object in started state. It is scheduled to fire
460 immediately.
237 461
238 $timer = $timer->cb (sub { my ($timer) = @_; ... }) 462 $timer = $timer->cb (sub { my ($timer) = @_; ... })
239 Set the callback to be called when the timer triggers. 463 Set the callback to be called when the timer triggers.
240 464
241 $tstamp = $timer->at 465 $tstamp = $timer->at
242 Return the time this watcher will fire next. 466 Return the time this watcher will fire next.
243 467
244 $timer = $timer->set ($tstamp) 468 $timer = $timer->set ($tstamp)
245 Set the time the event is generated to $tstamp. 469 Set the time the event is generated to $tstamp.
470
471 $timer = $timer->interval ($interval)
472 Normally (and when $interval is 0), the timer will automatically
473 stop after it has fired once. If $interval is non-zero, then the
474 timer is automatically rescheduled at the given intervals.
246 475
247 $timer = $timer->start 476 $timer = $timer->start
248 Start the timer. 477 Start the timer.
249 478
250 $timer = $timer->start ($tstamp) 479 $timer = $timer->start ($tstamp)
… …
292ENVIRONMENT 521ENVIRONMENT
293 URXVT_PERL_VERBOSITY 522 URXVT_PERL_VERBOSITY
294 This variable controls the verbosity level of the perl extension. Higher 523 This variable controls the verbosity level of the perl extension. Higher
295 numbers indicate more verbose output. 524 numbers indicate more verbose output.
296 525
297 0 - only fatal messages 526 =0 - only fatal messages
298 3 - script loading and management 527 =3 - script loading and management
299 10 - all events received 528 =10 - all events received
300 529
301AUTHOR 530AUTHOR
302 Marc Lehmann <pcg@goof.com> 531 Marc Lehmann <pcg@goof.com>
303 http://software.schmorp.de/pkg/rxvt-unicode 532 http://software.schmorp.de/pkg/rxvt-unicode
304 533

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines