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.74 by root, Tue Jan 10 04:26:54 2006 UTC vs.
Revision 1.82 by root, Thu Jan 12 01:30:53 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<hotkey> (enabled by default) 72=item searchable-scrollback<hotkey> (enabled by default)
72 73
73Adds regex search functionality to the scrollback buffer, triggered 74Adds regex search functionality to the scrollback buffer, triggered
74by a hotkey (default: C<M-s>). When in search mode, normal terminal 75by a hotkey (default: C<M-s>). When in search mode, normal terminal
83 84
84Displays a digital clock using the built-in overlay. 85Displays a digital clock using the built-in overlay.
85 86
86=item mark-urls 87=item mark-urls
87 88
88Uses per-line display filtering (C<on_line_update>) to underline urls. 89Uses per-line display filtering (C<on_line_update>) to underline urls and
90make them clickable. When clicked, the program specified in the resource
91C<urlLauncher> (default C<x-www-browser>) will be started.
89 92
90=item block-graphics-to-ascii 93=item block-graphics-to-ascii
91 94
92A not very useful example of filtering all text output to the terminal, 95A not very useful example of filtering all text output to the terminal,
93by replacing all line-drawing characters (U+2500 .. U+259F) by a 96by replacing all line-drawing characters (U+2500 .. U+259F) by a
98Displays a very simple digital clock in the upper right corner of the 101Displays a very simple digital clock in the upper right corner of the
99window. Illustrates overwriting the refresh callbacks to create your own 102window. Illustrates overwriting the refresh callbacks to create your own
100overlays or changes. 103overlays or changes.
101 104
102=back 105=back
106
107=head1 API DOCUMENTATION
103 108
104=head2 General API Considerations 109=head2 General API Considerations
105 110
106All objects (such as terminals, time watchers etc.) are typical 111All objects (such as terminals, time watchers etc.) are typical
107reference-to-hash objects. The hash can be used to store anything you 112reference-to-hash objects. The hash can be used to store anything you
120=over 4 125=over 4
121 126
122=item $text 127=item $text
123 128
124Rxvt-unicodes special way of encoding text, where one "unicode" character 129Rxvt-unicodes special way of encoding text, where one "unicode" character
125always represents one screen cell. See L<row_t> for a discussion of this format. 130always represents one screen cell. See L<ROW_t> for a discussion of this format.
126 131
127=item $string 132=item $string
128 133
129A perl text string, with an emphasis on I<text>. It can store all unicode 134A perl text string, with an emphasis on I<text>. It can store all unicode
130characters and is to be distinguished with text encoded in a specific 135characters and is to be distinguished with text encoded in a specific
340 345
341subwindow. 346subwindow.
342 347
343=back 348=back
344 349
345=head2 Variables in the C<urxvt> Package
346
347=over 4
348
349=item $urxvt::TERM
350
351The current terminal. This variable stores the current C<urxvt::term>
352object, whenever a callback/hook is executing.
353
354=back
355
356=head2 Functions in the C<urxvt> Package
357
358=over 4
359
360=item $term = new urxvt [arg...]
361
362Creates a new terminal, very similar as if you had started it with
363C<system $binfile, arg...>. Croaks (and probably outputs an error message)
364if the new instance couldn't be created. Returns C<undef> if the new
365instance didn't initialise perl, and the terminal object otherwise. The
366C<init> and C<start> hooks will be called during the call.
367
368=item urxvt::fatal $errormessage
369
370Fatally aborts execution with the given error message. Avoid at all
371costs! The only time this is acceptable is when the terminal process
372starts up.
373
374=item urxvt::warn $string
375
376Calls C<rxvt_warn> with the given string which should not include a
377newline. The module also overwrites the C<warn> builtin with a function
378that calls this function.
379
380Using this function has the advantage that its output ends up in the
381correct place, e.g. on stderr of the connecting urxvtc client.
382
383=item $is_safe = urxvt::safe
384
385Returns true when it is safe to do potentially unsafe things, such as
386evaluating perl code specified by the user. This is true when urxvt was
387started setuid or setgid.
388
389=item $time = urxvt::NOW
390
391Returns the "current time" (as per the event loop).
392
393=item urxvt::CurrentTime
394
395=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
396Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
397Button4Mask, Button5Mask, AnyModifier
398
399Various constants for use in X calls and event processing.
400
401=back
402
403=head2 RENDITION
404
405Rendition bitsets contain information about colour, font, font styles and
406similar information for each screen cell.
407
408The following "macros" deal with changes in rendition sets. You should
409never just create a bitset, you should always modify an existing one,
410as they contain important information required for correct operation of
411rxvt-unicode.
412
413=over 4
414
415=item $rend = urxvt::DEFAULT_RSTYLE
416
417Returns the default rendition, as used when the terminal is starting up or
418being reset. Useful as a base to start when creating renditions.
419
420=item $rend = urxvt::OVERLAY_RSTYLE
421
422Return the rendition mask used for overlays by default.
423
424=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
425
426Return the bit that enabled bold, italic, blink, reverse-video and
427underline, respectively. To enable such a style, just logically OR it into
428the bitset.
429
430=item $foreground = urxvt::GET_BASEFG $rend
431
432=item $background = urxvt::GET_BASEBG $rend
433
434Return the foreground/background colour index, respectively.
435
436=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
437
438=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
439
440Replace the foreground/background colour in the rendition mask with the
441specified one.
442
443=item $value = urxvt::GET_CUSTOM ($rend)
444
445Return the "custom" value: Every rendition has 5 bits for use by
446extensions. They can be set and changed as you like and are initially
447zero.
448
449=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
450
451Change the custom value.
452
453=back
454
455=cut 350=cut
456 351
457package urxvt; 352package urxvt;
458 353
459use utf8; 354use utf8;
470 365
471our $LIBDIR; 366our $LIBDIR;
472our $RESNAME; 367our $RESNAME;
473our $RESCLASS; 368our $RESCLASS;
474our $RXVTNAME; 369our $RXVTNAME;
370
371=head2 Variables in the C<urxvt> Package
372
373=over 4
374
375=item $urxvt::LIBDIR
376
377The rxvt-unicode library directory, where, among other things, the perl
378modules and scripts are stored.
379
380=item $urxvt::RESCLASS, $urxvt::RESCLASS
381
382The resource class and name rxvt-unicode uses to look up X resources.
383
384=item $urxvt::RXVTNAME
385
386The basename of the installed binaries, usually C<urxvt>.
387
388=item $urxvt::TERM
389
390The current terminal. This variable stores the current C<urxvt::term>
391object, whenever a callback/hook is executing.
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
475 489
476BEGIN { 490BEGIN {
477 urxvt->bootstrap; 491 urxvt->bootstrap;
478 492
479 # overwrite perl's warn 493 # overwrite perl's warn
482 $msg .= "\n" 496 $msg .= "\n"
483 unless $msg =~ /\n$/; 497 unless $msg =~ /\n$/;
484 urxvt::warn ($msg); 498 urxvt::warn ($msg);
485 }; 499 };
486 500
501 # %ENV is the original startup environment
487 delete $ENV{IFS}; 502 delete $ENV{IFS};
488 delete $ENV{CDPATH}; 503 delete $ENV{CDPATH};
489 delete $ENV{BASH_ENV}; 504 delete $ENV{BASH_ENV};
490 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin"; 505 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
491} 506}
675 690
676=head2 The C<urxvt::anyevent> Class 691=head2 The C<urxvt::anyevent> Class
677 692
678The sole purpose of this class is to deliver an interface to the 693The sole purpose of this class is to deliver an interface to the
679C<AnyEvent> module - any module using it will work inside urxvt without 694C<AnyEvent> module - any module using it will work inside urxvt without
680further work. The only exception is that you cannot wait on condition 695further programming. The only exception is that you cannot wait on
681variables, but non-blocking condvar use is ok. What this means is that you 696condition variables, but non-blocking condvar use is ok. What this means
682cannot use blocking APIs, but the non-blocking variant should work. 697is that you cannot use blocking APIs, but the non-blocking variant should
698work.
683 699
684=cut 700=cut
685 701
686our $VERSION = 1; 702our $VERSION = 1;
687 703
764 $proxy->enable ($name => $ref); 780 $proxy->enable ($name => $ref);
765 } 781 }
766 } 782 }
767} 783}
768 784
785=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
786
787Creates a new terminal, very similar as if you had started it with system
788C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
789hash which defines the environment of the new terminal.
790
791Croaks (and probably outputs an error message) if the new instance
792couldn't be created. Returns C<undef> if the new instance didn't
793initialise perl, and the terminal object otherwise. The C<init> and
794C<start> hooks will be called during this call.
795
796=cut
797
798sub new {
799 my ($class, $env, @args) = @_;
800
801 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
802}
803
769=item $term->destroy 804=item $term->destroy
770 805
771Destroy the terminal object (close the window, free resources etc.). 806Destroy the terminal object (close the window, free resources
807etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
808watchers (timers, io watchers) are still active.
772 809
773=item $isset = $term->option ($optval[, $set]) 810=item $isset = $term->option ($optval[, $set])
774 811
775Returns true if the option specified by C<$optval> is enabled, and 812Returns true if the option specified by C<$optval> is enabled, and
776optionally change it. All option values are stored by name in the hash 813optionally change it. All option values are stored by name in the hash
826 my ($self, $name) = (shift, shift); 863 my ($self, $name) = (shift, shift);
827 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 864 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
828 &urxvt::term::_resource 865 &urxvt::term::_resource
829} 866}
830 867
868=item $value = $term->x_resource ($pattern)
869
870Returns the X-Resource for the given pattern, excluding the program or
871class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
872same value as used by this instance of rxvt-unicode. Returns C<undef> if no
873resource with that pattern exists.
874
875This method should only be called during the C<on_start> hook, as there is
876only one resource database per display, and later invocations might return
877the wrong resources.
878
831=item $success = $term->parse_keysym ($keysym_spec, $command_string) 879=item $success = $term->parse_keysym ($keysym_spec, $command_string)
832 880
833Adds a keymap translation exactly as specified via a resource. See the 881Adds a keymap translation exactly as specified via a resource. See the
834C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 882C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
835 883
1034 1082
1035=item $lines_in_scrollback = $term->nsaved 1083=item $lines_in_scrollback = $term->nsaved
1036 1084
1037Return various integers describing terminal characteristics. 1085Return various integers describing terminal characteristics.
1038 1086
1087=item $x_display = $term->display_id
1088
1089Return the DISPLAY used by rxvt-unicode.
1090
1039=item $lc_ctype = $term->locale 1091=item $lc_ctype = $term->locale
1040 1092
1041Returns the LC_CTYPE category string used by this rxvt-unicode. 1093Returns the LC_CTYPE category string used by this rxvt-unicode.
1042 1094
1043=item $x_display = $term->display_id 1095=item $env = $term->env
1044 1096
1045Return the DISPLAY used by rxvt-unicode. 1097Returns a copy of the environment in effect for the terminal as a hashref
1098similar to C<\%ENV>.
1099
1100=cut
1101
1102sub env {
1103 if (my $env = $_[0]->_env) {
1104 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1105 } else {
1106 +{ %ENV }
1107 }
1108}
1046 1109
1047=item $modifiermask = $term->ModLevel3Mask 1110=item $modifiermask = $term->ModLevel3Mask
1048 1111
1049=item $modifiermask = $term->ModMetaMask 1112=item $modifiermask = $term->ModMetaMask
1050 1113
1290 $item->{render} ||= sub { $_[0]{text} }; 1353 $item->{render} ||= sub { $_[0]{text} };
1291 1354
1292 push @{ $self->{item} }, $item; 1355 push @{ $self->{item} }, $item;
1293} 1356}
1294 1357
1358=item $popup->add_title ($title)
1359
1360Adds a non-clickable title to the popup.
1361
1362=cut
1363
1364sub add_title {
1365 my ($self, $title) = @_;
1366
1367 $self->add_item ({
1368 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1369 text => $title,
1370 activate => sub { },
1371 });
1372}
1373
1374=item $popup->add_separator ([$sepchr])
1375
1376Creates a separator, optionally using the character given as C<$sepchr>.
1377
1378=cut
1379
1295sub add_separator { 1380sub add_separator {
1296 my ($self, $sep) = @_; 1381 my ($self, $sep) = @_;
1297 1382
1298 $sep ||= "="; 1383 $sep ||= "=";
1299 1384
1303 render => sub { $sep x $self->{term}->ncol }, 1388 render => sub { $sep x $self->{term}->ncol },
1304 activate => sub { }, 1389 activate => sub { },
1305 }); 1390 });
1306} 1391}
1307 1392
1308sub add_title { 1393=item $popup->add_button ($text, $cb)
1309 my ($self, $title) = @_;
1310 1394
1311 $self->add_item ({ 1395Adds a clickable button to the popup. C<$cb> is called whenever it is
1312 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" }, 1396selected.
1313 text => $title, 1397
1314 activate => sub { }, 1398=cut
1315 });
1316}
1317 1399
1318sub add_button { 1400sub add_button {
1319 my ($self, $text, $cb) = @_; 1401 my ($self, $text, $cb) = @_;
1320 1402
1321 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1403 $self->add_item ({ type => "button", text => $text, activate => $cb});
1322} 1404}
1405
1406=item $popup->add_toggle ($text, $cb, $initial_value)
1407
1408Adds a toggle/checkbox item to the popup. Teh callback gets called
1409whenever it gets toggled, with a boolean indicating its value as its first
1410argument.
1411
1412=cut
1323 1413
1324sub add_toggle { 1414sub add_toggle {
1325 my ($self, $text, $cb, $value) = @_; 1415 my ($self, $text, $cb, $value) = @_;
1326 1416
1327 my $item; $item = { 1417 my $item; $item = {
1328 type => "button", 1418 type => "button",
1329 text => " $text", 1419 text => " $text",
1330 value => $value, 1420 value => $value,
1331 render => sub { ($_[0]{value} ? "* " : " ") . $text }, 1421 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1332 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, 1422 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1333 }; 1423 };
1334 1424
1335 $self->add_item ($item); 1425 $self->add_item ($item);
1336} 1426}
1427
1428=item $popup->show
1429
1430Displays the popup (which is initially hidden).
1431
1432=cut
1337 1433
1338sub show { 1434sub show {
1339 my ($self) = @_; 1435 my ($self) = @_;
1340 1436
1341 local $urxvt::popup::self = $self; 1437 local $urxvt::popup::self = $self;
1342 1438
1439 my $env = $self->{term}->env;
1440 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1441 delete $env->{LC_ALL};
1343 local $ENV{LC_ALL} = $self->{term}->locale; 1442 $env->{LC_CTYPE} = $self->{term}->locale;
1344 1443
1444 urxvt::term->new ($env, $self->{term}->resource ("name"),
1345 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1445 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1346 "--transient-for" => $self->{term}->parent, 1446 "--transient-for" => $self->{term}->parent,
1347 "-display" => $self->{term}->display_id, 1447 "-display" => $self->{term}->display_id,
1348 "-pe" => "urxvt-popup") 1448 "-pe" => "urxvt-popup")
1349 or die "unable to create popup window\n"; 1449 or die "unable to create popup window\n";
1350} 1450}
1351 1451
1352sub DESTROY { 1452sub DESTROY {
1353 my ($self) = @_; 1453 my ($self) = @_;
1354 1454
1355 delete $self->{term}{_destroy}{$self}; 1455 delete $self->{term}{_destroy}{$self};
1356 $self->{term}->ungrab; 1456 $self->{term}->ungrab;
1357} 1457}
1458
1459=back
1358 1460
1359=head2 The C<urxvt::timer> Class 1461=head2 The C<urxvt::timer> Class
1360 1462
1361This class implements timer watchers/events. Time is represented as a 1463This class implements timer watchers/events. Time is represented as a
1362fractional number of seconds since the epoch. Example: 1464fractional number of seconds since the epoch. Example:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines