ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.3 by root, Mon Jan 2 15:59:25 2006 UTC vs.
Revision 1.21 by root, Tue Jan 3 04:20:37 2006 UTC

1=encoding utf8
2
1=head1 NAME 3=head1 NAME
2 4
3rxvtperl - rxvt-unicode's embedded perl interpreter 5@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
6 8
7* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically. 9 # create a file grab_test in $HOME:
8
9* Each script will only be loaded once, even in urxvtd, and will be valid
10globally.
11
12* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
13thus must be encoded as UTF-8.
14 10
15 sub on_sel_grab { 11 sub on_sel_grab {
16 warn "you selected ", $_[0]->selection; 12 warn "you selected ", $_[0]->selection;
17 () 13 ()
18 } 14 }
19 15
20 1 16 # start a @@RXVT_NAME@@ using it:
17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
21 19
22=head1 DESCRIPTION 20=head1 DESCRIPTION
21
22Everytime a terminal object gets created, scripts specified via the
23C<perl> resource are loaded and associated with it.
24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8.
27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals.
30
31=head2 Prepackaged Extensions
32
33This section describes the extensiosn delivered with this version. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35
36You can activate them like this:
37
38 @@RXVT_NAME@@ -pe <extensionname>
39
40=over 4
41
42=item selection
43
44Miscellaneous selection modifications.
45
46=over 4
47
48=item rot13
49
50Rot-13 the selection when activated. Used via keyboard trigger:
51
52 URxvt.keysym.C-M-r: perl:selection:rot13
53
54=back
55
56=item digital-clock
57
58Displays a digital clock using the built-in overlay.
59
60=item example-refresh-hooks
61
62Displays a very simple digital clock in the upper right corner of the
63window. Illustrates overwriting the refresh callbacks to create your own
64overlays or changes.
65
66=back
67
68=head2 General API Considerations
69
70All objects (such as terminals, time watchers etc.) are typical
71reference-to-hash objects. The hash can be used to store anything you
72like. All members starting with an underscore (such as C<_ptr> or
73C<_hook>) are reserved for internal uses and must not be accessed or
74modified).
75
76When objects are destroyed on the C++ side, the perl object hashes are
77emptied, so its best to store related objects such as time watchers and
78the like inside the terminal object so they get destroyed as soon as the
79terminal is destroyed.
23 80
24=head2 Hooks 81=head2 Hooks
25 82
26The following subroutines can be declared in loaded scripts, and will be called 83The following subroutines can be declared in loaded scripts, and will be called
27whenever the relevant event happens. 84whenever the relevant event happens.
106 163
107=item on_refresh_end $term 164=item on_refresh_end $term
108 165
109Called just after the screen gets redrawn. See C<on_refresh_begin>. 166Called just after the screen gets redrawn. See C<on_refresh_begin>.
110 167
168=item on_keyboard_command $term, $string
169
170Called whenever the user presses a key combination that has a
171C<perl:string> action bound to it (see description of the B<keysym>
172resource in the @@RXVT_NAME@@(1) manpage).
173
111=back 174=back
112 175
113=head2 Functions in the C<urxvt> Package 176=head2 Functions in the C<urxvt> Package
114 177
115=over 4 178=over 4
120costs! The only time this is acceptable is when the terminal process 183costs! The only time this is acceptable is when the terminal process
121starts up. 184starts up.
122 185
123=item urxvt::warn $string 186=item urxvt::warn $string
124 187
125Calls C<rxvt_warn> witht eh given string which should not include a 188Calls C<rxvt_warn> with the given string which should not include a
126newline. The module also overwrites the C<warn> builtin with a function 189newline. The module also overwrites the C<warn> builtin with a function
127that calls this function. 190that calls this function.
128 191
129Using this function has the advantage that its output ends up in the 192Using this function has the advantage that its output ends up in the
130correct place, e.g. on stderr of the connecting urxvtc client. 193correct place, e.g. on stderr of the connecting urxvtc client.
131 194
132=item $cellwidth = urxvt::wcswidth $string
133
134Returns the number of screen-cells this string would need. Correctly
135accounts for wide and combining characters.
136
137=item $time = urxvt::NOW 195=item $time = urxvt::NOW
138 196
139Returns the "current time" (as per the event loop). 197Returns the "current time" (as per the event loop).
198
199=back
200
201=head2 RENDITION
202
203Rendition bitsets contain information about colour, font, font styles and
204similar information for each screen cell.
205
206The following "macros" deal with changes in rendition sets. You should
207never just create a bitset, you should always modify an existing one,
208as they contain important information required for correct operation of
209rxvt-unicode.
210
211=over 4
212
213=item $rend = urxvt::DEFAULT_RSTYLE
214
215Returns the default rendition, as used when the terminal is starting up or
216being reset. Useful as a base to start when creating renditions.
217
218=item $rend = urxvt::OVERLAY_RSTYLE
219
220Return the rendition mask used for overlays by default.
221
222=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
223
224Return the bit that enabled bold, italic, blink, reverse-video and
225underline, respectively. To enable such a style, just logically OR it into
226the bitset.
227
228=item $foreground = urxvt::GET_BASEFG $rend
229
230=item $background = urxvt::GET_BASEBG $rend
231
232Return the foreground/background colour index, respectively.
233
234=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
235
236=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
237
238Replace the foreground/background colour in the rendition mask with the
239specified one.
240
241=item $value = urxvt::GET_CUSTOM ($rend)
242
243Return the "custom" value: Every rendition has 5 bits for use by
244extensions. They can be set and changed as you like and are initially
245zero.
246
247=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
248
249Change the custom value.
250
251=back
140 252
141=cut 253=cut
142 254
143package urxvt; 255package urxvt;
144 256
158 unless $msg =~ /\n$/; 270 unless $msg =~ /\n$/;
159 urxvt::warn ($msg); 271 urxvt::warn ($msg);
160 }; 272 };
161} 273}
162 274
275my @hook_count;
163my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10; 276my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
164 277
165sub verbose { 278sub verbose {
166 my ($level, $msg) = @_; 279 my ($level, $msg) = @_;
167 warn "$msg\n"; #d# 280 warn "$msg\n" if $level <= $verbosity;
168} 281}
169 282
170my @invoke_cb; 283# find on_xxx subs in the package and register them
284# as hooks
285sub register_package($) {
286 my ($pkg) = @_;
287
288 for my $htype (0.. $#HOOKNAME) {
289 my $name = $HOOKNAME[$htype];
290
291 my $ref = $pkg->can ("on_" . lc $name)
292 or next;
293
294 $term->{_hook}[$htype]{$ref*1} = $ref;
295 $hook_count[$htype]++
296 or set_should_invoke $htype, 1;
297 }
298}
299
300my $script_pkg = "script0000";
301my %script_pkg;
302
303# load a single script into its own package, once only
304sub script_package($) {
305 my ($path) = @_;
306
307 $script_pkg{$path} ||= do {
308 my $pkg = "urxvt::" . ($script_pkg++);
309
310 verbose 3, "loading script '$path' into package '$pkg'";
311
312 open my $fh, "<:raw", $path
313 or die "$path: $!";
314
315 my $source = "package $pkg; use strict; use utf8;\n"
316 . "#line 1 \"$path\"\n{\n"
317 . (do { local $/; <$fh> })
318 . "\n};\n1";
319
320 eval $source or die "$path: $@";
321
322 $pkg
323 }
324}
171 325
172# called by the rxvt core 326# called by the rxvt core
173sub invoke { 327sub invoke {
174 local $term = shift; 328 local $term = shift;
175 my $htype = shift; 329 my $htype = shift;
176 330
177 my $cb = $invoke_cb[$htype]; 331 if ($htype == 0) { # INIT
332 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
333
334 for my $ext (split /:/, $term->resource ("perl_ext")) {
335 my @files = grep -f $_, map "$_/$ext", @dirs;
336
337 if (@files) {
338 register_package script_package $files[0];
339 } else {
340 warn "perl extension '$ext' not found in perl library search path\n";
341 }
342 }
343
344 } elsif ($htype == 1) { # DESTROY
345 if (my $hook = $term->{_hook}) {
346 for my $htype (0..$#$hook) {
347 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
348 or set_should_invoke $htype, 0;
349 }
350 }
351 }
352
353 my $cb = $term->{_hook}[$htype]
354 or return;
178 355
179 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 356 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
180 if $verbosity >= 10; 357 if $verbosity >= 10;
181 358
182 while (my ($k, $v) = each %$cb) { 359 while (my ($k, $v) = each %$cb) {
184 } 361 }
185 362
186 0 363 0
187} 364}
188 365
189# find on_xxx subs in the package and register them 366=head2 The C<urxvt::term> Class
190# as hooks
191sub register_package($) {
192 my ($pkg) = @_;
193 367
194 for my $hook (0.. $#HOOKNAME) { 368=over 4
195 my $name = $HOOKNAME[$hook];
196 369
197 my $ref = $pkg->can ("on_" . lc $name) 370=item $value = $term->resource ($name[, $newval])
198 or next;
199 371
200 $invoke_cb[$hook]{$ref*1} = $ref; 372Returns the current resource value associated with a given name and
201 set_should_invoke $hook, 1; 373optionally sets a new value. Setting values is most useful in the C<init>
202 } 374hook. Unset resources are returned and accepted as C<undef>.
375
376The new value must be properly encoded to a suitable character encoding
377before passing it to this method. Similarly, the returned value may need
378to be converted from the used encoding to text.
379
380Resource names are as defined in F<src/rsinc.h>. Colours can be specified
381as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
382likely change).
383
384Please note that resource strings will currently only be freed when the
385terminal is destroyed, so changing options frequently will eat memory.
386
387Here is a a likely non-exhaustive list of resource names, not all of which
388are supported in every build, please see the source to see the actual
389list:
390
391 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
392 borderLess color cursorBlink cursorUnderline cutchars delete_key
393 display_name embed ext_bwidth fade font geometry hold iconName
394 imFont imLocale inputMethod insecure int_bwidth intensityStyles
395 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
396 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
397 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
398 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
399 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
400 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
401 shade term_name title transparent transparent_all tripleclickwords
402 utmpInhibit visualBell
403
404=cut
405
406sub urxvt::term::resource($$;$) {
407 my ($self, $name) = (shift, shift);
408 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
409 goto &urxvt::term::_resource;
203} 410}
204
205my $script_pkg = "script0000";
206my %script_pkg;
207
208# load a single script into its own package, once only
209sub load_script($) {
210 my ($path) = @_;
211
212 $script_pkg{$path} ||= do {
213 my $pkg = $script_pkg++;
214 verbose 3, "loading script '$path' into package '$pkg'";
215
216 open my $fh, "<:raw", $path
217 or die "$path: $!";
218
219 eval "package $pkg; use strict; use utf8;\n"
220 . "#line 1 \"$path\"\n"
221 . do { local $/; <$fh> }
222 or die "$path: $@";
223
224 register_package $pkg;
225
226 $pkg
227 };
228}
229
230load_script $_ for grep -f $_, <$LIBDIR/perl-ext/*>;
231
232
233=back
234
235=head2 The C<urxvt::term> Class
236
237=over 4
238 411
239=item ($row, $col) = $term->selection_mark ([$row, $col]) 412=item ($row, $col) = $term->selection_mark ([$row, $col])
240 413
241=item ($row, $col) = $term->selection_beg ([$row, $col]) 414=item ($row, $col) = $term->selection_beg ([$row, $col])
242 415
252 425
253=item $oldtext = $term->selection ([$newtext]) 426=item $oldtext = $term->selection ([$newtext])
254 427
255Return the current selection text and optionally replace it by C<$newtext>. 428Return the current selection text and optionally replace it by C<$newtext>.
256 429
257=item $term->scr_overlay ($x, $y, $text) 430#=item $term->overlay ($x, $y, $text)
258 431#
259Create a simple multi-line overlay box. See the next method for details. 432#Create a simple multi-line overlay box. See the next method for details.
260 433#
261=cut 434#=cut
262 435
263sub urxvt::term::scr_overlay { 436sub urxvt::term::scr_overlay {
437die;
264 my ($self, $x, $y, $text) = @_; 438 my ($self, $x, $y, $text) = @_;
265 439
266 my @lines = split /\n/, $text; 440 my @lines = split /\n/, $text;
267 441
268 my $w = 0; 442 my $w = 0;
269 for (map urxvt::wcswidth $_, @lines) { 443 for (map $self->strwidth ($_), @lines) {
270 $w = $_ if $w < $_; 444 $w = $_ if $w < $_;
271 } 445 }
272 446
273 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 447 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
274 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 448 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
275} 449}
276 450
277=item $term->scr_overlay_new ($x, $y, $width, $height) 451=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
278 452
279Create a new (empty) overlay at the given position with the given 453Create a new (empty) overlay at the given position with the given
280width/height. A border will be put around the box. If either C<$x> or 454width/height. C<$rstyle> defines the initial rendition style
281C<$y> is negative, then this is counted from the right/bottom side, 455(default: C<OVERLAY_RSTYLE>).
282respectively.
283 456
284=item $term->scr_overlay_off 457If C<$border> is C<2> (default), then a decorative border will be put
458around the box.
285 459
286Switch the overlay off again. 460If either C<$x> or C<$y> is negative, then this is counted from the
461right/bottom side, respectively.
287 462
288=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 463This method returns an urxvt::overlay object. The overlay will be visible
464as long as the perl object is referenced.
289 465
290Put a single character (specified numerically) at the given overlay 466Currently, the only method on the C<urxvt::overlay> object is C<set>:
291position.
292 467
293=item $term->scr_overlay_set ($x, $y, $text) 468=item $overlay->set ($x, $y, $text, $rend)
294 469
295Write a string at the given position into the overlay. 470Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
471text in rxvt-unicode's special encoding and an array of rendition values
472at a specific position inside the overlay.
473
474=item $cellwidth = $term->strwidth $string
475
476Returns the number of screen-cells this string would need. Correctly
477accounts for wide and combining characters.
478
479=item $octets = $term->locale_encode $string
480
481Convert the given text string into the corresponding locale encoding.
482
483=item $string = $term->locale_decode $octets
484
485Convert the given locale-encoded octets into a perl string.
486
487=item $term->tt_write ($octets)
488
489Write the octets given in C<$data> to the tty (i.e. as program input). To
490pass characters instead of octets, you should convert your strings first
491to the locale-specific encoding using C<< $term->locale_encode >>.
492
493=item $nrow = $term->nrow
494
495=item $ncol = $term->ncol
496
497Return the number of rows/columns of the terminal window (i.e. as
498specified by C<-geometry>, excluding any scrollback).
499
500=item $nsaved = $term->nsaved
501
502Returns the number of lines in the scrollback buffer.
503
504=item $view_start = $term->view_start ([$newvalue])
505
506Returns the negative row number of the topmost line. Minimum value is
507C<0>, which displays the normal terminal contents. Larger values scroll
508this many lines into the scrollback buffer.
509
510=item $term->want_refresh
511
512Requests a screen refresh. At the next opportunity, rxvt-unicode will
513compare the on-screen display with its stored representation. If they
514differ, it redraws the differences.
515
516Used after changing terminal contents to display them.
517
518=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
519
520Returns the text of the entire row with number C<$row_number>. Row C<0>
521is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
522terminal line. The scrollback buffer starts at line C<-1> and extends to
523line C<< -$term->nsaved >>.
524
525If C<$new_text> is specified, it will replace characters in the current
526line, starting at column C<$start_col> (default C<0>), which is useful
527to replace only parts of a line. The font index in the rendition will
528automatically be updated.
529
530C<$text> is in a special encoding: tabs and wide characters that use more
531than one cell when displayed are padded with urxvt::NOCHAR characters
532(C<chr 65535>). Characters with combining characters and other characters
533that do not fit into the normal tetx encoding will be replaced with
534characters in the private use area.
535
536You have to obey this encoding when changing text. The advantage is
537that C<substr> and similar functions work on screen cells and not on
538characters.
539
540The methods C<< $term->special_encode >> and C<< $term->special_decode >>
541can be used to convert normal strings into this encoding and vice versa.
542
543=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
544
545Like C<< $term->ROW_t >>, but returns an arrayref with rendition
546bitsets. Rendition bitsets contain information about colour, font, font
547styles and similar information. See also C<< $term->ROW_t >>.
548
549When setting rendition, the font mask will be ignored.
550
551See the section on RENDITION, above.
552
553=item $length = $term->ROW_l ($row_number[, $new_length])
554
555Returns the number of screen cells that are in use ("the line length"). If
556it is C<-1>, then the line is part of a multiple-row logical "line", which
557means all characters are in use and it is continued on the next row.
558
559=item $text = $term->special_encode $string
560
561Converts a perl string into the special encoding used by rxvt-unicode,
562where one character corresponds to one screen cell. See
563C<< $term->ROW_t >> for details.
564
565=item $string = $term->special_decode $text
566
567Converts rxvt-unicodes text reprsentation into a perl string. See
568C<< $term->ROW_t >> for details.
296 569
297=back 570=back
298 571
299=head2 The C<urxvt::timer> Class 572=head2 The C<urxvt::timer> Class
300 573
301This class implements timer watchers/events. Time is represented as a 574This class implements timer watchers/events. Time is represented as a
302fractional number of seconds since the epoch. Example: 575fractional number of seconds since the epoch. Example:
303 576
304 # create a digital clock display in upper right corner 577 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
305 $term->{timer} = urxvt::timer 578 $term->{timer} = urxvt::timer
306 ->new 579 ->new
307 ->start (urxvt::NOW) 580 ->interval (1)
308 ->cb (sub { 581 ->cb (sub {
309 my ($timer) = @_;
310 my $time = $timer->at;
311 $timer->start ($time + 1);
312 $self->scr_overlay (-1, 0, 582 $term->{overlay}->set (0, 0,
313 POSIX::strftime "%H:%M:%S", localtime $time); 583 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
314 }); 584 });
315 585
316=over 4 586=over 4
317 587
318=item $timer = new urxvt::timer 588=item $timer = new urxvt::timer
319 589
320Create a new timer object in stopped state. 590Create a new timer object in started state. It is scheduled to fire
591immediately.
321 592
322=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 593=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
323 594
324Set the callback to be called when the timer triggers. 595Set the callback to be called when the timer triggers.
325 596
328Return the time this watcher will fire next. 599Return the time this watcher will fire next.
329 600
330=item $timer = $timer->set ($tstamp) 601=item $timer = $timer->set ($tstamp)
331 602
332Set the time the event is generated to $tstamp. 603Set the time the event is generated to $tstamp.
604
605=item $timer = $timer->interval ($interval)
606
607Normally (and when C<$interval> is C<0>), the timer will automatically
608stop after it has fired once. If C<$interval> is non-zero, then the timer
609is automatically rescheduled at the given intervals.
333 610
334=item $timer = $timer->start 611=item $timer = $timer->start
335 612
336Start the timer. 613Start the timer.
337 614
391 668
392Stop watching for events on the given filehandle. 669Stop watching for events on the given filehandle.
393 670
394=back 671=back
395 672
673=head1 ENVIRONMENT
674
675=head2 URXVT_PERL_VERBOSITY
676
677This variable controls the verbosity level of the perl extension. Higher
678numbers indicate more verbose output.
679
680=over 4
681
682=item 0 - only fatal messages
683
684=item 3 - script loading and management
685
686=item 10 - all events received
687
688=back
689
396=head1 AUTHOR 690=head1 AUTHOR
397 691
398 Marc Lehmann <pcg@goof.com> 692 Marc Lehmann <pcg@goof.com>
399 http://software.schmorp.de/pkg/rxvt-unicode 693 http://software.schmorp.de/pkg/rxvt-unicode
400 694

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines