--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/02 17:21:59 1.2 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/19 19:26:31 1.33 @@ -15,11 +15,19 @@
urxvt
Packageurxvt
Packageurxvt::anyevent
Classurxvt::term
Classurxvt::popup
Classurxvt::timer
Classurxvt::iow
Class+
rxvtperl - rxvt-unicode's embedded perl interpreter
* Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be loaded automatically.
-* Each script will only be loaded once, even in urxvtd, and will be valid -globally.
-* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and -thus must be encoded as UTF-8.
++ # create a file grab_test in $HOME:
sub on_sel_grab { warn "you selected ", $_[0]->selection; () }
- 1+ # start a rxvt using it: +
+ rxvt --perl-lib $HOME -pe grab_test
Everytime a terminal object gets created, extension scripts specified via
+the perl
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.
+Each script will only ever be loaded once, even in rxvtd, where +scripts will be shared (but not enabled) for all terminals.
++
+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>+
--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:
++ 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:
++ URxvt.keysym.C-M-r: perl:selection:rot13+
Other extensions can extend this popup menu by pushing a code reference
+onto @{ $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 $_
, 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.
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.
+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.
++ rxvt -pixmap background.xpm -pe automove-background+
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
+like. All members starting with an underscore (such as _ptr
or
+_hook
) are reserved for internal uses and MUST NOT be accessed or
+modified).
When objects are destroyed on the C++ side, the perl object hashes are +emptied, so its best to store related objects such as time watchers and +the like inside the terminal object so they get destroyed as soon as the +terminal is destroyed.
+Argument names also often indicate the type of a parameter. Here are some +hints on what they mean:
++
+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 loaded scripts, and will be called -whenever the relevant event happens.
-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 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 extension oject as described in
+the in the Extension Objects
section.
All of these hooks 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 ()
). >
fork
ed.
+$status
is the status
+from waitpid
.
+Returning a true value aborts selection grabbing. It will still be hilighted.
See the selection example extension.
program(s)
running in the urxvt window send output.
+Called whenever the ESC ] 777 ; string ST command sequence (OSC =
+operating system command) is processed. Cursor position and other state
+information is up-to-date when this happens. For interoperability, the
+string should start with the extension name and a colon, to distinguish
+it from commands for other extensions, and this might be enforced in the
+future.
+Be careful not ever to trust (in a security sense) the data you receive, +as its source can not easily be controleld (e-mail content, messages from +other users on the same system etc.).
+$term->scr_add_lines
yourself. Please note that this
+might be very slow, however, as your hook is called for all text being
+output.
+The row number is always the topmost row of the line if the line spans +multiple rows.
+Please note that, if you change the line, then the hook might get called +later with the already-modified line (e.g. if unrelated parts change), so +you cannot just toggle rendition bits, but only set them.
on_refresh_begin
.
perl:string
action bound to it (see description of the keysym
+resource in the rxvt(1)
manpage).
+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.
on_key_press
additionally receives the string rxvt-unicode would
+output, if any, in locale-specific encoding.
subwindow.
++
+urxvt
Packageurxvt
.
+urxvt::term
+object, whenever a callback/hook is executing.
+@@ -185,7 +685,7 @@
rxvt_warn
witht eh given string which should not include a
+Calls rxvt_warn
with the given string which should not include a
newline. The module also overwrites the warn
builtin with a function
that calls this function.
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.
+
Rendition bitsets contain information about colour, font, font styles and +similar information for each screen cell.
+The following ``macros'' deal with changes in rendition sets. You should +never just create a bitset, you should always modify an existing one, +as they contain important information required for correct operation of +rxvt-unicode.
++
+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 programming. 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 during this call.
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.
$optval
is enabled, and
+optionally change it. All option values are stored by name in the hash
+%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 /src/optinc.h to see the actual list:
++ borderLess console cursorBlink cursorUnderline hold iconic insecure + intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage + override-redirect pastableTabs pointerBlank reverseVideo scrollBar + scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput + scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs + transparent tripleclickwords utmpInhibit visualBell+
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 /src/rsinc.h +to see the actual list:@@ -243,16 +891,52 @@ 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 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 + 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
$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
.
$x
or
-$y
is negative, then this is counted from the right/bottom side,
-respectively.
+width/height. $rstyle
defines the initial rendition style
+(default: OVERLAY_RSTYLE
).
+If $border
is 2
(default), then a decorative border will be put
+around the box.
If either $x
or $y
is negative, then this is counted from the
+right/bottom side, respectively.
This method returns an urxvt::overlay object. The overlay will be visible +as long as the perl object is referenced.
+The methods currently supported on urxvt::overlay
objects are:
$term->ROW_t
and $term->ROW_r
in that it puts
+text in rxvt-unicode's special encoding and an array of rendition values
+at a specific position inside the overlay.
+urxvt::popup
object that implements a popup menu. The
+$event
must be the event causing the menu to pop up (a button event,
+currently).
+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.
+Normally its not a good idea to use this function, as programs might be
+confused by changes in cursor position or scrolling. Its useful inside a
+on_add_lines
hook, though.
scr_add_lines
, but the argument must be in the
+locale-specific encoding of the terminal and can contain command sequences
+(escape codes) that will be interpreted.
+$data
to the tty (i.e. as program input). To
+pass characters instead of octets, you should convert your strings first
+to the locale-specific encoding using $term->locale_encode
.
+urxvt::timer->events
. Make sure to always restore
+the previous value.
++ $term->vt_emask_add (urxvt::PointerMotionMask);+
\%ENV
.
+0
, which displays the normal terminal contents. Lower values scroll
+this many lines into the scrollback buffer.
+Used after changing terminal contents to display them.
+$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
+is requested.
+If $new_text
is specified, it will replace characters in the current
+line, starting at column $start_col
(default 0
), which is useful
+to replace only parts of a line. The font index in the rendition will
+automatically be updated.
$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.
You have to obey this encoding when changing text. The advantage is
+that substr
and similar functions work on screen cells and not on
+characters.
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
, but returns an arrayref with rendition
+bitsets. Rendition bitsets contain information about colour, font, font
+styles and similar information. See also $term->ROW_t
.
+When setting rendition, the font mask will be ignored.
+See the section on RENDITION, above.
+$term->ncol
if the
+line is joined with the following one.
+urxvt::line
object that stores information
+about the logical line that row $row_number
is part of. It supports the
+following methods:
+ROW_t
+ROW_r
+ROW_l
.
+$term->ROW_t
for details.
+$term->ROW_t
for details.
+$sync
is true). Also remembers the grab timestampe.
++
+urxvt::popup
Class$sepchr
.
+$cb
is called whenever it is
+selected.
+@@ -317,22 +1418,20 @@
This class implements timer watchers/events. Time is represented as a fractional number of seconds since the epoch. Example:
- # create a digital clock display in upper right corner + $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); $term->{timer} = urxvt::timer ->new - ->start (urxvt::NOW) + ->interval (1) ->cb (sub { - my ($timer) = @_; - my $time = $timer->at; - $timer->start ($time + 1); - $self->scr_overlay (-1, 0, - POSIX::strftime "%H:%M:%S", localtime $time); + $term->{overlay}->set (0, 0, + sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); });
$interval
is 0
), the timer will automatically
+stop after it has fired once. If $interval
is non-zero, then the timer
+is automatically rescheduled at the given intervals.
+$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
.
This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output.
- +