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.69 by root, Mon Jan 9 22:41:41 2006 UTC vs.
Revision 1.77 by root, Wed Jan 11 00:59:58 2006 UTC

26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40=over 4 40=over 4
41 41
42=item selection (enabled by default) 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 45when the user extends selections (double-click). Right now, it tries to
46urls and complete shell-quoted arguments, which is very convenient, too, 46select urls and complete shell-quoted arguments, which is very convenient,
47if your F<ls> supports C<--quoting-style=shell>. 47too, if your F<ls> supports C<--quoting-style=shell>.
48 48
49It also offers the following bindable event: 49It also offers the following bindable keyboard command:
50 50
51=over 4 51=over 4
52 52
53=item rot13 53=item rot13
54 54
64runtime. 64runtime.
65 65
66=item selection-popup (enabled by default) 66=item selection-popup (enabled by default)
67 67
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection 68Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action. 69text into various other formats/action (such as uri unescaping, perl
70evalution, web-browser starting etc.), depending on content.
70 71
71=item searchable-scrollback (enabled by default) 72=item searchable-scrollback<hotkey> (enabled by default)
72 73
73Adds regex search functionality to the scrollback buffer, triggered by a 74Adds regex search functionality to the scrollback buffer, triggered
74hotkey (default: C<M-s>). When in search mode, terminal input/output is 75by a hotkey (default: C<M-s>). When in search mode, normal terminal
76input/output is suspended.
77
75suspended, C</> starts an incremental regex search, C<n> searches further, 78C</> starts an incremental regex search, C<n> searches further, C<p> or
76C<p> jumps to the previous match. C<enter> leaves search mode at the 79C<N> jump to the previous match, C<G> jumps to the bottom and clears the
77current position and C<escape> returns to the original position. 80history, C<enter> leaves search mode at the current position and C<escape>
81returns to the original position.
78 82
79=item digital-clock 83=item digital-clock
80 84
81Displays a digital clock using the built-in overlay. 85Displays a digital clock using the built-in overlay.
82 86
95Displays a very simple digital clock in the upper right corner of the 99Displays a very simple digital clock in the upper right corner of the
96window. Illustrates overwriting the refresh callbacks to create your own 100window. Illustrates overwriting the refresh callbacks to create your own
97overlays or changes. 101overlays or changes.
98 102
99=back 103=back
104
105=head1 API DOCUMENTATION
100 106
101=head2 General API Considerations 107=head2 General API Considerations
102 108
103All objects (such as terminals, time watchers etc.) are typical 109All objects (such as terminals, time watchers etc.) are typical
104reference-to-hash objects. The hash can be used to store anything you 110reference-to-hash objects. The hash can be used to store anything you
263can filter/change and output the text yourself by returning a true value 269can filter/change and output the text yourself by returning a true value
264and calling C<< $term->scr_add_lines >> yourself. Please note that this 270and calling C<< $term->scr_add_lines >> yourself. Please note that this
265might be very slow, however, as your hook is called for B<all> text being 271might be very slow, however, as your hook is called for B<all> text being
266output. 272output.
267 273
274=item on_tt_write $term, $octets
275
276Called whenever some data is written to the tty/pty and can be used to
277suppress or filter tty input.
278
268=item on_line_update $term, $row 279=item on_line_update $term, $row
269 280
270Called whenever a line was updated or changed. Can be used to filter 281Called whenever a line was updated or changed. Can be used to filter
271screen output (e.g. underline urls or other useless stuff). Only lines 282screen output (e.g. underline urls or other useless stuff). Only lines
272that are being shown will be filtered, and, due to performance reasons, 283that are being shown will be filtered, and, due to performance reasons,
329 340
330C<on_key_press> additionally receives the string rxvt-unicode would 341C<on_key_press> additionally receives the string rxvt-unicode would
331output, if any, in locale-specific encoding. 342output, if any, in locale-specific encoding.
332 343
333subwindow. 344subwindow.
334
335=back
336
337=head2 Variables in the C<urxvt> Package
338
339=over 4
340
341=item $urxvt::TERM
342
343The current terminal. This variable stores the current C<urxvt::term>
344object, whenever a callback/hook is executing.
345
346=back
347
348=head2 Functions in the C<urxvt> Package
349
350=over 4
351
352=item $term = new urxvt [arg...]
353
354Creates a new terminal, very similar as if you had started it with
355C<system $binfile, arg...>. Croaks (and probably outputs an error message)
356if the new instance couldn't be created. Returns C<undef> if the new
357instance didn't initialise perl, and the terminal object otherwise. The
358C<init> and C<start> hooks will be called during the call.
359
360=item urxvt::fatal $errormessage
361
362Fatally aborts execution with the given error message. Avoid at all
363costs! The only time this is acceptable is when the terminal process
364starts up.
365
366=item urxvt::warn $string
367
368Calls C<rxvt_warn> with the given string which should not include a
369newline. The module also overwrites the C<warn> builtin with a function
370that calls this function.
371
372Using this function has the advantage that its output ends up in the
373correct place, e.g. on stderr of the connecting urxvtc client.
374
375=item $is_safe = urxvt::safe
376
377Returns true when it is safe to do potentially unsafe things, such as
378evaluating perl code specified by the user. This is true when urxvt was
379started setuid or setgid.
380
381=item $time = urxvt::NOW
382
383Returns the "current time" (as per the event loop).
384
385=item urxvt::CurrentTime
386
387=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
388Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
389Button4Mask, Button5Mask, AnyModifier
390
391Various constants for use in X calls and event processing.
392
393=back
394
395=head2 RENDITION
396
397Rendition bitsets contain information about colour, font, font styles and
398similar information for each screen cell.
399
400The following "macros" deal with changes in rendition sets. You should
401never just create a bitset, you should always modify an existing one,
402as they contain important information required for correct operation of
403rxvt-unicode.
404
405=over 4
406
407=item $rend = urxvt::DEFAULT_RSTYLE
408
409Returns the default rendition, as used when the terminal is starting up or
410being reset. Useful as a base to start when creating renditions.
411
412=item $rend = urxvt::OVERLAY_RSTYLE
413
414Return the rendition mask used for overlays by default.
415
416=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
417
418Return the bit that enabled bold, italic, blink, reverse-video and
419underline, respectively. To enable such a style, just logically OR it into
420the bitset.
421
422=item $foreground = urxvt::GET_BASEFG $rend
423
424=item $background = urxvt::GET_BASEBG $rend
425
426Return the foreground/background colour index, respectively.
427
428=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
429
430=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
431
432Replace the foreground/background colour in the rendition mask with the
433specified one.
434
435=item $value = urxvt::GET_CUSTOM ($rend)
436
437Return the "custom" value: Every rendition has 5 bits for use by
438extensions. They can be set and changed as you like and are initially
439zero.
440
441=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
442
443Change the custom value.
444 345
445=back 346=back
446 347
447=cut 348=cut
448 349
457our $VERSION = 1; 358our $VERSION = 1;
458our $TERM; 359our $TERM;
459our @HOOKNAME; 360our @HOOKNAME;
460our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 361our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
461our %OPTION; 362our %OPTION;
363
462our $LIBDIR; 364our $LIBDIR;
365our $RESNAME;
366our $RESCLASS;
367our $RXVTNAME;
368
369=head2 Variables in the C<urxvt> Package
370
371=over 4
372
373=item $urxvt::LIBDIR
374
375The rxvt-unicode library directory, where, among other things, the perl
376modules and scripts are stored.
377
378=item $urxvt::RESCLASS, $urxvt::RESCLASS
379
380The resource class and name rxvt-unicode uses to look up X resources.
381
382=item $urxvt::RXVTNAME
383
384The basename of the installed binaries, usually C<urxvt>.
385
386=item $urxvt::TERM
387
388The current terminal. This variable stores the current C<urxvt::term>
389object, whenever a callback/hook is executing.
390
391=item
392
393=back
394
395=head2 Functions in the C<urxvt> Package
396
397=over 4
398
399=item urxvt::fatal $errormessage
400
401Fatally aborts execution with the given error message. Avoid at all
402costs! The only time this is acceptable is when the terminal process
403starts up.
404
405=item urxvt::warn $string
406
407Calls C<rxvt_warn> with the given string which should not include a
408newline. The module also overwrites the C<warn> builtin with a function
409that calls this function.
410
411Using this function has the advantage that its output ends up in the
412correct place, e.g. on stderr of the connecting urxvtc client.
413
414Messages have a size limit of 1023 bytes currently.
415
416=item $is_safe = urxvt::safe
417
418Returns true when it is safe to do potentially unsafe things, such as
419evaluating perl code specified by the user. This is true when urxvt was
420started setuid or setgid.
421
422=item $time = urxvt::NOW
423
424Returns the "current time" (as per the event loop).
425
426=item urxvt::CurrentTime
427
428=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
429Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
430Button4Mask, Button5Mask, AnyModifier
431
432Various constants for use in X calls and event processing.
433
434=back
435
436=head2 RENDITION
437
438Rendition bitsets contain information about colour, font, font styles and
439similar information for each screen cell.
440
441The following "macros" deal with changes in rendition sets. You should
442never just create a bitset, you should always modify an existing one,
443as they contain important information required for correct operation of
444rxvt-unicode.
445
446=over 4
447
448=item $rend = urxvt::DEFAULT_RSTYLE
449
450Returns the default rendition, as used when the terminal is starting up or
451being reset. Useful as a base to start when creating renditions.
452
453=item $rend = urxvt::OVERLAY_RSTYLE
454
455Return the rendition mask used for overlays by default.
456
457=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
458
459Return the bit that enabled bold, italic, blink, reverse-video and
460underline, respectively. To enable such a style, just logically OR it into
461the bitset.
462
463=item $foreground = urxvt::GET_BASEFG $rend
464
465=item $background = urxvt::GET_BASEBG $rend
466
467Return the foreground/background colour index, respectively.
468
469=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
470
471=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
472
473Replace the foreground/background colour in the rendition mask with the
474specified one.
475
476=item $value = urxvt::GET_CUSTOM $rend
477
478Return the "custom" value: Every rendition has 5 bits for use by
479extensions. They can be set and changed as you like and are initially
480zero.
481
482=item $rend = urxvt::SET_CUSTOM $rend, $new_value
483
484Change the custom value.
485
486=back
487
488=cut
463 489
464BEGIN { 490BEGIN {
465 urxvt->bootstrap; 491 urxvt->bootstrap;
466 492
467 # overwrite perl's warn 493 # overwrite perl's warn
501 open my $fh, "<:raw", $path 527 open my $fh, "<:raw", $path
502 or die "$path: $!"; 528 or die "$path: $!";
503 529
504 my $source = untaint 530 my $source = untaint
505 "package $pkg; use strict; use utf8;\n" 531 "package $pkg; use strict; use utf8;\n"
506 . "use base urxvt::term::proxy::;\n" 532 . "use base urxvt::term::extension::;\n"
507 . "#line 1 \"$path\"\n{\n" 533 . "#line 1 \"$path\"\n{\n"
508 . (do { local $/; <$fh> }) 534 . (do { local $/; <$fh> })
509 . "\n};\n1"; 535 . "\n};\n1";
510 536
511 eval $source 537 eval $source
588 } 614 }
589 615
590 $retval 616 $retval
591} 617}
592 618
593# urxvt::term::proxy 619# urxvt::term::extension
594 620
595package urxvt::term::proxy; 621package urxvt::term::extension;
596 622
597sub enable { 623sub enable {
598 my ($self, %hook) = @_; 624 my ($self, %hook) = @_;
599 my $pkg = $self->{_pkg}; 625 my $pkg = $self->{_pkg};
600 626
663 689
664=head2 The C<urxvt::anyevent> Class 690=head2 The C<urxvt::anyevent> Class
665 691
666The sole purpose of this class is to deliver an interface to the 692The sole purpose of this class is to deliver an interface to the
667C<AnyEvent> module - any module using it will work inside urxvt without 693C<AnyEvent> module - any module using it will work inside urxvt without
668further work. The only exception is that you cannot wait on condition 694further programming. The only exception is that you cannot wait on
669variables, but non-blocking condvar use is ok. What this means is that you 695condition variables, but non-blocking condvar use is ok. What this means
670cannot use blocking APIs, but the non-blocking variant should work. 696is that you cannot use blocking APIs, but the non-blocking variant should
697work.
671 698
672=cut 699=cut
673 700
674our $VERSION = 1; 701our $VERSION = 1;
675 702
752 $proxy->enable ($name => $ref); 779 $proxy->enable ($name => $ref);
753 } 780 }
754 } 781 }
755} 782}
756 783
784=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
785
786Creates a new terminal, very similar as if you had started it with system
787C<$rxvtname, arg...>. C<$envhashref> must be a reference to a %ENV>-like
788C<hash which defines the environment of the new terminal.
789
790Croaks (and probably outputs an error message) if the new instance
791couldn't be created. Returns C<undef> if the new instance didn't
792initialise perl, and the terminal object otherwise. The C<init> and
793C<start> hooks will be called during this call.
794
795=cut
796
797sub new {
798 my ($class, $env, @args) = @_;
799
800 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
801}
802
757=item $term->destroy 803=item $term->destroy
758 804
759Destroy the terminal object (close the window, free resources etc.). 805Destroy the terminal object (close the window, free resources
806etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
807watchers (timers, io watchers) are still active.
760 808
761=item $isset = $term->option ($optval[, $set]) 809=item $isset = $term->option ($optval[, $set])
762 810
763Returns true if the option specified by C<$optval> is enabled, and 811Returns true if the option specified by C<$optval> is enabled, and
764optionally change it. All option values are stored by name in the hash 812optionally change it. All option values are stored by name in the hash
941 989
942=item $string = $term->locale_decode ($octets) 990=item $string = $term->locale_decode ($octets)
943 991
944Convert the given locale-encoded octets into a perl string. 992Convert the given locale-encoded octets into a perl string.
945 993
994=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
995
996XORs the rendition values in the given span with the provided value
997(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
998to the selection.
999
1000=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1001
1002Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1003whitespace will additionally be xored with the C<$rstyle2>, which defaults
1004to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1005it instead.
1006
946=item $term->scr_bell 1007=item $term->scr_bell
947 1008
948Ring the bell! 1009Ring the bell!
949 1010
950=item $term->scr_add_lines ($string) 1011=item $term->scr_add_lines ($string)
1009 1070
1010=item $lines_in_scrollback = $term->nsaved 1071=item $lines_in_scrollback = $term->nsaved
1011 1072
1012Return various integers describing terminal characteristics. 1073Return various integers describing terminal characteristics.
1013 1074
1075=item $x_display = $term->display_id
1076
1077Return the DISPLAY used by rxvt-unicode.
1078
1014=item $lc_ctype = $term->locale 1079=item $lc_ctype = $term->locale
1015 1080
1016Returns the LC_CTYPE category string used by this rxvt-unicode. 1081Returns the LC_CTYPE category string used by this rxvt-unicode.
1017 1082
1018=item $x_display = $term->display_id 1083=item $env = $term->env
1019 1084
1020Return the DISPLAY used by rxvt-unicode. 1085Returns a copy of the environment in effect for the terminal as a hashref
1086similar to C<\%ENV>.
1087
1088=cut
1089
1090sub env {
1091 if (my $env = $_[0]->_env) {
1092 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1093 } else {
1094 +{ %ENV }
1095 }
1096}
1021 1097
1022=item $modifiermask = $term->ModLevel3Mask 1098=item $modifiermask = $term->ModLevel3Mask
1023 1099
1024=item $modifiermask = $term->ModMetaMask 1100=item $modifiermask = $term->ModMetaMask
1025 1101
1265 $item->{render} ||= sub { $_[0]{text} }; 1341 $item->{render} ||= sub { $_[0]{text} };
1266 1342
1267 push @{ $self->{item} }, $item; 1343 push @{ $self->{item} }, $item;
1268} 1344}
1269 1345
1346=item $popup->add_title ($title)
1347
1348Adds a non-clickable title to the popup.
1349
1350=cut
1351
1352sub add_title {
1353 my ($self, $title) = @_;
1354
1355 $self->add_item ({
1356 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1357 text => $title,
1358 activate => sub { },
1359 });
1360}
1361
1362=item $popup->add_separator ([$sepchr])
1363
1364Creates a separator, optionally using the character given as C<$sepchr>.
1365
1366=cut
1367
1270sub add_separator { 1368sub add_separator {
1271 my ($self, $sep) = @_; 1369 my ($self, $sep) = @_;
1272 1370
1273 $sep ||= "="; 1371 $sep ||= "=";
1274 1372
1278 render => sub { $sep x $self->{term}->ncol }, 1376 render => sub { $sep x $self->{term}->ncol },
1279 activate => sub { }, 1377 activate => sub { },
1280 }); 1378 });
1281} 1379}
1282 1380
1283sub add_title { 1381=item $popup->add_button ($text, $cb)
1284 my ($self, $title) = @_;
1285 1382
1286 $self->add_item ({ 1383Adds a clickable button to the popup. C<$cb> is called whenever it is
1287 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" }, 1384selected.
1288 text => $title, 1385
1289 activate => sub { }, 1386=cut
1290 });
1291}
1292 1387
1293sub add_button { 1388sub add_button {
1294 my ($self, $text, $cb) = @_; 1389 my ($self, $text, $cb) = @_;
1295 1390
1296 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1391 $self->add_item ({ type => "button", text => $text, activate => $cb});
1297} 1392}
1393
1394=item $popup->add_toggle ($text, $cb, $initial_value)
1395
1396Adds a toggle/checkbox item to the popup. Teh callback gets called
1397whenever it gets toggled, with a boolean indicating its value as its first
1398argument.
1399
1400=cut
1298 1401
1299sub add_toggle { 1402sub add_toggle {
1300 my ($self, $text, $cb, $value) = @_; 1403 my ($self, $text, $cb, $value) = @_;
1301 1404
1302 my $item; $item = { 1405 my $item; $item = {
1303 type => "button", 1406 type => "button",
1304 text => " $text", 1407 text => " $text",
1305 value => $value, 1408 value => $value,
1306 render => sub { ($_[0]{value} ? "* " : " ") . $text }, 1409 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1307 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, 1410 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1308 }; 1411 };
1309 1412
1310 $self->add_item ($item); 1413 $self->add_item ($item);
1311} 1414}
1415
1416=item $popup->show
1417
1418Displays the popup (which is initially hidden).
1419
1420=cut
1312 1421
1313sub show { 1422sub show {
1314 my ($self) = @_; 1423 my ($self) = @_;
1315 1424
1316 local $urxvt::popup::self = $self; 1425 local $urxvt::popup::self = $self;
1317 1426
1427 my $env = $self->{term}->env;
1428 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1429 delete $env->{LC_ALL};
1318 local $ENV{LC_ALL} = $self->{term}->locale; 1430 $env->{LC_CTYPE} = $self->{term}->locale;
1319 1431
1432 urxvt::term->new ($env, $self->{term}->resource ("name"),
1320 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1433 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1321 "--transient-for" => $self->{term}->parent, 1434 "--transient-for" => $self->{term}->parent,
1322 "-display" => $self->{term}->display_id, 1435 "-display" => $self->{term}->display_id,
1323 "-pe" => "urxvt-popup") 1436 "-pe" => "urxvt-popup")
1324 or die "unable to create popup window\n"; 1437 or die "unable to create popup window\n";
1325} 1438}
1326 1439
1327sub DESTROY { 1440sub DESTROY {
1328 my ($self) = @_; 1441 my ($self) = @_;

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines