--- rxvt-unicode/src/urxvt.pm 2006/01/07 04:19:43 1.43 +++ rxvt-unicode/src/urxvt.pm 2006/01/09 22:41:41 1.69 @@ -19,8 +19,8 @@ =head1 DESCRIPTION -Everytime a terminal object gets created, scripts specified via the -C resource are loaded and associated with it. +Everytime a terminal object gets created, extension scripts specified via +the C resource are loaded and associated with it. Scripts are compiled in a 'use strict' and 'use utf8' environment, and thus must be encoded as UTF-8. @@ -39,7 +39,7 @@ =over 4 -=item selection +=item selection (enabled by default) Intelligent selection. This extension tries to be more intelligent when the user extends selections (double-click). Right now, it tries to select @@ -58,6 +58,24 @@ =back +=item option-popup (enabled by default) + +Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at +runtime. + +=item selection-popup (enabled by default) + +Binds a popup menu to Ctrl-Button3 that lets you convert the selection +text into various other formats/action. + +=item searchable-scrollback (enabled by default) + +Adds regex search functionality to the scrollback buffer, triggered by a +hotkey (default: C). When in search mode, terminal input/output is +suspended, C starts an incremental regex search, C searches further, +C

jumps to the previous match. C leaves search mode at the +current position and C returns to the original position. + =item digital-clock Displays a digital clock using the built-in overlay. @@ -116,22 +134,52 @@ =back +=head2 Extension Objects + +Very perl extension is a perl class. A separate perl object is created +for each terminal and each extension and passed as the first parameter to +hooks. So extensions can use their C<$self> object without having to think +about other extensions, with the exception of methods and members that +begin with an underscore character C<_>: these are reserved for internal +use. + +Although it isn't a C object, you can call all methods of the +C class on this object. + +It has the following methods and data members: + +=over 4 + +=item $urxvt_term = $self->{term} + +Returns the C object associated with this instance of the +extension. This member I be changed in any way. + +=item $self->enable ($hook_name => $cb, [$hook_name => $cb..]) + +Dynamically enable the given hooks (named without the C prefix) for +this extension, replacing any previous hook. This is useful when you want +to overwrite time-critical hooks only temporarily. + +=item $self->disable ($hook_name[, $hook_name..]) + +Dynamically disable the given hooks. + +=back + =head2 Hooks The following subroutines can be declared in extension files, and will be called whenever the relevant event happens. -The first argument passed to them is an object private to each terminal -and extension package. You can call all C methods on it, but -its not a real C object. Instead, the real C -object that is shared between all packages is stored in the C -member. - -All of them must return a boolean value. If it is true, then the event -counts as being I, and the invocation of other hooks is skipped, -and the relevant action might not be carried out by the C++ code. +The first argument passed to them is an extension oject as described in +the in the C section. + +B of these hooks must return a boolean value. If it is true, then the +event counts as being I, and the invocation of other hooks is +skipped, and the relevant action might not be carried out by the C++ code. -When in doubt, return a false value (preferably C<()>). +I<< When in doubt, return a false value (preferably C<()>). >> =over 4 @@ -180,16 +228,6 @@ See the F example extension. -=item on_focus_in $term - -Called whenever the window gets the keyboard focus, before urxvt does -focus in processing. - -=item on_focus_out $term - -Called wheneever the window loses keyboard focus, before urxvt does focus -out processing. - =item on_view_change $term, $offset Called whenever the view offset changes, i..e the user or program @@ -206,10 +244,6 @@ $nrow - 1) represent the lines to be scrolled out). C<$saved> is the total number of lines that will be in the scrollback buffer. -=item on_tty_activity $term *NYI* - -Called whenever the program(s) running in the urxvt window send output. - =item on_osc_seq $term, $string Called whenever the B command sequence (OSC = @@ -262,9 +296,19 @@ C action bound to it (see description of the B resource in the @@RXVT_NAME@@(1) manpage). -=item on_key_press $term, $event, $octets +=item on_focus_in $term + +Called whenever the window gets the keyboard focus, before rxvt-unicode +does focus in processing. -=item on_key_release $term, $event +=item on_focus_out $term + +Called wheneever the window loses keyboard focus, before rxvt-unicode does +focus out processing. + +=item on_key_press $term, $event, $keysym, $octets + +=item on_key_release $term, $event, $keysym =item on_button_press $term, $event @@ -272,6 +316,10 @@ =item on_motion_notify $term, $event +=item on_map_notify $term, $event + +=item on_unmap_notify $term, $event + Called whenever the corresponding X event is received for the terminal If the hook returns true, then the even will be ignored by rxvt-unicode. @@ -324,10 +372,24 @@ Using this function has the advantage that its output ends up in the correct place, e.g. on stderr of the connecting urxvtc client. +=item $is_safe = urxvt::safe + +Returns true when it is safe to do potentially unsafe things, such as +evaluating perl code specified by the user. This is true when urxvt was +started setuid or setgid. + =item $time = urxvt::NOW Returns the "current time" (as per the event loop). +=item urxvt::CurrentTime + +=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, +Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, +Button4Mask, Button5Mask, AnyModifier + +Various constants for use in X calls and event processing. + =back =head2 RENDITION @@ -386,11 +448,17 @@ package urxvt; +use utf8; use strict; +use Carp (); use Scalar::Util (); +use List::Util (); +our $VERSION = 1; our $TERM; our @HOOKNAME; +our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; +our %OPTION; our $LIBDIR; BEGIN { @@ -403,6 +471,11 @@ unless $msg =~ /\n$/; urxvt::warn ($msg); }; + + delete $ENV{IFS}; + delete $ENV{CDPATH}; + delete $ENV{BASH_ENV}; + $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin"; } my @hook_count; @@ -413,44 +486,30 @@ warn "$msg\n" if $level <= $verbosity; } -# find on_xxx subs in the package and register them -# as hooks -sub register_package($) { - my ($pkg) = @_; - - for my $htype (0.. $#HOOKNAME) { - my $name = $HOOKNAME[$htype]; - - my $ref = $pkg->can ("on_" . lc $name) - or next; - - $TERM->{_hook}[$htype]{$pkg} = $ref; - $hook_count[$htype]++ - or set_should_invoke $htype, 1; - } -} - -my $script_pkg = "script0000"; -my %script_pkg; +my $extension_pkg = "extension0000"; +my %extension_pkg; # load a single script into its own package, once only -sub script_package($) { +sub extension_package($) { my ($path) = @_; - $script_pkg{$path} ||= do { - my $pkg = "urxvt::" . ($script_pkg++); + $extension_pkg{$path} ||= do { + my $pkg = "urxvt::" . ($extension_pkg++); - verbose 3, "loading script '$path' into package '$pkg'"; + verbose 3, "loading extension '$path' into package '$pkg'"; open my $fh, "<:raw", $path or die "$path: $!"; - my $source = "package $pkg; use strict; use utf8;\n" - . "#line 1 \"$path\"\n{\n" - . (do { local $/; <$fh> }) - . "\n};\n1"; + my $source = untaint + "package $pkg; use strict; use utf8;\n" + . "use base urxvt::term::proxy::;\n" + . "#line 1 \"$path\"\n{\n" + . (do { local $/; <$fh> }) + . "\n};\n1"; - eval $source or die "$path: $@"; + eval $source + or die "$path: $@"; $pkg } @@ -465,16 +524,33 @@ if ($htype == 0) { # INIT my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); + + my %ext_arg; - for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { + for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { + if ($_ eq "default") { + $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); + } elsif (/^-(.*)$/) { + delete $ext_arg{$1}; + } elsif (/^([^<]+)<(.*)>$/) { + push @{ $ext_arg{$1} }, $2; + } else { + $ext_arg{$_} ||= []; + } + } + + while (my ($ext, $argv) = each %ext_arg) { my @files = grep -f $_, map "$_/$ext", @dirs; if (@files) { - register_package script_package $files[0]; + $TERM->register_package (extension_package $files[0], $argv); } else { warn "perl extension '$ext' not found in perl library search path\n"; } } + + eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval"); + warn $@ if $@; } $retval = undef; @@ -486,20 +562,18 @@ keys %$cb; while (my ($pkg, $cb) = each %$cb) { - $retval = $cb->( - $TERM->{_pkg}{$pkg} ||= do { - my $proxy = bless { }, urxvt::term::proxy::; - Scalar::Util::weaken ($proxy->{term} = $TERM); - $proxy - }, - @_, - ) and last; + $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } + and last; + + if ($@) { + $TERM->ungrab; # better to lose the grab than the session + warn $@; + } } } if ($htype == 1) { # DESTROY - # remove hooks if unused - if (my $hook = $TERM->{_hook}) { + if (my $hook = delete $TERM->{_hook}) { for my $htype (0..$#$hook) { $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } or set_should_invoke $htype, 0; @@ -516,29 +590,190 @@ $retval } -sub urxvt::term::proxy::AUTOLOAD { - $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ - or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; +# urxvt::term::proxy + +package urxvt::term::proxy; + +sub enable { + my ($self, %hook) = @_; + my $pkg = $self->{_pkg}; + + while (my ($name, $cb) = each %hook) { + my $htype = $HOOKTYPE{uc $name}; + defined $htype + or Carp::croak "unsupported hook type '$name'"; + + unless (exists $self->{term}{_hook}[$htype]{$pkg}) { + $hook_count[$htype]++ + or urxvt::set_should_invoke $htype, 1; + } + + $self->{term}{_hook}[$htype]{$pkg} = $cb; + } +} + +sub disable { + my ($self, @hook) = @_; + my $pkg = $self->{_pkg}; + + for my $name (@hook) { + my $htype = $HOOKTYPE{uc $name}; + defined $htype + or Carp::croak "unsupported hook type '$name'"; + + if (delete $self->{term}{_hook}[$htype]{$pkg}) { + --$hook_count[$htype] + or urxvt::set_should_invoke $htype, 0; + } + } +} + +our $AUTOLOAD; + +sub AUTOLOAD { + $AUTOLOAD =~ /:([^:]+)$/ + or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable"; eval qq{ - sub $urxvt::term::proxy::AUTOLOAD { + sub $AUTOLOAD { my \$proxy = shift; \$proxy->{term}->$1 (\@_) } 1 } or die "FATAL: unable to compile method forwarder: $@"; - goto &$urxvt::term::proxy::AUTOLOAD; + goto &$AUTOLOAD; +} + +sub DESTROY { + # nop +} + +# urxvt::destroy_hook + +sub urxvt::destroy_hook::DESTROY { + ${$_[0]}->(); } +sub urxvt::destroy_hook(&) { + bless \shift, urxvt::destroy_hook:: +} + +package urxvt::anyevent; + +=head2 The C Class + +The sole purpose of this class is to deliver an interface to the +C module - any module using it will work inside urxvt without +further work. The only exception is that you cannot wait on condition +variables, but non-blocking condvar use is ok. What this means is that you +cannot use blocking APIs, but the non-blocking variant should work. + +=cut + +our $VERSION = 1; + +$INC{"urxvt/anyevent.pm"} = 1; # mark us as there +push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; + +sub timer { + my ($class, %arg) = @_; + + my $cb = $arg{cb}; + + urxvt::timer + ->new + ->start (urxvt::NOW + $arg{after}) + ->cb (sub { + $_[0]->stop; # need to cancel manually + $cb->(); + }) +} + +sub io { + my ($class, %arg) = @_; + + my $cb = $arg{cb}; + + bless [$arg{fh}, urxvt::iow + ->new + ->fd (fileno $arg{fh}) + ->events (($arg{poll} =~ /r/ ? 1 : 0) + | ($arg{poll} =~ /w/ ? 2 : 0)) + ->start + ->cb (sub { + $cb->(($_[1] & 1 ? 'r' : '') + . ($_[1] & 2 ? 'w' : '')); + })], + urxvt::anyevent:: +} + +sub DESTROY { + $_[0][1]->stop; +} + +sub condvar { + bless \my $flag, urxvt::anyevent::condvar:: +} + +sub urxvt::anyevent::condvar::broadcast { + ${$_[0]}++; +} + +sub urxvt::anyevent::condvar::wait { + unless (${$_[0]}) { + Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API"; + } +} + +package urxvt::term; + =head2 The C Class =over 4 +=cut + +# find on_xxx subs in the package and register them +# as hooks +sub register_package { + my ($self, $pkg, $argv) = @_; + + my $proxy = bless { + _pkg => $pkg, + argv => $argv, + }, $pkg; + Scalar::Util::weaken ($proxy->{term} = $self); + + $self->{_pkg}{$pkg} = $proxy; + + for my $name (@HOOKNAME) { + if (my $ref = $pkg->can ("on_" . lc $name)) { + $proxy->enable ($name => $ref); + } + } +} + =item $term->destroy Destroy the terminal object (close the window, free resources etc.). +=item $isset = $term->option ($optval[, $set]) + +Returns true if the option specified by C<$optval> is enabled, and +optionally change it. All option values are stored by name in the hash +C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash. + +Here is a a likely non-exhaustive list of option names, please see the +source file F to see the actual list: + + borderLess console cursorBlink cursorUnderline hold iconic insecure + intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage + pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating + scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer + secondaryScreen secondaryScroll skipBuiltinGlyphs transparent + tripleclickwords utmpInhibit visualBell + =item $value = $term->resource ($name[, $newval]) Returns the current resource value associated with a given name and @@ -557,8 +792,8 @@ terminal is destroyed, so changing options frequently will eat memory. Here is a a likely non-exhaustive list of resource names, not all of which -are supported in every build, please see the source to see the actual -list: +are supported in every build, please see the source file F +to see the actual list: answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont borderLess color cursorBlink cursorUnderline cutchars delete_key @@ -575,12 +810,17 @@ =cut -sub urxvt::term::resource($$;$) { +sub resource($$;$) { my ($self, $name) = (shift, shift); unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); - goto &urxvt::term::_resource; + &urxvt::term::_resource } +=item $success = $term->parse_keysym ($keysym_spec, $command_string) + +Adds a keymap translation exactly as specified via a resource. See the +C resource in the @@RXVT_NAME@@(1) manpage. + =item $rend = $term->rstyle ([$new_rstyle]) Return and optionally change the current rendition. Text that is output by @@ -609,25 +849,24 @@ Return the current selection text and optionally replace it by C<$newtext>. -#=item $term->overlay ($x, $y, $text) -# -#Create a simple multi-line overlay box. See the next method for details. -# -#=cut -# -#sub urxvt::term::scr_overlay { -# my ($self, $x, $y, $text) = @_; -# -# my @lines = split /\n/, $text; -# -# my $w = 0; -# for (map $self->strwidth ($_), @lines) { -# $w = $_ if $w < $_; -# } -# -# $self->scr_overlay_new ($x, $y, $w, scalar @lines); -# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; -#} +=item $term->overlay_simple ($x, $y, $text) + +Create a simple multi-line overlay box. See the next method for details. + +=cut + +sub overlay_simple { + my ($self, $x, $y, $text) = @_; + + my @lines = split /\n/, $text; + + my $w = List::Util::max map $self->strwidth ($_), @lines; + + my $overlay = $self->overlay ($x, $y, $w, scalar @lines); + $overlay->set (0, $_, $lines[$_]) for 0.. $#lines; + + $overlay +} =item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) @@ -664,6 +903,33 @@ =back +=item $popup = $term->popup ($event) + +Creates a new C object that implements a popup menu. The +C<$event> I be the event causing the menu to pop up (a button event, +currently). + +=cut + +sub popup { + my ($self, $event) = @_; + + $self->grab ($event->{time}, 1) + or return; + + my $popup = bless { + term => $self, + event => $event, + }, urxvt::popup::; + + Scalar::Util::weaken $popup->{term}; + + $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy }; + Scalar::Util::weaken $self->{_destroy}{$popup}; + + $popup +} + =item $cellwidth = $term->strwidth ($string) Returns the number of screen-cells this string would need. Correctly @@ -677,6 +943,10 @@ Convert the given locale-encoded octets into a perl string. +=item $term->scr_bell + +Ring the bell! + =item $term->scr_add_lines ($string) Write the given text string to the screen, as if output by the application @@ -700,6 +970,13 @@ pass characters instead of octets, you should convert your strings first to the locale-specific encoding using C<< $term->locale_encode >>. +=item $old_events = $term->pty_ev_events ([$new_events]) + +Replaces the event mask of the pty watcher by the given event mask. Can +be used to suppress input and output handling to the pty/tty. See the +description of C<< urxvt::timer->events >>. Make sure to always restore +the previous value. + =item $windowid = $term->parent Return the window id of the toplevel window. @@ -734,6 +1011,23 @@ Return various integers describing terminal characteristics. +=item $lc_ctype = $term->locale + +Returns the LC_CTYPE category string used by this rxvt-unicode. + +=item $x_display = $term->display_id + +Return the DISPLAY used by rxvt-unicode. + +=item $modifiermask = $term->ModLevel3Mask + +=item $modifiermask = $term->ModMetaMask + +=item $modifiermask = $term->ModNumLockMask + +Return the modifier masks corresponding to the "ISO Level 3 Shift" (often +AltGr), the meta key (often Alt) and the num lock key, if applicable. + =item $view_start = $term->view_start ([$newvalue]) Returns the negative row number of the topmost line. Minimum value is @@ -836,7 +1130,7 @@ =cut -sub urxvt::term::line { +sub line { my ($self, $row) = @_; my $maxrow = $self->nrow - 1; @@ -910,7 +1204,6 @@ ) } -=item ($row, $col) = $line->coord_of ($offset) =item $text = $term->special_encode $string Converts a perl string into the special encoding used by rxvt-unicode, @@ -922,8 +1215,122 @@ Converts rxvt-unicodes text reprsentation into a perl string. See C<< $term->ROW_t >> for details. +=item $success = $term->grab_button ($button, $modifiermask) + +Registers a synchronous button grab. See the XGrabButton manpage. + +=item $success = $term->grab ($eventtime[, $sync]) + +Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or +synchronous (C<$sync> is true). Also remembers the grab timestampe. + +=item $term->allow_events_async + +Calls XAllowEvents with AsyncBoth for the most recent grab. + +=item $term->allow_events_sync + +Calls XAllowEvents with SyncBoth for the most recent grab. + +=item $term->allow_events_replay + +Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most +recent grab. + +=item $term->ungrab + +Calls XUngrab for the most recent grab. Is called automatically on +evaluation errors, as it is better to lose the grab in the error case as +the session. + =back +=cut + +package urxvt::popup; + +=head2 The C Class + +=over 4 + +=cut + +sub add_item { + my ($self, $item) = @_; + + $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal}; + $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover}; + $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active}; + + $item->{render} ||= sub { $_[0]{text} }; + + push @{ $self->{item} }, $item; +} + +sub add_separator { + my ($self, $sep) = @_; + + $sep ||= "="; + + $self->add_item ({ + rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" }, + text => "", + render => sub { $sep x $self->{term}->ncol }, + activate => sub { }, + }); +} + +sub add_title { + my ($self, $title) = @_; + + $self->add_item ({ + rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" }, + text => $title, + activate => sub { }, + }); +} + +sub add_button { + my ($self, $text, $cb) = @_; + + $self->add_item ({ type => "button", text => $text, activate => $cb}); +} + +sub add_toggle { + my ($self, $text, $cb, $value) = @_; + + my $item; $item = { + type => "button", + text => " $text", + value => $value, + render => sub { ($_[0]{value} ? "* " : " ") . $text }, + activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, + }; + + $self->add_item ($item); +} + +sub show { + my ($self) = @_; + + local $urxvt::popup::self = $self; + + local $ENV{LC_ALL} = $self->{term}->locale; + + urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, + "--transient-for" => $self->{term}->parent, + "-display" => $self->{term}->display_id, + "-pe" => "urxvt-popup") + or die "unable to create popup window\n"; +} + +sub DESTROY { + my ($self) = @_; + + delete $self->{term}{_destroy}{$self}; + $self->{term}->ungrab; +} + =head2 The C Class This class implements timer watchers/events. Time is represented as a @@ -985,7 +1392,7 @@ $term->{iow} = urxvt::iow ->new ->fd (fileno $term->{socket}) - ->events (1) # wait for read data + ->events (urxvt::EVENT_READ) ->start ->cb (sub { my ($iow, $revents) = @_; @@ -1012,8 +1419,9 @@ =item $iow = $iow->events ($eventmask) -Set the event mask to watch. Bit #0 (value C<1>) enables watching for read -data, Bit #1 (value C<2>) enables watching for write data. +Set the event mask to watch. The only allowed values are +C and C, which might be ORed +together, or C. =item $iow = $iow->start @@ -1034,11 +1442,11 @@ =over 4 -=item =0 - only fatal messages +=item == 0 - fatal messages -=item =3 - script loading and management +=item >= 3 - script loading and management -=item =10 - all events received +=item >=10 - all events received =back