--- rxvt-unicode/src/urxvt.pm 2012/06/10 13:58:05 1.217 +++ rxvt-unicode/src/urxvt.pm 2012/07/14 08:00:34 1.224 @@ -33,8 +33,9 @@ =head1 PREPACKAGED EXTENSIONS -This section describes the extensions delivered with this release. You can -find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. +A number of extensions are delivered with this release. You can find them +in F<@@RXVT_LIBDIR@@/urxvt/perl/>, and the documentation can be viewed +using F<< man urxvt- >>. You can activate them like this: @@ -44,373 +45,8 @@ URxvt.perl-ext-common: default,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 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 following adds a regex that matches everything -between two vertical bars: - - URxvt.selection.pattern-0: \\|([^|]+)\\| - -Another example: Programs I use often output "absolute path: " at the -beginning of a line when they process multiple files. The following -pattern matches the filename (note, there is a single space at the very -end): - - 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 rot13 - -Rot-13 the selection when activated. Used via keyboard trigger: - - URxvt.keysym.C-M-r: perl:selection:rot13 - -=back - -=item option-popup (enabled by default) - -Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at -runtime. - -Other extensions can extend this popup menu by pushing a code reference -onto C<@{ $term->{option_popup_hook} }>, which gets called whenever the -popup is being displayed. - -Its sole argument is the popup menu, which can be modified. It should -either return nothing or a string, the initial boolean value and a code -reference. The string will be used as button text and the code reference -will be called when the toggle changes, with the new boolean value as -first argument. - -The following will add an entry C that changes -C<< $self->{myoption} >>: - - push @{ $self->{term}{option_popup_hook} }, sub { - ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) - }; - -=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 (such as uri unescaping, perl -evaluation, 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} }>, which gets called whenever the -popup is being displayed. - -Its sole argument is the popup menu, which can be modified. The selection -is in C<$_>, which can be used to decide whether 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 b" => 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). While in search mode, normal terminal -input/output is suspended and a regex is displayed at the bottom of the -screen. - -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 if the C modifier is active. - -The regex defaults to "(?i)", resulting in a case-insensitive search. To -get a case-sensitive search you can delete this prefix using C -or simply use an uppercase character which removes the "(?i)" prefix. - -See L for more info about perl regular expression syntax. - -=item readline (enabled by default) - -A support package that tries to make editing with readline easier. At -the moment, it reacts to clicking shift-left mouse button by trying to -move the text cursor to this position. It does so by generating as many -cursor-left or cursor-right keypresses as required (this only works -for programs that correctly support wide characters). - -To avoid too many false positives, this is only done when: - -=over 4 - -=item - the tty is in ICANON state. - -=item - the text cursor is visible. - -=item - the primary screen is currently being displayed. - -=item - the mouse is on the same (multi-row-) line as the text cursor. - -=back - -The normal selection mechanism isn't disabled, so quick successive clicks -might interfere with selection creation in harmless ways. - -=item selection-autotransform - -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 tabbed - -This transforms the terminal into a tabbar with additional terminals, that -is, it implements what is commonly referred to as "tabbed terminal". The topmost line -displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one -button per tab. - -Clicking a button will activate that tab. Pressing B and -B will switch to the tab left or right of the current one, -while B creates a new tab. - -The tabbar itself can be configured similarly to a normal terminal, but -with a resource class of C. In addition, it supports the -following four resources (shown with defaults): - - URxvt.tabbed.tabbar-fg: - URxvt.tabbed.tabbar-bg: - URxvt.tabbed.tab-fg: - URxvt.tabbed.tab-bg: - -See I in the @@RXVT_NAME@@(1) manpage for valid -indices. - -=item matcher - -Uses per-line display filtering (C) to underline text -matching a certain pattern and make it clickable. When clicked with the -mouse button specified in the C resource (default 2, or -middle), the program specified in the C resource -(default, the C resource, C) will be started -with the matched text as first argument. The default configuration is -suitable for matching URLs and launching a web browser, like the -former "mark-urls" extension. - -The default pattern to match URLs can be overridden with the -C resource, and additional patterns can be specified -with numbered patterns, in a manner similar to the "selection" extension. -The launcher can also be overridden on a per-pattern basis. - -It is possible to activate the most recently seen match or a list of matches -from the keyboard. Simply bind a keysym to "perl:matcher:last" or -"perl:matcher:list" as seen in the example below. - -Example configuration: - - URxvt.perl-ext: default,matcher - URxvt.urlLauncher: sensible-browser - URxvt.keysym.C-Delete: perl:matcher:last - URxvt.keysym.M-Delete: perl:matcher:list - URxvt.matcher.button: 1 - URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-] - URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$) - URxvt.matcher.launcher.2: gvim +$2 $1 - -=item xim-onthespot - -This (experimental) perl extension implements OnTheSpot editing. It does -not work perfectly, and some input methods don't seem to work well with -OnTheSpot editing in general, but it seems to work at least for SCIM and -kinput2. - -You enable it by specifying this extension and a preedit style of -C, i.e.: - - @@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot - -=item kuake - -A very primitive quake-console-like extension. It was inspired by a -description of how the programs C and C work: Whenever the -user presses a global accelerator key (by default C), the terminal -will show or hide itself. Another press of the accelerator key will hide -or show it again. - -Initially, the window will not be shown when using this extension. - -This is useful if you need a single terminal that is not using any desktop -space most of the time but is quickly available at the press of a key. - -The accelerator key is grabbed regardless of any modifiers, so this -extension will actually grab a physical key just for this function. - -If you want a quake-like animation, tell your window manager to do so -(fvwm can do it). - -=item overlay-osc - -This extension implements some OSC commands to display timed popups on the -screen - useful for status displays from within scripts. You have to read -the sources for more info. - -=item block-graphics-to-ascii - -A not very useful example of filtering all text output to the terminal -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 remote-clipboard - -Somewhat of a misnomer, this extension adds two menu entries to the -selection popup that allows one to run external commands to store the -selection somewhere and fetch it again. - -We use it to implement a "distributed selection mechanism", which just -means that one command uploads the file to a remote server, and another -reads it. - -The commands can be set using the C and -C resources. The first should read the -selection to store from STDIN (always in UTF-8), the second should provide -the selection data on STDOUT (also in UTF-8). - -The defaults (which are likely useless to you) use rsh and cat: - - URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' - URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection' - -=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/% - -I xrdb uses the C preprocessor, which might interpret -the double C characters as comment start. Use C<\057\057> instead, -which works regardless of whether xrdb is used to parse the resource file -or not. - -=item macosx-clipboard and macosx-clipboard-native - -These two modules implement an extended clipboard for Mac OS X. They are -used like this: - - URxvt.perl-ext-common: default,macosx-clipboard - URxvt.keysym.M-c: perl:macosx-clipboard:copy - URxvt.keysym.M-v: perl:macosx-clipboard:paste - -The difference between them is that the native variant requires a -perl from apple's devkit or so, and C requires the -C module, works with other perls, has fewer bugs, is -simpler etc. etc. - -=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 confirm-paste - -Displays a confirmation dialog when a paste containing at least a full -line is detected. - -=item bell-command - -Runs the command specified by the C resource when -a bell event occurs. For example, the following pops up a notification -bubble with the text "Beep, Beep" using notify-send: - - URxvt.bell-command: notify-send "Beep, Beep" - -=back +Extensions that add command line parameters or resources on their own are +loaded automatically when used. =head1 API DOCUMENTATION @@ -469,26 +105,8 @@ 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 +Additional methods only supported for extension objects are described in +the C section below. =head2 Hooks @@ -1101,7 +719,7 @@ if $verbosity >= 10; for my $pkg (keys %$cb) { - my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg}, @_) }; + my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) }; $retval ||= $retval_; if ($@) { @@ -1156,6 +774,73 @@ package urxvt::term::extension; +=head2 The C class + +Each extension attached to a terminal object is represented by +a C object. + +You can use these objects, which are passed to all callbacks to store any +state related to the terminal and extension instance. + +The methods (And data members) documented below can be called on extension +objects, in addition to call methods documented for the +class. + +=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. + +=cut + +our $AUTOLOAD; + +sub AUTOLOAD { + $AUTOLOAD =~ /:([^:]+)$/ + or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable"; + + eval qq{ + sub $AUTOLOAD { + my \$proxy = shift; + \$proxy->{term}->$1 (\@_) + } + 1 + } or die "FATAL: unable to compile method forwarder: $@"; + + goto &$AUTOLOAD; +} + +sub DESTROY { + # nop +} + +# urxvt::destroy_hook (basically a cheap Guard:: implementation) + +sub urxvt::destroy_hook::DESTROY { + ${$_[0]}->(); +} + +sub urxvt::destroy_hook(&) { + bless \shift, urxvt::destroy_hook:: +} + +=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. + +To install additional callbacks for the same hook, you can use the C +method of the C class. + +=item $self->disable ($hook_name[, $hook_name..]) + +Dynamically disable the given hooks. + +=cut + sub enable { my ($self, %hook) = @_; my $pkg = $self->{_pkg}; @@ -1186,37 +871,56 @@ } } -our $AUTOLOAD; +=item $guard = $self->on ($hook_name => $cb[, $hook_name => $cb..]) -sub AUTOLOAD { - $AUTOLOAD =~ /:([^:]+)$/ - or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable"; +Similar to the C enable, but installs additional callbacks for +the given hook(s) (that is, it doesn't replace existing callbacks), and +returns a guard object. When the guard object is destroyed the callbacks +are disabled again. - eval qq{ - sub $AUTOLOAD { - my \$proxy = shift; - \$proxy->{term}->$1 (\@_) - } - 1 - } or die "FATAL: unable to compile method forwarder: $@"; +=cut - goto &$AUTOLOAD; -} +sub urxvt::extension::on_disable::DESTROY { + my $disable = shift; -sub DESTROY { - # nop + my $term = delete $disable->{""}; + + while (my ($htype, $id) = each %$disable) { + delete $term->{_hook}[$htype]{$id}; + $term->set_should_invoke ($htype, -1); + } } -# urxvt::destroy_hook +sub on { + my ($self, %hook) = @_; -sub urxvt::destroy_hook::DESTROY { - ${$_[0]}->(); -} + my $term = $self->{term}; -sub urxvt::destroy_hook(&) { - bless \shift, urxvt::destroy_hook:: + my %disable = ( "" => $term ); + + while (my ($name, $cb) = each %hook) { + my $htype = $HOOKTYPE{uc $name}; + defined $htype + or Carp::croak "unsupported hook type '$name'"; + + $term->set_should_invoke ($htype, +1); + $term->{_hook}[$htype]{ $disable{$htype} = $cb+0 } + = sub { shift; $cb->($self, @_) }; # very ugly indeed + } + + bless \%disable, "urxvt::extension::on_disable" } +=item $self->x_resource ($pattern) + +=item $self->x_resource_boolean ($pattern) + +These methods support an additional C<%> prefix when called on an +extension object - see the description of these methods in the +C class for details. + +=cut + sub x_resource { my ($self, $name) = @_; $name =~ s/^%(\.|$)/$_[0]{_name}$1/; @@ -1229,6 +933,10 @@ $self->{term}->x_resource_boolean ($name) } +=back + +=cut + package urxvt::anyevent; =head2 The C Class @@ -1487,7 +1195,7 @@ are supported in every build, please see the source file F to see the actual list: - answerbackstring backgroundPixmap backspace_key blendtype blurradius + answerbackstring backgroundPixmap backspace_key blurradius boldFont boldItalicFont borderLess buffered chdir color cursorBlink cursorUnderline cutchars delete_key depth display_name embed ext_bwidth fade font geometry hold iconName iconfile imFont imLocale inputMethod @@ -1522,7 +1230,7 @@ If the method is called on an extension object (basically, from an extension), then the special prefix C<%.> will be replaced by the name of -the extension and a dot, and the lone string C<%> will be replcaed by the +the extension and a dot, and the lone string C<%> will be replaced by the extension name itself. This makes it possible to code extensions so you can rename them and get a new set of commandline switches and resources without having to change the actual code.