=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<ls> 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<ls> supports
+C<--quoting-style=shell>.
-It also offers the following bindable keyboard command:
+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:
+
+ 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
=item searchable-scrollback<hotkey> (enabled by default)
Adds regex search functionality to the scrollback buffer, triggered
-by a hotkey (default: C<M-s>). When in search mode, normal terminal
-input/output is suspended.
+by a hotkey (default: C<M-s>). 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<n> searches further, C<p> or
-C<N> jump to the previous match, C<G> jumps to the bottom and clears the
-history, C<enter> leaves search mode at the current position and C<escape>
-returns to the original position.
+Inputting characters appends them to the regex and continues incremental
+search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
+search upwards/downwards in the scrollback buffer, C<End> jumps to the
+bottom. C<Escape> leaves search mode and returns to the point where search
+was started, while C<Enter> or C<Return> 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<s///>
+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<filename:number>, often seen in compiler messages, into C<vi +$filename
+$word>:
+
+ 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+):?$/\\x1b: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+)\\.$/\x1b: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<on_line_update>) to underline urls.
+Uses per-line display filtering (C<on_line_update>) to underline urls and
+make them clickable. When middle-clicked, the program specified in the
+resource C<urlLauncher> (default C<x-www-browser>) will be started with
+the URL as first argument.
=item block-graphics-to-ascii
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</tmp> directly.).
+
+It listens to the C<selection-pastebin:remote-pastebin> 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<selection-pastebin-url> resource (again, the % is the placeholder
+for the filename):
+
+ URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
+
=back
=head1 API DOCUMENTATION
=item $text
Rxvt-unicodes special way of encoding text, where one "unicode" character
-always represents one screen cell. See L<row_t> for a discussion of this format.
+always represents one screen cell. See L<ROW_t> for a discussion of this format.
=item $string
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<selection> example extension.
C<perl:string> action bound to it (see description of the B<keysym>
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
The current terminal. This variable stores the current C<urxvt::term>
object, whenever a callback/hook is executing.
-=item
-
=back
=head2 Functions in the C<urxvt> Package
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).
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
=cut
BEGIN {
- urxvt->bootstrap;
-
# overwrite perl's warn
*CORE::GLOBAL::warn = sub {
my $msg = join "", @_;
urxvt::warn ($msg);
};
+ # %ENV is the original startup environment
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 {
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";
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} };
$retval
}
+sub exec_async(@) {
+ my $pid = fork;
+
+ return
+ if !defined $pid or $pid;
+
+ %ENV = %{ $TERM->env };
+
+ exec @_;
+ _exit 255;
+}
+
# urxvt::term::extension
package urxvt::term::extension;
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;
}
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};
}
}
=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<hash which defines the environment of the new terminal.
+C<$rxvtname, arg...>. 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<undef> if the new instance didn't
&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<undef> if no
+resource with that pattern exists.
+
+This method should only be called during the C<on_start> 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
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<selection_beg> and
+C<selection_end>. 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<on_sel_grab> hooks.
=item $oldtext = $term->selection ([$newtext])
=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<RS_RVid>). Useful in refresh hooks to provide effects similar
-to the selection.
+(default: C<RS_RVid>), which I<MUST NOT> 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<scr_xor_span>, but xors a rectangle instead. Trailing
whitespace will additionally be xored with the C<$rstyle2>, which defaults
to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
-it instead.
+it instead. Both styles I<MUST NOT> contain font styles.
=item $term->scr_bell
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
=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.
=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
=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)
$self->{term}->ungrab;
}
+=back
+
=head2 The C<urxvt::timer> Class
This class implements timer watchers/events. Time is represented as a
=item >= 3 - script loading and management
-=item >=10 - all events received
+=item >=10 - all called hooks
+
+=item >=11 - hook reutrn values
=back