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.187 by sf-exg, Sat Jul 24 10:20:26 2010 UTC vs.
Revision 1.211 by root, Wed Jun 6 14:34:03 2012 UTC

259The default pattern to match URLs can be overridden with the 259The default pattern to match URLs can be overridden with the
260C<matcher.pattern.0> resource, and additional patterns can be specified 260C<matcher.pattern.0> resource, and additional patterns can be specified
261with numbered patterns, in a manner similar to the "selection" extension. 261with numbered patterns, in a manner similar to the "selection" extension.
262The launcher can also be overridden on a per-pattern basis. 262The launcher can also be overridden on a per-pattern basis.
263 263
264It is possible to activate the most recently seen match from the keyboard. 264It is possible to activate the most recently seen match or a list of matches
265from the keyboard. Simply bind a keysym to "perl:matcher:last" or
265Simply bind a keysym to "perl:matcher" as seen in the example below. 266"perl:matcher:list" as seen in the example below.
266 267
267Example configuration: 268Example configuration:
268 269
269 URxvt.perl-ext: default,matcher 270 URxvt.perl-ext: default,matcher
270 URxvt.urlLauncher: sensible-browser 271 URxvt.urlLauncher: sensible-browser
271 URxvt.keysym.C-Delete: perl:matcher 272 URxvt.keysym.C-Delete: perl:matcher:last
273 URxvt.keysym.M-Delete: perl:matcher:list
272 URxvt.matcher.button: 1 274 URxvt.matcher.button: 1
273 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-] 275 URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
274 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$) 276 URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$)
275 URxvt.matcher.launcher.2: gvim +$2 $1 277 URxvt.matcher.launcher.2: gvim +$2 $1
276 278
393 395
394Displays a very simple digital clock in the upper right corner of the 396Displays a very simple digital clock in the upper right corner of the
395window. Illustrates overwriting the refresh callbacks to create your own 397window. Illustrates overwriting the refresh callbacks to create your own
396overlays or changes. 398overlays or changes.
397 399
400=item confirm-paste
401
402Displays a confirmation dialog when a paste containing at least a full
403line is detected.
404
405=item bell-command
406
407Runs the command specified by the C<URxvt.bell-command> resource when
408a bell event occurs. For example, the following pops up a notification
409bubble with the text "Beep, Beep" using notify-send:
410
411 URxvt.bell-command: notify-send "Beep, Beep"
412
398=back 413=back
399 414
400=head1 API DOCUMENTATION 415=head1 API DOCUMENTATION
401 416
402=head2 General API Considerations 417=head2 General API Considerations
431=item $octets 446=item $octets
432 447
433Either binary data or - more common - a text string encoded in a 448Either binary data or - more common - a text string encoded in a
434locale-specific way. 449locale-specific way.
435 450
451=item $keysym
452
453an integer that is a valid X11 keysym code. You can convert a string
454into a keysym and viceversa by using C<XStringToKeysym> and
455C<XKeysymToString>.
456
436=back 457=back
437 458
438=head2 Extension Objects 459=head2 Extension Objects
439 460
440Every perl extension is a perl class. A separate perl object is created 461Every perl extension is a perl class. A separate perl object is created
441for each terminal, and each terminal has its own set of extenion objects, 462for each terminal, and each terminal has its own set of extension objects,
442which are passed as the first parameter to hooks. So extensions can use 463which are passed as the first parameter to hooks. So extensions can use
443their C<$self> object without having to think about clashes with other 464their C<$self> object without having to think about clashes with other
444extensions or other terminals, with the exception of methods and members 465extensions or other terminals, with the exception of methods and members
445that begin with an underscore character C<_>: these are reserved for 466that begin with an underscore character C<_>: these are reserved for
446internal use. 467internal use.
651resource in the @@RXVT_NAME@@(1) manpage). 672resource in the @@RXVT_NAME@@(1) manpage).
652 673
653The event is simply the action string. This interface is assumed to change 674The event is simply the action string. This interface is assumed to change
654slightly in the future. 675slightly in the future.
655 676
677=item on_register_command $term, $keysym, $modifiermask, $string
678
679Called after parsing a keysym resource but before registering the
680associated binding. If this hook returns TRUE the binding is not
681registered. It can be used to modify a binding by calling
682C<register_command>.
683
656=item on_resize_all_windows $term, $new_width, $new_height 684=item on_resize_all_windows $term, $new_width, $new_height
657 685
658Called just after the new window size has been calculated, but before 686Called just after the new window size has been calculated, but before
659windows are actually being resized or hints are being set. If this hook 687windows are actually being resized or hints are being set. If this hook
660returns TRUE, setting of the window hints is being skipped. 688returns TRUE, setting of the window hints is being skipped.
734use Scalar::Util (); 762use Scalar::Util ();
735use List::Util (); 763use List::Util ();
736 764
737our $VERSION = 1; 765our $VERSION = 1;
738our $TERM; 766our $TERM;
739our @TERM_INIT; 767our @TERM_INIT; # should go, prevents async I/O etc.
740our @TERM_EXT; 768our @TERM_EXT; # should go, prevents async I/O etc.
741our @HOOKNAME; 769our @HOOKNAME;
742our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 770our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
743our %OPTION; 771our %OPTION;
744 772
745our $LIBDIR; 773our $LIBDIR;
793 821
794=over 4 822=over 4
795 823
796=item urxvt::fatal $errormessage 824=item urxvt::fatal $errormessage
797 825
798Fatally aborts execution with the given error message. Avoid at all 826Fatally aborts execution with the given error message (which should
799costs! The only time this is acceptable is when the terminal process 827include a trailing newline). Avoid at all costs! The only time this
800starts up. 828is acceptable (and useful) is in the init hook, where it prevents the
829terminal from starting up.
801 830
802=item urxvt::warn $string 831=item urxvt::warn $string
803 832
804Calls C<rxvt_warn> with the given string which should not include a 833Calls C<rxvt_warn> with the given string which should include a trailing
805newline. The module also overwrites the C<warn> builtin with a function 834newline. The module also overwrites the C<warn> builtin with a function
806that calls this function. 835that calls this function.
807 836
808Using this function has the advantage that its output ends up in the 837Using this function has the advantage that its output ends up in the
809correct place, e.g. on stderr of the connecting urxvtc client. 838correct place, e.g. on stderr of the connecting urxvtc client.
813=item @terms = urxvt::termlist 842=item @terms = urxvt::termlist
814 843
815Returns all urxvt::term objects that exist in this process, regardless of 844Returns all urxvt::term objects that exist in this process, regardless of
816whether they are started, being destroyed etc., so be careful. Only term 845whether they are started, being destroyed etc., so be careful. Only term
817objects that have perl extensions attached will be returned (because there 846objects that have perl extensions attached will be returned (because there
818is no urxvt::term objet associated with others). 847is no urxvt::term object associated with others).
819 848
820=item $time = urxvt::NOW 849=item $time = urxvt::NOW
821 850
822Returns the "current time" (as per the event loop). 851Returns the "current time" (as per the event loop).
823 852
866 895
867=item $rend = urxvt::OVERLAY_RSTYLE 896=item $rend = urxvt::OVERLAY_RSTYLE
868 897
869Return the rendition mask used for overlays by default. 898Return the rendition mask used for overlays by default.
870 899
871=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 900=item $rendbit = urxvt::RS_Bold, urxvt::RS_Italic, urxvt::RS_Blink,
901urxvt::RS_RVid, urxvt::RS_Uline
872 902
873Return the bit that enabled bold, italic, blink, reverse-video and 903Return the bit that enabled bold, italic, blink, reverse-video and
874underline, respectively. To enable such a style, just logically OR it into 904underline, respectively. To enable such a style, just logically OR it into
875the bitset. 905the bitset.
876 906
913 }; 943 };
914} 944}
915 945
916no warnings 'utf8'; 946no warnings 'utf8';
917 947
948sub parse_resource {
949 my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
950
951 $term->scan_meta;
952
953 my $r = $term->{meta}{resource};
954 while (my ($pattern, $v) = each %$r) {
955 $name =~ y/-/./ if $isarg;
956
957 if (
958 $pattern =~ s/\*$//
959 ? $pattern eq substr $name, 0, length $pattern
960 : $pattern eq $name
961 ) {
962 $name = "$urxvt::RESCLASS.$name";
963
964 push @TERM_EXT, $v->[0];
965
966 if ($v->[1] eq "boolean") {
967 $term->put_option_db ($name, $flag ? "true" : "false");
968 return 1;
969 } else {
970 $term->put_option_db ($name, $value);
971 return 1 + 2;
972 }
973 }
974 }
975
976 0
977}
978
979sub usage {
980 my ($term, $usage_type) = @_;
981
982 $term->scan_meta;
983
984 my $r = $term->{meta}{resource};
985
986 for my $pattern (sort keys %$r) {
987 my ($ext, $type, $desc) = @{ $r->{$pattern} };
988
989 $desc .= " (-pe $ext)";
990
991 if ($usage_type == 1) {
992 $pattern =~ y/./-/;
993 $pattern =~ s/\*/.../g;
994
995 if ($type eq "boolean") {
996 urxvt::log sprintf " -%-30s %s\n", "/+$pattern", $desc;
997 } else {
998 urxvt::log sprintf " -%-30s %s\n", "$pattern $type", $desc;
999 }
1000 } else {
1001 urxvt::log sprintf " %-31s %s\n", "$pattern:", $type;
1002 }
1003 }
1004}
1005
918my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 1006my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
919 1007
920sub verbose { 1008sub verbose {
921 my ($level, $msg) = @_; 1009 my ($level, $msg) = @_;
922 warn "$msg\n" if $level <= $verbosity; 1010 warn "$msg\n" if $level <= $verbosity;
958sub invoke { 1046sub invoke {
959 local $TERM = shift; 1047 local $TERM = shift;
960 my $htype = shift; 1048 my $htype = shift;
961 1049
962 if ($htype == 0) { # INIT 1050 if ($htype == 0) { # INIT
963 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 1051 my @dirs = $TERM->perl_libdirs;
964 1052
965 my %ext_arg; 1053 my %ext_arg;
966 1054
967 { 1055 {
968 my @init = @TERM_INIT; 1056 my @init = @TERM_INIT;
1129=head2 The C<urxvt::anyevent> Class 1217=head2 The C<urxvt::anyevent> Class
1130 1218
1131The sole purpose of this class is to deliver an interface to the 1219The sole purpose of this class is to deliver an interface to the
1132C<AnyEvent> module - any module using it will work inside urxvt without 1220C<AnyEvent> module - any module using it will work inside urxvt without
1133further programming. The only exception is that you cannot wait on 1221further programming. The only exception is that you cannot wait on
1134condition variables, but non-blocking condvar use is ok. What this means 1222condition variables, but non-blocking condvar use is ok.
1135is that you cannot use blocking APIs, but the non-blocking variant should 1223
1136work. 1224In practical terms this means is that you cannot use blocking APIs, but
1225the non-blocking variant should work.
1137 1226
1138=cut 1227=cut
1139 1228
1140our $VERSION = '5.23'; 1229our $VERSION = '5.23';
1141 1230
1200 1289
1201sub DESTROY { 1290sub DESTROY {
1202 $_[0][1]->stop; 1291 $_[0][1]->stop;
1203} 1292}
1204 1293
1294# only needed for AnyEvent < 6 compatibility
1205sub one_event { 1295sub one_event {
1206 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API"; 1296 Carp::croak "AnyEvent->one_event blocking wait unsupported in urxvt, use a non-blocking API";
1207} 1297}
1208 1298
1209package urxvt::term; 1299package urxvt::term;
1238 $proxy->enable ($name => $ref); 1328 $proxy->enable ($name => $ref);
1239 } 1329 }
1240 } 1330 }
1241} 1331}
1242 1332
1333sub perl_libdirs {
1334 map { split /:/ }
1335 $_[0]->resource ("perl_lib"),
1336 $ENV{URXVT_PERL_LIB},
1337 "$ENV{HOME}/.urxvt/ext",
1338 "$LIBDIR/perl"
1339}
1340
1341sub scan_meta {
1342 my ($self) = @_;
1343 my @libdirs = perl_libdirs $self;
1344
1345 return if $self->{meta_libdirs} eq join "\x00", @libdirs;
1346
1347 my %meta;
1348
1349 $self->{meta_libdirs} = join "\x00", @libdirs;
1350 $self->{meta} = \%meta;
1351
1352 for my $dir (reverse @libdirs) {
1353 opendir my $fh, $dir
1354 or next;
1355 for my $ext (readdir $fh) {
1356 $ext ne "."
1357 and $ext ne ".."
1358 and open my $fh, "<", "$dir/$ext"
1359 or next;
1360
1361 while (<$fh>) {
1362 if (/^#:META:X_RESOURCE:(.*)/) {
1363 my ($pattern, $type, $desc) = split /:/, $1;
1364 $pattern =~ s/^%\./$ext./g; # $$ in pattern == extension name
1365 if ($pattern =~ /[^a-zA-Z\*\.]/) {
1366 warn "$dir/$ext: meta resource '$pattern' contains illegal characters (not alphanumeric nor . nor *)\n";
1367 } else {
1368 $meta{resource}{$pattern} = [$ext, $type, $desc];
1369 }
1370 } elsif (/^\s*(?:#|$)/) {
1371 # skip other comments and empty lines
1372 } else {
1373 last; # stop parsing on first non-empty non-comment line
1374 }
1375 }
1376 }
1377 }
1378}
1379
1243=item $term = new urxvt::term $envhashref, $rxvtname, [arg...] 1380=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
1244 1381
1245Creates a new terminal, very similar as if you had started it with system 1382Creates a new terminal, very similar as if you had started it with system
1246C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like 1383C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
1247hash which defines the environment of the new terminal. 1384hash which defines the environment of the new terminal.
1301C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. 1438C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
1302 1439
1303Here is a likely non-exhaustive list of option names, please see the 1440Here is a likely non-exhaustive list of option names, please see the
1304source file F</src/optinc.h> to see the actual list: 1441source file F</src/optinc.h> to see the actual list:
1305 1442
1306 borderLess console cursorBlink cursorUnderline hold iconic insecure 1443 borderLess buffered console cursorBlink cursorUnderline hold iconic
1307 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage 1444 insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
1308 override-redirect pastableTabs pointerBlank reverseVideo scrollBar 1445 mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
1309 scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput 1446 pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
1310 scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs 1447 scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
1311 transparent tripleclickwords utmpInhibit visualBell 1448 secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
1449 urgentOnBell utmpInhibit visualBell
1312 1450
1313=item $value = $term->resource ($name[, $newval]) 1451=item $value = $term->resource ($name[, $newval])
1314 1452
1315Returns the current resource value associated with a given name and 1453Returns the current resource value associated with a given name and
1316optionally sets a new value. Setting values is most useful in the C<init> 1454optionally sets a new value. Setting values is most useful in the C<init>
1329 1467
1330Here is a likely non-exhaustive list of resource names, not all of which 1468Here is a likely non-exhaustive list of resource names, not all of which
1331are supported in every build, please see the source file F</src/rsinc.h> 1469are supported in every build, please see the source file F</src/rsinc.h>
1332to see the actual list: 1470to see the actual list:
1333 1471
1334 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 1472 answerbackstring backgroundPixmap backspace_key blendtype blurradius
1335 borderLess chdir color cursorBlink cursorUnderline cutchars delete_key 1473 boldFont boldItalicFont borderLess buffered chdir color cursorBlink
1336 display_name embed ext_bwidth fade font geometry hold iconName 1474 cursorUnderline cutchars delete_key depth display_name embed ext_bwidth
1337 imFont imLocale inputMethod insecure int_bwidth intensityStyles 1475 fade font geometry hold iconName iconfile imFont imLocale inputMethod
1338 italicFont jumpScroll lineSpace letterSpace loginShell mapAlert meta8 1476 insecure int_bwidth intensityStyles iso14755 iso14755_52 italicFont
1477 jumpScroll letterSpace lineSpace loginShell mapAlert meta8 modifier
1339 modifier mouseWheelScrollPage name override_redirect pastableTabs path 1478 mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
1340 perl_eval perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay 1479 perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
1341 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar 1480 preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
1342 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness 1481 scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
1343 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle 1482 scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
1344 secondaryScreen secondaryScroll shade term_name title 1483 secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
1345 transient_for transparent transparent_all tripleclickwords utmpInhibit 1484 term_name title transient_for transparent tripleclickwords urgentOnBell
1346 visualBell 1485 utmpInhibit visualBell
1347 1486
1348=cut 1487=cut
1349 1488
1350sub resource($$;$) { 1489sub resource($$;$) {
1351 my ($self, $name) = (shift, shift); 1490 my ($self, $name) = (shift, shift);
1362 1501
1363This method should only be called during the C<on_start> hook, as there is 1502This method should only be called during the C<on_start> hook, as there is
1364only one resource database per display, and later invocations might return 1503only one resource database per display, and later invocations might return
1365the wrong resources. 1504the wrong resources.
1366 1505
1367=item $success = $term->parse_keysym ($keysym_spec, $command_string) 1506=item $value = $term->x_resource_boolean ($pattern)
1368 1507
1508Like C<x_resource>, above, but interprets the string value as a boolean
1509and returns C<1> for true values, C<0> for false values and C<undef> if
1510the resource or option isn't specified.
1511
1512You should always use this method to parse boolean resources.
1513
1514=cut
1515
1516sub x_resource_boolean {
1517 my $res = &x_resource;
1518
1519 $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
1520}
1521
1522=item $success = $term->parse_keysym ($key, $octets)
1523
1369Adds a keymap translation exactly as specified via a resource. See the 1524Adds a key binding exactly as specified via a resource. See the
1370C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 1525C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
1526
1527=item $term->register_command ($keysym, $modifiermask, $string)
1528
1529Adds a key binding. This is a lower level api compared to
1530C<parse_keysym>, as it expects a parsed key description, and can be
1531used only inside either the C<on_init> hook, to add a binding, or the
1532C<on_register_command> hook, to modify a parsed binding.
1371 1533
1372=item $rend = $term->rstyle ([$new_rstyle]) 1534=item $rend = $term->rstyle ([$new_rstyle])
1373 1535
1374Return and optionally change the current rendition. Text that is output by 1536Return and optionally change the current rendition. Text that is output by
1375the terminal application will use this style. 1537the terminal application will use this style.
1588 1750
1589Adds the specified events to the vt event mask. Useful e.g. when you want 1751Adds the specified events to the vt event mask. Useful e.g. when you want
1590to receive pointer events all the times: 1752to receive pointer events all the times:
1591 1753
1592 $term->vt_emask_add (urxvt::PointerMotionMask); 1754 $term->vt_emask_add (urxvt::PointerMotionMask);
1755
1756=item $term->set_urgency ($set)
1757
1758Enable/disable the urgency hint on the toplevel window.
1593 1759
1594=item $term->focus_in 1760=item $term->focus_in
1595 1761
1596=item $term->focus_out 1762=item $term->focus_out
1597 1763
1913=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height) 2079=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1914 2080
1915=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y) 2081=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1916 2082
1917=item $term->XChangeInput ($window, $add_events[, $del_events]) 2083=item $term->XChangeInput ($window, $add_events[, $del_events])
2084
2085=item $keysym = $term->XStringToKeysym ($string)
2086
2087=item $string = $term->XKeysymToString ($keysym)
1918 2088
1919Various X or X-related functions. The C<$term> object only serves as 2089Various X or X-related functions. The C<$term> object only serves as
1920the source of the display, otherwise those functions map more-or-less 2090the source of the display, otherwise those functions map more-or-less
1921directly onto the X functions of the same name. 2091directly onto the X functions of the same name.
1922 2092
2244 2414
2245=back 2415=back
2246 2416
2247=head1 AUTHOR 2417=head1 AUTHOR
2248 2418
2249 Marc Lehmann <pcg@goof.com> 2419 Marc Lehmann <schmorp@schmorp.de>
2250 http://software.schmorp.de/pkg/rxvt-unicode 2420 http://software.schmorp.de/pkg/rxvt-unicode
2251 2421
2252=cut 2422=cut
2253 2423
22541 24241

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines