--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/08 06:35:38 1.16 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/02/21 01:00:40 1.43 @@ -15,10 +15,12 @@
urxvt
Packageurxvt
Packageurxvt::popup
Classurxvt::timer
Classurxvt::iow
Classurxvt::iw
Classurxvt::pw
Class-
This section describes the extensiosn delivered with this version. You can +
This section describes the extensions delivered with this release. You can find them in /opt/rxvt/lib/urxvt/perl/.
You can activate them like this:
rxvt -pe <extensionname>+
Or by adding them to the resource for extensions loaded by default:
++ URxvt.perl-ext-common: default,automove-background,selection-autotransform
--quoting-style=shell
.
+(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 ls supports
+--quoting-style=shell
.
+A double-click usually selects the word under the cursor, further clicks +will enlarge the selection.
It also offers the following bindable event:
+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: \\|([^|]+)\\|+
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:
Other extensions can extend this popup menu by pushing a code reference
+onto @{ $term-
{option_popup_hook} }>, which gets called whenever the
+popup is being displayed.
It's 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 myoption
that changes
+$self-
{myoption}>:
+ push @{ $self->{term}{option_popup_hook} }, sub { + ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) + };+
Other extensions can extend this popup menu by pushing a code reference
+onto @{ $term-
{selection_popup_hook} }>, which gets called whenever the
+popup is being displayed.
It's sole argument is the popup menu, which can be modified. The selection
+is in $_
, 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 $_
.
The following will add an entry a to b
that transforms all a
s in
+the selection to b
s, but only if the selection currently contains any
+a
s:
+ push @{ $self->{term}{selection_popup_hook} }, sub { + /a/ ? ("a to be" => sub { s/a/b/g } + : () + };+
M-s
). 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. BackSpace
removes a character from the regex, Up
and Down
+search upwards/downwards in the scrollback buffer, End
jumps to the
+bottom. Escape
leaves search mode and returns to the point where search
+was started, while Enter
or Return
stay at the current position and
+additionally stores the first match in the current line into the primary
+selection.
To avoid too many false positives, this is only done when:
+The normal selection mechanism isn't disabled, so quick successive clicks +might interfere with selection creation in harmless ways.
+It works by specifying perl snippets (most useful is a single s///
+operator) that modify $_
as resources:
+ URxvt.selection-autotransform.0: transform + URxvt.selection-autotransform.1: transform + ...+
For example, the following will transform selections of the form
+filename:number
, often seen in compiler messages, into 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+):?$/: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.
+Clicking a button will activate that tab. Pressing Shift-Left and +Shift-Right will switch to the tab left or right of the current one, +while Shift-Down creates a new tab.
+The tabbar itself can be configured similarly to a normal terminal, but
+with a resource class of URxvt.tabbed
. In addition, it supports the
+following four resources (shown with defaults):
+ URxvt.tabbed.tabbar-fg: <colour-index, default 3> + URxvt.tabbed.tabbar-bg: <colour-index, default 0> + URxvt.tabbed.tab-fg: <colour-index, default 0> + URxvt.tabbed.tab-bg: <colour-index, default 1>+
See COLOR AND GRAPHICS in the rxvt(1)
manpage for valid
+indices.
on_line_update
) to underline urls.
+Uses per-line display filtering (on_line_update
) to underline urls and
+make them clickable. When middle-clicked, the program specified in the
+resource urlLauncher
(default x-www-browser
) will be started with
+the URL as first argument.
+You enable it by specifying this extension and a preedit style of
+OnTheSpot
, i.e.:
+ rxvt -pt OnTheSpot -pe xim-onthespot+
+ rxvt -pixmap background.xpm -pe automove-background
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 URxvt.remote-selection.store
and
+URxvt.remote-selection.fetch
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'+
It listens to the 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 %
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 selection-pastebin-url
resource (again, the % is the placeholder
+for the filename):
+ URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%+
+
+
All objects (such as terminals, time watchers etc.) are typical reference-to-hash objects. The hash can be used to store anything you @@ -156,7 +486,7 @@
+
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 $self
object without having to think
+about other extensions, with the exception of methods and members that
+begin with an underscore character _
: these are reserved for internal
+use.
Although it isn't a urxvt::term
object, you can call all methods of the
+urxvt::term
class on this object.
It has the following methods and data members:
+urxvt::term
object associated with this instance of the
+extension. This member must not be changed in any way.
+on_
prefix) for
+this extension, replacing any previous hook. This is useful when you want
+to overwrite time-critical hooks only temporarily.
++
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 urxvt::term
methods on it, but
-its not a real urxvt::term
object. Instead, the real urxvt::term
-object that is shared between all packages is stored in the term
-member. It is, however, blessed intot he package of the extension script,
-so for all practical purposes you can treat an extension script as a class.
All of them must return a boolean value. If it is true, then the event -counts as being consumed, 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 ()
).
The first argument passed to them is an extension oject as described in
+the in the Extension Objects
section.
All of these hooks must return a boolean value. If any of the called +hooks returns true, then the event counts as being consumed, and the +relevant action might not be carried out by the C++ code.
+When in doubt, return a false value (preferably ()
). >
on_start
hook is a better
+place.
+
+
+fork
ed.
+$status
is the status
+from waitpid
.
See the selection example extension.
@@ -271,12 +654,6 @@ number of lines that will be in the scrollback buffer.program(s)
running in the urxvt window send output.
-on_refresh_begin
.
perl:string
action bound to it (see description of the keysym
+Called whenever the a user-configured event is being activated (e.g. via
+a perl:string
action bound to a key, see description of the keysym
resource in the rxvt(1)
manpage).
The event is simply the action string. This interface is assumed to change +slightly in the future.
+The event is a hash with most values as named by Xlib (see the XEvent
-manpage), with the additional members row
and col
, which are the row
-and column under the mouse cursor.
row
and col
, which are the
+(real, not screen-based) row and column under the mouse cursor.
on_key_press
additionally receives the string rxvt-unicode would
@@ -388,32 +796,73 @@
subwindow.
urxvt
Packageurxvt
.
+urxvt::term
object, whenever a callback/hook is executing.
urxvt::term
object (during the on_init
phase). The array
+gets cleared before the codereferences that were in it are being executed,
+so coderefs can push themselves onto it again if they so desire.
+This complements to the perl-eval commandline option, but gets executed +first.
+@TERM_INIT
, but contains perl package/class names, which
+get registered as normal extensions after calling the hooks in @TERM_INIT
+but before other extensions. Gets cleared just like @TERM_INIT
.
+
urxvt
Packagesystem $binfile, arg...
. Croaks (and probably outputs an error message)
-if the new instance couldn't be created. Returns undef
if the new
-instance didn't initialise perl, and the terminal object otherwise. The
-init
and start
hooks will be called during the call.
-Using this function has the advantage that its output ends up in the correct place, e.g. on stderr of the connecting urxvtc client.
Messages have a size limit of 1023 bytes currently.
+urxvt::anyevent
ClassThe sole purpose of this class is to deliver an interface to the
AnyEvent
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.
urxvt::term
Class$rxvtname, arg...
. $envhashref
must be a reference to a %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 undef
if the new instance didn't
+initialise perl, and the terminal object otherwise. The init
and
+start
hooks will be called before this call returns, and are free to
+refer to global data (which is race free).
fork
/exec
builtins, which executes
+(``starts'') programs in the background. This function takes care of setting
+the user environment before exec'ing the command (e.g. PATH
) and should
+be preferred over explicit calls to exec
or system
.
+Returns the pid of the subprocess or undef
on error.
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
$term->x_resource ("boldFont")
should return the
+same value as used by this instance of rxvt-unicode. Returns undef
if no
+resource with that pattern exists.
+This method should only be called during the on_start
hook, as there is
+only one resource database per display, and later invocations might return
+the wrong resources.
keysym
resource in the rxvt(1)
manpage.
selection_beg
and
+selection_end
. If $rectangular
is true (default: false), a
+rectangular selection will be made. This is the prefered function to make
+a selection.
+on_sel_grab
hooks.
$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; -#}
+Create a simple multi-line overlay box. See the next method for details.RS_RVid
), which MUST NOT contain font styles. Useful in
+refresh hooks to provide effects similar to the selection.
+scr_xor_span
, but xors a rectangle instead. Trailing
+whitespace will additionally be xored with the $rstyle2
, which defaults
+to RS_RVid | RS_Uline
, which removes reverse video again and underlines
+it instead. Both styles MUST NOT contain font styles.
+on_add_lines
hook, though.
$term->locale_encode
.
urxvt::timer->events
. Make sure to always restore
+the previous value.
+-1
if no pty
+is used.
++ $term->vt_emask_add (urxvt::PointerMotionMask);+
\%ENV
.
+VAR=VALUE
.
+0
, which displays the normal terminal contents. Larger values scroll
+Returns the row number of the topmost displayed line. Maximum value is
+0
, which displays the normal terminal contents. Lower values scroll
this many lines into the scrollback buffer.
$row_number
. Row 0
is the topmost terminal line, row $term->$ncol-1
is the bottommost
terminal line. The scrollback buffer starts at line -1
and extends to
-line -$term->nsaved
. Nothing will be returned if a nonexistent line
+line -$term->nsaved
. Nothing will be returned if a nonexistent line
is requested.
$text
is in a special encoding: tabs and wide characters that use more
-than one cell when displayed are padded with urxvt::NOCHAR characters
-(chr 65535
). Characters with combining characters and other characters
-that do not fit into the normal tetx encoding will be replaced with
-characters in the private use area.
$urxvt::NOCHAR
(chr 65535)
+characters. Characters with combining characters and other characters that
+do not fit into the normal tetx encoding will be replaced with characters
+in the private use area.
You have to obey this encoding when changing text. The advantage is @@ -850,7 +1488,7 @@ characters.
The methods $term->special_encode
and $term->special_decode
+
The methods $term->special_encode
and $term->special_decode
can be used to convert normal strings into this encoding and vice versa.
$term->ROW_t
for details.
$sync
is true). Also remembers the grab timestampe.
+$term
object only serves as
+the source of the display, otherwise those functions map more-or-less
+directory onto the X functions of the same name.
+
urxvt::popup
Class$sepchr
.
+$cb
is called whenever it is
+selected.
+
urxvt::timer
Class$tstamp
and start the timer.
+start
, but sets the expiry timer to c<urxvt::NOW + $delay>.
+1
) enables watching for read
-data, Bit #1 (value 2
) enables watching for write data.
+Set the event mask to watch. The only allowed values are
+urxvt::EVENT_READ
and urxvt::EVENT_WRITE
, which might be ORed
+together, or urxvt::EVENT_NONE
.
+
urxvt::iw
ClassThis class implements idle watchers, that get called automatically when +the process is idle. They should return as fast as possible, after doing +some useful work.
++
+urxvt::pw
ClassThis class implements process watchers. They create an event whenever a +process exits, after which they stop automatically.
++ my $pid = fork; + ... + $term->{pw} = urxvt::pw + ->new + ->start ($pid) + ->cb (sub { + my ($pw, $exit_status) = @_; + ... + });+
$pid
.
++
@@ -1083,11 +1908,13 @@
This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output.