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.73 by root, Tue Jan 10 04:23:39 2006 UTC vs.
Revision 1.83 by root, Thu Jan 12 01:38:37 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
83=item mark-urls 87=item mark-urls
84 88
85Uses 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 middle-clicked, the program specified in the
91resource C<urlLauncher> (default C<x-www-browser>) will be started.
86 92
87=item block-graphics-to-ascii 93=item block-graphics-to-ascii
88 94
89A 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,
90by replacing all line-drawing characters (U+2500 .. U+259F) by a 96by replacing all line-drawing characters (U+2500 .. U+259F) by a
95Displays 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
96window. Illustrates overwriting the refresh callbacks to create your own 102window. Illustrates overwriting the refresh callbacks to create your own
97overlays or changes. 103overlays or changes.
98 104
99=back 105=back
106
107=head1 API DOCUMENTATION
100 108
101=head2 General API Considerations 109=head2 General API Considerations
102 110
103All objects (such as terminals, time watchers etc.) are typical 111All objects (such as terminals, time watchers etc.) are typical
104reference-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
117=over 4 125=over 4
118 126
119=item $text 127=item $text
120 128
121Rxvt-unicodes special way of encoding text, where one "unicode" character 129Rxvt-unicodes special way of encoding text, where one "unicode" character
122always 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.
123 131
124=item $string 132=item $string
125 133
126A 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
127characters and is to be distinguished with text encoded in a specific 135characters and is to be distinguished with text encoded in a specific
337 345
338subwindow. 346subwindow.
339 347
340=back 348=back
341 349
342=head2 Variables in the C<urxvt> Package
343
344=over 4
345
346=item $urxvt::TERM
347
348The current terminal. This variable stores the current C<urxvt::term>
349object, whenever a callback/hook is executing.
350
351=back
352
353=head2 Functions in the C<urxvt> Package
354
355=over 4
356
357=item $term = new urxvt [arg...]
358
359Creates a new terminal, very similar as if you had started it with
360C<system $binfile, arg...>. Croaks (and probably outputs an error message)
361if the new instance couldn't be created. Returns C<undef> if the new
362instance didn't initialise perl, and the terminal object otherwise. The
363C<init> and C<start> hooks will be called during the call.
364
365=item urxvt::fatal $errormessage
366
367Fatally aborts execution with the given error message. Avoid at all
368costs! The only time this is acceptable is when the terminal process
369starts up.
370
371=item urxvt::warn $string
372
373Calls C<rxvt_warn> with the given string which should not include a
374newline. The module also overwrites the C<warn> builtin with a function
375that calls this function.
376
377Using this function has the advantage that its output ends up in the
378correct place, e.g. on stderr of the connecting urxvtc client.
379
380=item $is_safe = urxvt::safe
381
382Returns true when it is safe to do potentially unsafe things, such as
383evaluating perl code specified by the user. This is true when urxvt was
384started setuid or setgid.
385
386=item $time = urxvt::NOW
387
388Returns the "current time" (as per the event loop).
389
390=item urxvt::CurrentTime
391
392=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
393Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
394Button4Mask, Button5Mask, AnyModifier
395
396Various constants for use in X calls and event processing.
397
398=back
399
400=head2 RENDITION
401
402Rendition bitsets contain information about colour, font, font styles and
403similar information for each screen cell.
404
405The following "macros" deal with changes in rendition sets. You should
406never just create a bitset, you should always modify an existing one,
407as they contain important information required for correct operation of
408rxvt-unicode.
409
410=over 4
411
412=item $rend = urxvt::DEFAULT_RSTYLE
413
414Returns the default rendition, as used when the terminal is starting up or
415being reset. Useful as a base to start when creating renditions.
416
417=item $rend = urxvt::OVERLAY_RSTYLE
418
419Return the rendition mask used for overlays by default.
420
421=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
422
423Return the bit that enabled bold, italic, blink, reverse-video and
424underline, respectively. To enable such a style, just logically OR it into
425the bitset.
426
427=item $foreground = urxvt::GET_BASEFG $rend
428
429=item $background = urxvt::GET_BASEBG $rend
430
431Return the foreground/background colour index, respectively.
432
433=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
434
435=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
436
437Replace the foreground/background colour in the rendition mask with the
438specified one.
439
440=item $value = urxvt::GET_CUSTOM ($rend)
441
442Return the "custom" value: Every rendition has 5 bits for use by
443extensions. They can be set and changed as you like and are initially
444zero.
445
446=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
447
448Change the custom value.
449
450=back
451
452=cut 350=cut
453 351
454package urxvt; 352package urxvt;
455 353
456use utf8; 354use utf8;
467 365
468our $LIBDIR; 366our $LIBDIR;
469our $RESNAME; 367our $RESNAME;
470our $RESCLASS; 368our $RESCLASS;
471our $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
472 489
473BEGIN { 490BEGIN {
474 urxvt->bootstrap; 491 urxvt->bootstrap;
475 492
476 # overwrite perl's warn 493 # overwrite perl's warn
479 $msg .= "\n" 496 $msg .= "\n"
480 unless $msg =~ /\n$/; 497 unless $msg =~ /\n$/;
481 urxvt::warn ($msg); 498 urxvt::warn ($msg);
482 }; 499 };
483 500
501 # %ENV is the original startup environment
484 delete $ENV{IFS}; 502 delete $ENV{IFS};
485 delete $ENV{CDPATH}; 503 delete $ENV{CDPATH};
486 delete $ENV{BASH_ENV}; 504 delete $ENV{BASH_ENV};
487 $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";
488} 506}
672 690
673=head2 The C<urxvt::anyevent> Class 691=head2 The C<urxvt::anyevent> Class
674 692
675The 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
676C<AnyEvent> module - any module using it will work inside urxvt without 694C<AnyEvent> module - any module using it will work inside urxvt without
677further work. The only exception is that you cannot wait on condition 695further programming. The only exception is that you cannot wait on
678variables, 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
679cannot use blocking APIs, but the non-blocking variant should work. 697is that you cannot use blocking APIs, but the non-blocking variant should
698work.
680 699
681=cut 700=cut
682 701
683our $VERSION = 1; 702our $VERSION = 1;
684 703
761 $proxy->enable ($name => $ref); 780 $proxy->enable ($name => $ref);
762 } 781 }
763 } 782 }
764} 783}
765 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
766=item $term->destroy 804=item $term->destroy
767 805
768Destroy 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.
769 809
770=item $isset = $term->option ($optval[, $set]) 810=item $isset = $term->option ($optval[, $set])
771 811
772Returns true if the option specified by C<$optval> is enabled, and 812Returns true if the option specified by C<$optval> is enabled, and
773optionally 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
823 my ($self, $name) = (shift, shift); 863 my ($self, $name) = (shift, shift);
824 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 864 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
825 &urxvt::term::_resource 865 &urxvt::term::_resource
826} 866}
827 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
828=item $success = $term->parse_keysym ($keysym_spec, $command_string) 879=item $success = $term->parse_keysym ($keysym_spec, $command_string)
829 880
830Adds a keymap translation exactly as specified via a resource. See the 881Adds a keymap translation exactly as specified via a resource. See the
831C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 882C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
832 883
1031 1082
1032=item $lines_in_scrollback = $term->nsaved 1083=item $lines_in_scrollback = $term->nsaved
1033 1084
1034Return various integers describing terminal characteristics. 1085Return various integers describing terminal characteristics.
1035 1086
1087=item $x_display = $term->display_id
1088
1089Return the DISPLAY used by rxvt-unicode.
1090
1036=item $lc_ctype = $term->locale 1091=item $lc_ctype = $term->locale
1037 1092
1038Returns the LC_CTYPE category string used by this rxvt-unicode. 1093Returns the LC_CTYPE category string used by this rxvt-unicode.
1039 1094
1040=item $x_display = $term->display_id 1095=item $env = $term->env
1041 1096
1042Return 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}
1043 1109
1044=item $modifiermask = $term->ModLevel3Mask 1110=item $modifiermask = $term->ModLevel3Mask
1045 1111
1046=item $modifiermask = $term->ModMetaMask 1112=item $modifiermask = $term->ModMetaMask
1047 1113
1287 $item->{render} ||= sub { $_[0]{text} }; 1353 $item->{render} ||= sub { $_[0]{text} };
1288 1354
1289 push @{ $self->{item} }, $item; 1355 push @{ $self->{item} }, $item;
1290} 1356}
1291 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
1292sub add_separator { 1380sub add_separator {
1293 my ($self, $sep) = @_; 1381 my ($self, $sep) = @_;
1294 1382
1295 $sep ||= "="; 1383 $sep ||= "=";
1296 1384
1300 render => sub { $sep x $self->{term}->ncol }, 1388 render => sub { $sep x $self->{term}->ncol },
1301 activate => sub { }, 1389 activate => sub { },
1302 }); 1390 });
1303} 1391}
1304 1392
1305sub add_title { 1393=item $popup->add_button ($text, $cb)
1306 my ($self, $title) = @_;
1307 1394
1308 $self->add_item ({ 1395Adds a clickable button to the popup. C<$cb> is called whenever it is
1309 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" }, 1396selected.
1310 text => $title, 1397
1311 activate => sub { }, 1398=cut
1312 });
1313}
1314 1399
1315sub add_button { 1400sub add_button {
1316 my ($self, $text, $cb) = @_; 1401 my ($self, $text, $cb) = @_;
1317 1402
1318 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1403 $self->add_item ({ type => "button", text => $text, activate => $cb});
1319} 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
1320 1413
1321sub add_toggle { 1414sub add_toggle {
1322 my ($self, $text, $cb, $value) = @_; 1415 my ($self, $text, $cb, $value) = @_;
1323 1416
1324 my $item; $item = { 1417 my $item; $item = {
1325 type => "button", 1418 type => "button",
1326 text => " $text", 1419 text => " $text",
1327 value => $value, 1420 value => $value,
1328 render => sub { ($_[0]{value} ? "* " : " ") . $text }, 1421 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1329 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, 1422 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1330 }; 1423 };
1331 1424
1332 $self->add_item ($item); 1425 $self->add_item ($item);
1333} 1426}
1427
1428=item $popup->show
1429
1430Displays the popup (which is initially hidden).
1431
1432=cut
1334 1433
1335sub show { 1434sub show {
1336 my ($self) = @_; 1435 my ($self) = @_;
1337 1436
1338 local $urxvt::popup::self = $self; 1437 local $urxvt::popup::self = $self;
1339 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};
1340 local $ENV{LC_ALL} = $self->{term}->locale; 1442 $env->{LC_CTYPE} = $self->{term}->locale;
1341 1443
1444 urxvt::term->new ($env, $self->{term}->resource ("name"),
1342 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,
1343 "--transient-for" => $self->{term}->parent, 1446 "--transient-for" => $self->{term}->parent,
1344 "-display" => $self->{term}->display_id, 1447 "-display" => $self->{term}->display_id,
1345 "-pe" => "urxvt-popup") 1448 "-pe" => "urxvt-popup")
1346 or die "unable to create popup window\n"; 1449 or die "unable to create popup window\n";
1347} 1450}
1348 1451
1349sub DESTROY { 1452sub DESTROY {
1350 my ($self) = @_; 1453 my ($self) = @_;
1351 1454
1352 delete $self->{term}{_destroy}{$self}; 1455 delete $self->{term}{_destroy}{$self};
1353 $self->{term}->ungrab; 1456 $self->{term}->ungrab;
1354} 1457}
1458
1459=back
1355 1460
1356=head2 The C<urxvt::timer> Class 1461=head2 The C<urxvt::timer> Class
1357 1462
1358This class implements timer watchers/events. Time is represented as a 1463This class implements timer watchers/events. Time is represented as a
1359fractional 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