--- rxvt-unicode/src/urxvt.pm 2006/01/11 00:59:58 1.77 +++ rxvt-unicode/src/urxvt.pm 2006/01/19 19:52:54 1.111 @@ -37,16 +37,42 @@ @@RXVT_NAME@@ -pe +Or by adding them to the resource for extensions loaded by default: + + URxvt.perl-ext-common: default,automove-background,selection-autotransform + =over 4 =item selection (enabled by default) (More) intelligent selection. This extension tries to be more intelligent -when the user extends selections (double-click). Right now, it tries to -select urls and complete shell-quoted arguments, which is very convenient, -too, if your F supports C<--quoting-style=shell>. +when the user extends selections (double-click and further clicks). Right +now, it tries to select words, urls and complete shell-quoted +arguments, which is very convenient, too, if your F supports +C<--quoting-style=shell>. + +A double-click usually selects the word under the cursor, further clicks +will enlarge the selection. + +The selection works by trying to match a number of regexes and displaying +them in increasing order of length. You can add your own regexes by +specifying resources of the form: + + URxvt.selection.pattern-0: perl-regex + URxvt.selection.pattern-1: perl-regex + ... + +The index number (0, 1...) must not have any holes, and each regex must +contain at least one pair of capturing parentheses, which will be used for +the match. For example, the followign adds a regex that matches everything +between two vertical bars: -It also offers the following bindable keyboard command: + URxvt.selection.pattern-0: \\|([^|]+)\\| + +You can look at the source of the selection extension to see more +interesting uses, such as parsing a line from beginning to end. + +This extension also offers following bindable keyboard commands: =over 4 @@ -69,24 +95,89 @@ text into various other formats/action (such as uri unescaping, perl evalution, web-browser starting etc.), depending on content. +Other extensions can extend this popup menu by pushing a code reference +onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the +popup is displayed. + +It's sole argument is the popup menu, which can be modified. The selection +is in C<$_>, which can be used to decide wether to add something or not. +It should either return nothing or a string and a code reference. The +string will be used as button text and the code reference will be called +when the button gets activated and should transform C<$_>. + +The following will add an entry C that transforms all Cs in +the selection to Cs, but only if the selection currently contains any +Cs: + + push @{ $self->{term}{selection_popup_hook} }, sub { + /a/ ? ("a to be" => sub { s/a/b/g } + : () + }; + =item searchable-scrollback (enabled by default) Adds regex search functionality to the scrollback buffer, triggered -by a hotkey (default: C). When in search mode, normal terminal -input/output is suspended. +by a hotkey (default: C). While in search mode, normal terminal +input/output is suspended and a regex is displayed at the bottom of the +screen. -C starts an incremental regex search, C searches further, C

or -C jump to the previous match, C jumps to the bottom and clears the -history, C leaves search mode at the current position and C -returns to the original position. +Inputting characters appends them to the regex and continues incremental +search. C removes a character from the regex, C and C +search upwards/downwards in the scrollback buffer, C jumps to the +bottom. C leaves search mode and returns to the point where search +was started, while C or C stay at the current position and +additionally stores the first match in the current line into the primary +selection. -=item digital-clock +=item selection-autotransform -Displays a digital clock using the built-in overlay. +This selection allows you to do automatic transforms on a selection +whenever a selection is made. + +It works by specifying perl snippets (most useful is a single C +operator) that modify C<$_> as resources: + + URxvt.selection-autotransform.0: transform + URxvt.selection-autotransform.1: transform + ... + +For example, the following will transform selections of the form +C, often seen in compiler messages, into C: + + URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ + +And this example matches the same,but replaces it with vi-commands you can +paste directly into your (vi :) editor: + + URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/ + +Of course, this can be modified to suit your needs and your editor :) + +To expand the example above to typical perl error messages ("XXX at +FILENAME line YYY."), you need a slightly more elaborate solution: + + URxvt.selection.pattern-0: ( at .*? line \\d+[,.]) + URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/ + +The first line tells the selection code to treat the unchanging part of +every error message as a selection pattern, and the second line transforms +the message into vi commands to load the file. =item mark-urls -Uses per-line display filtering (C) to underline urls. +Uses per-line display filtering (C) to underline urls and +make them clickable. When middle-clicked, the program specified in the +resource C (default C) will be started with +the URL as first argument. + +=item automove-background + +This is basically a one-line extension that dynamically changes the background pixmap offset +to the window position, in effect creating the same effect as pseudo transparency with +a custom pixmap. No scaling is supported in this mode. Exmaple: + + @@RXVT_NAME@@ -pixmap background.xpm -pe automove-background =item block-graphics-to-ascii @@ -94,12 +185,45 @@ by replacing all line-drawing characters (U+2500 .. U+259F) by a similar-looking ascii character. +=item digital-clock + +Displays a digital clock using the built-in overlay. + =item example-refresh-hooks Displays a very simple digital clock in the upper right corner of the window. Illustrates overwriting the refresh callbacks to create your own overlays or changes. +=item selection-pastebin + +This is a little rarely useful extension that Uploads the selection as +textfile to a remote site (or does other things). (The implementation is +not currently secure for use in a multiuser environment as it writes to +F directly.). + +It listens to the C keyboard command, +i.e. + + URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin + +Pressing this combination runs a command with C<%> replaced by the name of +the textfile. This command can be set via a resource: + + URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/. + +And the default is likely not useful to anybody but the few people around +here :) + +The name of the textfile is the hex encoded md5 sum of the selection, so +the same content should lead to the same filename. + +After a successful upload the selection will be replaced by the text given +in the C resource (again, the % is the placeholder +for the filename): + + URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% + =back =head1 API DOCUMENTATION @@ -125,7 +249,7 @@ =item $text Rxvt-unicodes special way of encoding text, where one "unicode" character -always represents one screen cell. See L for a discussion of this format. +always represents one screen cell. See L for a discussion of this format. =item $string @@ -208,6 +332,15 @@ Called at the very end of initialisation of a new terminal, just before returning to the mainloop. +=item on_child_start $term, $pid + +Called just after the child process has been Ced. + +=item on_child_exit $term, $status + +Called just after the child process has exited. C<$status> is the status +from C. + =item on_sel_make $term, $eventtime Called whenever a selection has been made by the user, but before the @@ -230,7 +363,9 @@ Called whenever the user tries to extend the selection (e.g. with a double click) and is either supposed to return false (normal operation), or should extend the selection itelf and return true to suppress the built-in -processing. +processing. This can happen multiple times, as long as the callback +returns true, it will be called on every further click by the user and is +supposed to enlarge the selection more and more, if possible. See the F example extension. @@ -307,6 +442,12 @@ C action bound to it (see description of the B resource in the @@RXVT_NAME@@(1) manpage). +=item on_x_event $term, $event + +Called on every X event received on the vt window (and possibly other +windows). Should only be used as a last resort. Most event structure +members are not passed. + =item on_focus_in $term Called whenever the window gets the keyboard focus, before rxvt-unicode @@ -317,6 +458,8 @@ Called wheneever the window loses keyboard focus, before rxvt-unicode does focus out processing. +=item on_configure_notify $term, $event + =item on_key_press $term, $event, $keysym, $octets =item on_key_release $term, $event, $keysym @@ -388,8 +531,6 @@ The current terminal. This variable stores the current C object, whenever a callback/hook is executing. -=item - =back =head2 Functions in the C Package @@ -413,12 +554,6 @@ Messages have a size limit of 1023 bytes currently. -=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). @@ -429,6 +564,22 @@ Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, AnyModifier +=item urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, +ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, +PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, +Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, +KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask, +ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask, +FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask + +=item urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, +EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose, +GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify, +UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify, +ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, +CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, +SelectionNotify, ColormapNotify, ClientMessage, MappingNotify + Various constants for use in X calls and event processing. =back @@ -488,8 +639,6 @@ =cut BEGIN { - urxvt->bootstrap; - # overwrite perl's warn *CORE::GLOBAL::warn = sub { my $msg = join "", @_; @@ -497,14 +646,8 @@ 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; my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; sub verbose { @@ -512,24 +655,29 @@ warn "$msg\n" if $level <= $verbosity; } -my $extension_pkg = "extension0000"; my %extension_pkg; # load a single script into its own package, once only sub extension_package($) { my ($path) = @_; + no strict 'refs'; + $extension_pkg{$path} ||= do { - my $pkg = "urxvt::" . ($extension_pkg++); + $path =~ /([^\/\\]+)$/; + my $pkg = $1; + $pkg =~ s/[^[:word:]]/_/g; + $pkg = "urxvt::ext::$pkg"; verbose 3, "loading extension '$path' into package '$pkg'"; open my $fh, "<:raw", $path or die "$path: $!"; - my $source = untaint + @{"$pkg\::ISA"} = urxvt::term::extension::; + + my $source = "package $pkg; use strict; use utf8;\n" - . "use base urxvt::term::extension::;\n" . "#line 1 \"$path\"\n{\n" . (do { local $/; <$fh> }) . "\n};\n1"; @@ -596,16 +744,12 @@ warn $@; } } + + verbose 11, "$HOOKNAME[$htype] returning <$retval>" + if $verbosity >= 11; } if ($htype == 1) { # DESTROY - if (my $hook = delete $TERM->{_hook}) { - for my $htype (0..$#$hook) { - $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } - or set_should_invoke $htype, 0; - } - } - # clear package objects %$_ = () for values %{ $TERM->{_pkg} }; @@ -629,10 +773,8 @@ 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->set_should_invoke ($htype, +1) + unless exists $self->{term}{_hook}[$htype]{$pkg}; $self->{term}{_hook}[$htype]{$pkg} = $cb; } @@ -647,10 +789,8 @@ 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; - } + $self->set_should_invoke ($htype, -1) + if delete $self->{term}{_hook}[$htype]{$pkg}; } } @@ -784,8 +924,8 @@ =item $term = new urxvt::term $envhashref, $rxvtname, [arg...] Creates a new terminal, very similar as if you had started it with system -C<$rxvtname, arg...>. C<$envhashref> must be a reference to a %ENV>-like -C. C<$envhashref> must be a reference to a C<%ENV>-like +hash which defines the environment of the new terminal. Croaks (and probably outputs an error message) if the new instance couldn't be created. Returns C if the new instance didn't @@ -806,6 +946,31 @@ etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event watchers (timers, io watchers) are still active. +=item $term->exec_async ($cmd[, @args]) + +Works like the combination of the C/C builtins, which executes +("starts") programs in the background. This function takes care of setting +the user environment before exec'ing the command (e.g. C) and should +be preferred over explicit calls to C or C. + +Returns the pid of the subprocess or C on error. + +=cut + +sub exec_async { + my $self = shift; + + my $pid = fork; + + return $pid + if !defined $pid or $pid; + + %ENV = %{ $self->env }; + + exec @_; + urxvt::_exit 255; +} + =item $isset = $term->option ($optval[, $set]) Returns true if the option specified by C<$optval> is enabled, and @@ -817,10 +982,10 @@ 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 + override-redirect pastableTabs pointerBlank reverseVideo scrollBar + scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput + scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs + transparent tripleclickwords utmpInhibit visualBell =item $value = $term->resource ($name[, $newval]) @@ -847,14 +1012,15 @@ borderLess color cursorBlink cursorUnderline cutchars delete_key display_name embed ext_bwidth fade font geometry hold iconName imFont imLocale inputMethod insecure int_bwidth intensityStyles - italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier - mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2 - perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd - reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating - scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput - scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle - shade term_name title transparent transparent_all tripleclickwords - utmpInhibit visualBell + italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier + mouseWheelScrollPage name override_redirect pastableTabs path perl_eval + perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay + preeditType print_pipe pty_fd reverseVideo saveLines scrollBar + scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness + scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle + secondaryScreen secondaryScroll selectstyle shade term_name title + transient_for transparent transparent_all tripleclickwords utmpInhibit + visualBell =cut @@ -864,6 +1030,17 @@ &urxvt::term::_resource } +=item $value = $term->x_resource ($pattern) + +Returns the X-Resource for the given pattern, excluding the program or +class name, i.e. C<< $term->x_resource ("boldFont") >> should return the +same value as used by this instance of rxvt-unicode. Returns C if no +resource with that pattern exists. + +This method should only be called during the C hook, as there is +only one resource database per display, and later invocations might return +the wrong resources. + =item $success = $term->parse_keysym ($keysym_spec, $command_string) Adds a keymap translation exactly as specified via a resource. See the @@ -888,10 +1065,18 @@ Return the current values of the selection mark, begin or end positions, and optionally set them to new values. +=item $term->selection_make ($eventtime[, $rectangular]) + +Tries to make a selection as set by C and +C. If C<$rectangular> is true (default: false), a +rectangular selection will be made. This is the prefered function to make +a selection. + =item $success = $term->selection_grab ($eventtime) -Try to request the primary selection from the server (for example, as set -by the next method). +Try to request the primary selection text from the server (for example, as +set by the next method). No visual feedback will be given. This function +is mostly useful from within C hooks. =item $oldtext = $term->selection ([$newtext]) @@ -994,15 +1179,15 @@ =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) XORs the rendition values in the given span with the provided value -(default: C). Useful in refresh hooks to provide effects similar -to the selection. +(default: C), which I contain font styles. Useful in +refresh hooks to provide effects similar to the selection. =item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]]) Similar to C, but xors a rectangle instead. Trailing whitespace will additionally be xored with the C<$rstyle2>, which defaults to C, which removes reverse video again and underlines -it instead. +it instead. Both styles I contain font styles. =item $term->scr_bell @@ -1046,6 +1231,13 @@ Return the window id of the terminal window. +=item $term->vt_emask_add ($x_event_mask) + +Adds the specified events to the vt event mask. Useful e.g. when you want +to receive pointer events all the times: + + $term->vt_emask_add (urxvt::PointerMotionMask); + =item $window_width = $term->width =item $window_height = $term->height @@ -1068,7 +1260,7 @@ =item $nrow_plus_saveLines = $term->total_rows -=item $lines_in_scrollback = $term->nsaved +=item $topmost_scrollback_row = $term->top_row Return various integers describing terminal characteristics. @@ -1106,8 +1298,8 @@ =item $view_start = $term->view_start ([$newvalue]) -Returns the negative row number of the topmost line. Minimum value is -C<0>, which displays the normal terminal contents. Larger values scroll +Returns the row number of the topmost displayed line. Maximum value is +C<0>, which displays the normal terminal contents. Lower values scroll this many lines into the scrollback buffer. =item $term->want_refresh @@ -1196,7 +1388,8 @@ =item $offset = $line->offset_of ($row, $col) Returns the character offset of the given row|col pair within the logical -line. +line. Works for rows outside the line, too, and returns corresponding +offsets outside the string. =item ($row, $col) = $line->coord_of ($offset) @@ -1429,8 +1622,10 @@ delete $env->{LC_ALL}; $env->{LC_CTYPE} = $self->{term}->locale; - urxvt::term->new ($env, $self->{term}->resource ("name"), - "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, + urxvt::term->new ($env, "popup", + "--perl-lib" => "", "--perl-ext-common" => "", + "-pty-fd" => -1, "-sl" => 0, + "-b" => 1, "-bd" => "grey80", "-bl", "-override-redirect", "--transient-for" => $self->{term}->parent, "-display" => $self->{term}->display_id, "-pe" => "urxvt-popup") @@ -1444,6 +1639,8 @@ $self->{term}->ungrab; } +=back + =head2 The C Class This class implements timer watchers/events. Time is represented as a @@ -1491,6 +1688,10 @@ Set the event trigger time to C<$tstamp> and start the timer. +=item $timer = $timer->after ($delay) + +Like C, but sets the expiry timer to c. + =item $timer = $timer->stop Stop the timer. @@ -1559,7 +1760,9 @@ =item >= 3 - script loading and management -=item >=10 - all events received +=item >=10 - all called hooks + +=item >=11 - hook reutrn values =back