doc/README.xvt
doc/changes.txt
doc/podtbl
+doc/rxvt-unicode.spec
+
doc/rxvt.1.pod
doc/rxvt.7.pod
doc/rxvtc.1.pod
doc/rxvt.7.man.in
doc/rxvtc.1.man.in
doc/rxvtd.1.man.in
-doc/rxvt.1.html
-doc/rxvt.7.html
-doc/rxvtc.1.html
-doc/rxvtd.1.html
+doc/rxvtperl.3.man.in
doc/rxvt.1.txt
doc/rxvt.7.txt
doc/rxvtc.1.txt
doc/rxvtd.1.txt
-doc/rxvtperl.3.man.in
+doc/rxvtperl.3.txt
+doc/rxvt.1.html
+doc/rxvt.7.html
+doc/rxvtc.1.html
+doc/rxvtd.1.html
doc/rxvtperl.3.html
-doc/rxvt-unicode.spec
autoconf/.cvsignore
autoconf/Make.common.in
--enable-pointer-blank (default: on)
Add support to have the pointer disappear when typing or inactive.
+ --enable-perl (default: off)
+ Enable an embedded perl interpreter. See the rxvtperl(3) manpage
+ (doc/rxvtperl.txt) for more info on this feature, or the files in
+ src/perl-ext/ for the extensions that are installed by default.
+
--with-name=NAME (default: urxvt)
Set the basename for the installed binaries, resulting in "urxvt",
"urxvtd" etc.). Specify "--with-name=rxvt" to replace with "rxvt".
tags allbin:
alldoc: rxvt.1.man.in rxvt.7.man.in rxvtc.1.man.in rxvtd.1.man.in rxvtperl.3.man.in \
- rxvt.1.txt rxvt.7.txt rxvtc.1.txt rxvtd.1.txt \
+ rxvt.1.txt rxvt.7.txt rxvtc.1.txt rxvtd.1.txt rxvtperl.3.txt \
rxvt.1.html rxvt.7.html rxvtc.1.html rxvtd.1.html rxvtperl.3.html \
../README.configure ../README.FAQ
infocmp -C rxvt-unicode >etc/rxvt-unicode.termcap
my $slave = $pty->slave;
while (<$slave>) { print $slave "got <$_>\n" }</pre>
</dd>
+<p></p>
+<dt><strong><a name="item__2dperl_string"><strong>-perl</strong> <em>string</em></a></strong><br />
+</dt>
+<dd>
+Used by perl extension. See resource <strong>perl</strong>.
+</dd>
<p></p></dl>
<p>
</p>
names that are used in turn when trying to display Unicode characters.
The first font defines the cell size for characters; other fonts might
be smaller, but not larger. A reasonable default font list is always
-appended to it. option <strong>-fn</strong>.
+appended to it; option <strong>-fn</strong>.
</dd>
<dd>
<p>Each font can either be a standard X11 core font (XLFD) name, with
The locale to use for opening the IM. You can use an <code>LC_CTYPE</code> of e.g.
<code>de_DE.UTF-8</code> for normal text processing but <code>ja_JP.EUC-JP</code> for the
input extension to be able to input japanese characters while staying in
-another locale. option <strong>-imlocale</strong>.
+another locale; option <strong>-imlocale</strong>.
</dd>
<p></p>
<dt><strong><a name="item_imfont_3a_fontset"><strong>imFont:</strong> <em>fontset</em></a></strong><br />
<dd>
Change the meaning of triple-click selection with the left mouse
button. Instead of selecting a full line it will extend the selection to
-the end of the logical line only. option <strong>-tcw</strong>.
+the end of the logical line only; option <strong>-tcw</strong>.
</dd>
<p></p>
<dt><strong><a name="item_insecure_3a_boolean"><strong>insecure:</strong> <em>boolean</em></a></strong><br />
URxvt.keysym.M-C-3: command:\033[8;25;80t
URxvt.keysym.M-C-4: command:\033[8;48;110t</pre>
</dd>
+<p></p>
+<dt><strong><a name="item_perl_3a_string"><strong>perl</strong>: <em>string</em></a></strong><br />
+</dt>
+<dd>
+Used by perl extension and is free for any use, as it is not interpreted
+by rxvt-unicode itself; option <strong>perl</strong>.
+</dd>
+<p></p>
+<dt><strong><a name="item_perl_2deval_3a_string"><strong>perl-eval</strong>: <em>string</em></a></strong><br />
+</dt>
+<dd>
+Perl code to be evaluated when all extensions have been loaded. See the
+<code>rxvtperl(3)</code> manpage.
+</dd>
+<p></p>
+<dt><strong><a name="item_perl_2dlib_3a_path"><strong>perl-lib</strong>: <em>path</em></a></strong><br />
+</dt>
+<dd>
+Additional directory that holds extension scripts that are loaded and
+enabled for this terminal instance, in addition to scripts stored in
+<em>/opt/rxvt/lib/urxvt/perl-ext/</em>, which are global to all terminal
+instances.
+</dd>
+<dd>
+<p>See the <code>rxvtperl(3)</code> manpage.</p>
+</dd>
<p></p></dl>
<p>
</p>
\& my $slave = $pty->slave;
\& while (<$slave>) { print $slave "got <$_>\en" }
.Ve
+.IP "\fB\-perl\fR \fIstring\fR" 4
+.IX Item "-perl string"
+Used by perl extension. See resource \fBperl\fR.
.SH "RESOURCES (available also as long\-options)"
.IX Header "RESOURCES (available also as long-options)"
Note: `@@RXVT_NAME@@ \-\-help' gives a list of all resources (long
names that are used in turn when trying to display Unicode characters.
The first font defines the cell size for characters; other fonts might
be smaller, but not larger. A reasonable default font list is always
-appended to it. option \fB\-fn\fR.
+appended to it; option \fB\-fn\fR.
.Sp
Each font can either be a standard X11 core font (\s-1XLFD\s0) name, with
optional prefix \f(CW\*(C`x:\*(C'\fR or a Xft font (Compile \fIxft\fR), prefixed with \f(CW\*(C`xft:\*(C'\fR.
The locale to use for opening the \s-1IM\s0. You can use an \f(CW\*(C`LC_CTYPE\*(C'\fR of e.g.
\&\f(CW\*(C`de_DE.UTF\-8\*(C'\fR for normal text processing but \f(CW\*(C`ja_JP.EUC\-JP\*(C'\fR for the
input extension to be able to input japanese characters while staying in
-another locale. option \fB\-imlocale\fR.
+another locale; option \fB\-imlocale\fR.
.IP "\fBimFont:\fR \fIfontset\fR" 4
.IX Item "imFont: fontset"
Specify the font-set used for \s-1XIM\s0 styles \f(CW\*(C`OverTheSpot\*(C'\fR or
.IX Item "tripleclickwords: boolean"
Change the meaning of triple-click selection with the left mouse
button. Instead of selecting a full line it will extend the selection to
-the end of the logical line only. option \fB\-tcw\fR.
+the end of the logical line only; option \fB\-tcw\fR.
.IP "\fBinsecure:\fR \fIboolean\fR" 4
.IX Item "insecure: boolean"
Enables \*(L"insecure\*(R" mode. Rxvt-unicode offers some escape sequences that
\& URxvt.keysym.M-C-3: command:\e033[8;25;80t
\& URxvt.keysym.M-C-4: command:\e033[8;48;110t
.Ve
+.IP "\fBperl\fR: \fIstring\fR" 4
+.IX Item "perl: string"
+Used by perl extension and is free for any use, as it is not interpreted
+by rxvt-unicode itself; option \fBperl\fR.
+.IP "\fBperl-eval\fR: \fIstring\fR" 4
+.IX Item "perl-eval: string"
+Perl code to be evaluated when all extensions have been loaded. See the
+\&\fIrxvtperl\fR\|(3) manpage.
+.IP "\fBperl-lib\fR: \fIpath\fR" 4
+.IX Item "perl-lib: path"
+Additional directory that holds extension scripts that are loaded and
+enabled for this terminal instance, in addition to scripts stored in
+\&\fI@@RXVT_LIBDIR@@/urxvt/perl\-ext/\fR, which are global to all terminal
+instances.
+.Sp
+See the \fIrxvtperl\fR\|(3) manpage.
.SH "THE SCROLLBAR"
.IX Header "THE SCROLLBAR"
Lines of text that scroll off the top of the \fB@@RXVT_NAME@@\fR window
my $slave = $pty->slave;
while (<$slave>) { print $slave "got <$_>\n" }
+=item B<-perl> I<string>
+
+Used by perl extension. See resource B<perl>.
+
=back
=head1 RESOURCES (available also as long-options)
names that are used in turn when trying to display Unicode characters.
The first font defines the cell size for characters; other fonts might
be smaller, but not larger. A reasonable default font list is always
-appended to it. option B<-fn>.
+appended to it; option B<-fn>.
Each font can either be a standard X11 core font (XLFD) name, with
optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>.
The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
input extension to be able to input japanese characters while staying in
-another locale. option B<-imlocale>.
+another locale; option B<-imlocale>.
=item B<imFont:> I<fontset>
Change the meaning of triple-click selection with the left mouse
button. Instead of selecting a full line it will extend the selection to
-the end of the logical line only. option B<-tcw>.
+the end of the logical line only; option B<-tcw>.
=item B<insecure:> I<boolean>
URxvt.keysym.M-C-3: command:\033[8;25;80t
URxvt.keysym.M-C-4: command:\033[8;48;110t
+=item B<perl>: I<string>
+
+Used by perl extension and is free for any use, as it is not interpreted
+by rxvt-unicode itself; option B<perl>.
+
+=item B<perl-eval>: I<string>
+
+Perl code to be evaluated when all extensions have been loaded. See the
+rxvtperl(3) manpage.
+
+=item B<perl-lib>: I<path>
+
+Additional directory that holds extension scripts that are loaded and
+enabled for this terminal instance, in addition to scripts stored in
+F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, which are global to all terminal
+instances.
+
+See the rxvtperl(3) manpage.
+
=back
=head1 THE SCROLLBAR
my $slave = $pty->slave;
while (<$slave>) { print $slave "got <$_>\n" }
+ -perl *string*
+ Used by perl extension. See resource perl.
+
RESOURCES (available also as long-options)
Note: `rxvt --help' gives a list of all resources (long options)
compiled into your version.
names that are used in turn when trying to display Unicode
characters. The first font defines the cell size for characters;
other fonts might be smaller, but not larger. A reasonable default
- font list is always appended to it. option -fn.
+ font list is always appended to it; option -fn.
Each font can either be a standard X11 core font (XLFD) name, with
optional prefix "x:" or a Xft font (Compile *xft*), prefixed with
The locale to use for opening the IM. You can use an "LC_CTYPE" of
e.g. "de_DE.UTF-8" for normal text processing but "ja_JP.EUC-JP" for
the input extension to be able to input japanese characters while
- staying in another locale. option -imlocale.
+ staying in another locale; option -imlocale.
imFont: *fontset*
Specify the font-set used for XIM styles "OverTheSpot" or
tripleclickwords: *boolean*
Change the meaning of triple-click selection with the left mouse
button. Instead of selecting a full line it will extend the
- selection to the end of the logical line only. option -tcw.
+ selection to the end of the logical line only; option -tcw.
insecure: *boolean*
Enables "insecure" mode. Rxvt-unicode offers some escape sequences
URxvt.keysym.M-C-3: command:\033[8;25;80t
URxvt.keysym.M-C-4: command:\033[8;48;110t
+ perl: *string*
+ Used by perl extension and is free for any use, as it is not
+ interpreted by rxvt-unicode itself; option perl.
+
+ perl-eval: *string*
+ Perl code to be evaluated when all extensions have been loaded. See
+ the rxvtperl(3) manpage.
+
+ perl-lib: *path*
+ Additional directory that holds extension scripts that are loaded
+ and enabled for this terminal instance, in addition to scripts
+ stored in /opt/rxvt/lib/urxvt/perl-ext/, which are global to all
+ terminal instances.
+
+ See the rxvtperl(3) manpage.
+
THE SCROLLBAR
Lines of text that scroll off the top of the rxvt window (resource:
saveLines) and can be scrolled back using the scrollbar or by
Add support to have the pointer disappear when typing or inactive.
</dd>
<p></p>
+<dt><strong><a name="item_perl">--enable-perl (default: off)</a></strong><br />
+</dt>
+<dd>
+Enable an embedded perl interpreter. See the <strong>rxvtperl(3)</strong> manpage
+(<em>doc/rxvtperl.txt</em>) for more info on this feature, or the files in
+<em>src/perl-ext/</em> for the extensions that are installed by default.
+</dd>
+<p></p>
<dt><strong>--with-name=NAME (default: urxvt)</strong><br />
</dt>
<dd>
.IP "\-\-enable\-pointer\-blank (default: on)" 4
.IX Item "--enable-pointer-blank (default: on)"
Add support to have the pointer disappear when typing or inactive.
+.IP "\-\-enable\-perl (default: off)" 4
+.IX Item "--enable-perl (default: off)"
+Enable an embedded perl interpreter. See the \fB\f(BIrxvtperl\fB\|(3)\fR manpage
+(\fIdoc/rxvtperl.txt\fR) for more info on this feature, or the files in
+\&\fIsrc/perl\-ext/\fR for the extensions that are installed by default.
.IP "\-\-with\-name=NAME (default: urxvt)" 4
.IX Item "--with-name=NAME (default: urxvt)"
Set the basename for the installed binaries, resulting
Add support to have the pointer disappear when typing or inactive.
+=item --enable-perl (default: off)
+
+Enable an embedded perl interpreter. See the B<rxvtperl(3)> manpage
+(F<doc/rxvtperl.txt>) for more info on this feature, or the files in
+F<src/perl-ext/> for the extensions that are installed by default.
+
=item --with-name=NAME (default: urxvt)
Set the basename for the installed binaries, resulting
--enable-pointer-blank (default: on)
Add support to have the pointer disappear when typing or inactive.
+ --enable-perl (default: off)
+ Enable an embedded perl interpreter. See the rxvtperl(3) manpage
+ (doc/rxvtperl.txt) for more info on this feature, or the files in
+ src/perl-ext/ for the extensions that are installed by default.
+
--with-name=NAME (default: urxvt)
Set the basename for the installed binaries, resulting in "urxvt",
"urxvtd" etc.). Specify "--with-name=rxvt" to replace with "rxvt".
<li><a href="#description">DESCRIPTION</a></li>
<ul>
+ <li><a href="#general_api_considerations">General API Considerations</a></li>
<li><a href="#hooks">Hooks</a></li>
<li><a href="#functions_in_the_urxvt_package">Functions in the <code>urxvt</code> Package</a></li>
<li><a href="#the_urxvt__term_class">The <code>urxvt::term</code> Class</a></li>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>* Put your scripts into <em>/opt/rxvt/lib/urxvt/perl-ext/</em>, they will be loaded automatically.</p>
-<p>* Each script will only be loaded once, even in urxvtd, and will be valid
-globally.</p>
<p>* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
thus must be encoded as UTF-8.</p>
<pre>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
+<p>On startup, rxvt will scan <em>/opt/rxvt/lib/urxvt/perl-ext/</em>
+for files and will load them. Everytime a terminal object gets created,
+the directory specified by the <code>perl-lib</code> resource will be additionally
+scanned.</p>
+<p>Each script will only ever be loaded once, even in rxvtd, where
+scripts will be shared for all terminals.</p>
+<p>Hooks in scripts specified by <code>perl-lib</code> will only be called for the
+terminals created with that specific option value.</p>
+<p>
+</p>
+<h2><a name="general_api_considerations">General API Considerations</a></h2>
+<p>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 <code>_ptr</code> or
+<code>_hook</code>) are reserved for internal uses and must not be accessed or
+modified).</p>
+<p>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.</p>
<p>
</p>
<h2><a name="hooks">Hooks</a></h2>
<dt><strong><a name="item_urxvt_3a_3awarn__24string">urxvt::warn $string</a></strong><br />
</dt>
<dd>
-Calls <code>rxvt_warn</code> witht eh given string which should not include a
+Calls <code>rxvt_warn</code> with the given string which should not include a
newline. The module also overwrites the <code>warn</code> builtin with a function
that calls this function.
</dd>
correct place, e.g. on stderr of the connecting urxvtc client.</p>
</dd>
<p></p>
-<dt><strong><a name="item__24cellwidth__3d_urxvt_3a_3awcswidth__24string">$cellwidth = urxvt::wcswidth $string</a></strong><br />
-</dt>
-<dd>
-Returns the number of screen-cells this string would need. Correctly
-accounts for wide and combining characters.
-</dd>
-<p></p>
<dt><strong><a name="item__24time__3d_urxvt_3a_3anow">$time = urxvt::NOW</a></strong><br />
</dt>
<dd>
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
- visualBell</pre>
+ modifier mouseWheelScrollPage name pastableTabs path perl perl_eval
+ 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</pre>
</dd>
<p></p>
<dt><strong><a name="item_selection_mark">($row, $col) = $term->selection_mark ([$row, $col])</a></strong><br />
<dd>
Write a string at the given position into the overlay.
</dd>
+<p></p>
+<dt><strong><a name="item_strwidth">$cellwidth = $term->strwidth $string</a></strong><br />
+</dt>
+<dd>
+Returns the number of screen-cells this string would need. Correctly
+accounts for wide and combining characters.
+</dd>
+<p></p>
+<dt><strong><a name="item_locale_encode">$octets = $term->locale_encode $string</a></strong><br />
+</dt>
+<dd>
+Convert the given text string into the corresponding locale encoding.
+</dd>
+<p></p>
+<dt><strong><a name="item_locale_decode">$string = $term->locale_decode $octets</a></strong><br />
+</dt>
+<dd>
+Convert the given locale-encoded octets into a perl string.
+</dd>
+<p></p>
+<dt><strong><a name="item_tt_write">$term->tt_write ($octets)</a></strong><br />
+</dt>
+<dd>
+Write the octets given in <code>$data</code> to the tty (i.e. as program input). To
+pass characters instead of octets, you should convetr you strings first to
+the locale-specific encoding using <a href="#item_locale_encode"><code>$term->locale_encode</code></a>.
+</dd>
<p></p></dl>
<p>
</p>
.IX Header "SYNOPSIS"
* Put your scripts into \fI@@RXVT_LIBDIR@@/urxvt/perl\-ext/\fR, they will be loaded automatically.
.PP
-* Each script will only be loaded once, even in urxvtd, and will be valid
-globally.
-.PP
* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
thus must be encoded as \s-1UTF\-8\s0.
.PP
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
+On startup, @@RXVT_NAME@@ will scan \fI@@RXVT_LIBDIR@@/urxvt/perl\-ext/\fR
+for files and will load them. Everytime a terminal object gets created,
+the directory specified by the \f(CW\*(C`perl\-lib\*(C'\fR resource will be additionally
+scanned.
+.PP
+Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
+scripts will be shared for all terminals.
+.PP
+Hooks in scripts specified by \f(CW\*(C`perl\-lib\*(C'\fR will only be called for the
+terminals created with that specific option value.
+.Sh "General \s-1API\s0 Considerations"
+.IX Subsection "General API Considerations"
+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 \f(CW\*(C`_ptr\*(C'\fR or
+\&\f(CW\*(C`_hook\*(C'\fR) are reserved for internal uses and must not be accessed or
+modified).
+.PP
+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.
.Sh "Hooks"
.IX Subsection "Hooks"
The following subroutines can be declared in loaded scripts, and will be called
.ie n .IP "urxvt::warn $string" 4
.el .IP "urxvt::warn \f(CW$string\fR" 4
.IX Item "urxvt::warn $string"
-Calls \f(CW\*(C`rxvt_warn\*(C'\fR witht eh given string which should not include a
+Calls \f(CW\*(C`rxvt_warn\*(C'\fR with the given string which should not include a
newline. The module also overwrites the \f(CW\*(C`warn\*(C'\fR builtin with a function
that calls this function.
.Sp
Using this function has the advantage that its output ends up in the
correct place, e.g. on stderr of the connecting urxvtc client.
-.ie n .IP "$cellwidth = urxvt::wcswidth $string" 4
-.el .IP "$cellwidth = urxvt::wcswidth \f(CW$string\fR" 4
-.IX Item "$cellwidth = urxvt::wcswidth $string"
-Returns the number of screen-cells this string would need. Correctly
-accounts for wide and combining characters.
.IP "$time = urxvt::NOW" 4
.IX Item "$time = urxvt::NOW"
Returns the \*(L"current time\*(R" (as per the event loop).
\& 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
-\& visualBell
+\& modifier mouseWheelScrollPage name pastableTabs path perl perl_eval
+\& 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
.Ve
.ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_mark ([$row, \f(CW$col])" 4
.el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_mark ([$row, \f(CW$col\fR])" 4
.el .IP "$term\->scr_overlay_set ($x, \f(CW$y\fR, \f(CW$text\fR)" 4
.IX Item "$term->scr_overlay_set ($x, $y, $text)"
Write a string at the given position into the overlay.
+.ie n .IP "$cellwidth = $term\fR\->strwidth \f(CW$string" 4
+.el .IP "$cellwidth = \f(CW$term\fR\->strwidth \f(CW$string\fR" 4
+.IX Item "$cellwidth = $term->strwidth $string"
+Returns the number of screen-cells this string would need. Correctly
+accounts for wide and combining characters.
+.ie n .IP "$octets = $term\fR\->locale_encode \f(CW$string" 4
+.el .IP "$octets = \f(CW$term\fR\->locale_encode \f(CW$string\fR" 4
+.IX Item "$octets = $term->locale_encode $string"
+Convert the given text string into the corresponding locale encoding.
+.ie n .IP "$string = $term\fR\->locale_decode \f(CW$octets" 4
+.el .IP "$string = \f(CW$term\fR\->locale_decode \f(CW$octets\fR" 4
+.IX Item "$string = $term->locale_decode $octets"
+Convert the given locale-encoded octets into a perl string.
+.IP "$term\->tt_write ($octets)" 4
+.IX Item "$term->tt_write ($octets)"
+Write the octets given in \f(CW$data\fR to the tty (i.e. as program input). To
+pass characters instead of octets, you should convetr you strings first to
+the locale-specific encoding using \f(CW\*(C`$term\->locale_encode\*(C'\fR.
.ie n .Sh "The ""urxvt::timer"" Class"
.el .Sh "The \f(CWurxvt::timer\fP Class"
.IX Subsection "The urxvt::timer Class"
--- /dev/null
+NAME
+ rxvtperl - rxvt-unicode's embedded perl interpreter
+
+SYNOPSIS
+ * Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be
+ loaded automatically.
+
+ * Scripts are evaluated in a 'use strict' and 'use utf8' environment,
+ and thus must be encoded as UTF-8.
+
+ sub on_sel_grab {
+ warn "you selected ", $_[0]->selection;
+ ()
+ }
+
+ 1
+
+DESCRIPTION
+ On startup, rxvt will scan /opt/rxvt/lib/urxvt/perl-ext/ for files and
+ will load them. Everytime a terminal object gets created, the directory
+ specified by the "perl-lib" resource will be additionally scanned.
+
+ Each script will only ever be loaded once, even in rxvtd, where scripts
+ will be shared for all terminals.
+
+ Hooks in scripts specified by "perl-lib" will only be called for the
+ terminals created with that specific option value.
+
+ General API Considerations
+ 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.
+
+ Hooks
+ 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 "()").
+
+ on_init $term
+ Called after a new terminal object has been initialized, but before
+ windows are created or the command gets run.
+
+ on_reset $term
+ Called after the screen is "reset" for any reason, such as resizing
+ or control sequences. Here is where you can react on changes to
+ size-related variables.
+
+ on_start $term
+ Called at the very end of initialisation of a new terminal, just
+ before returning to the mainloop.
+
+ on_sel_make $term, $eventtime
+ Called whenever a selection has been made by the user, but before
+ the selection text is copied, so changes to the beginning, end or
+ type of the selection will be honored.
+
+ Returning a true value aborts selection making by urxvt, in which
+ case you have to make a selection yourself by calling
+ "$term->selection_grab".
+
+ on_sel_grab $term, $eventtime
+ Called whenever a selection has been copied, but before the
+ selection is requested from the server. The selection text can be
+ queried and changed by calling "$term->selection".
+
+ Returning a true value aborts selection grabbing. It will still be
+ hilighted.
+
+ on_focus_in $term
+ Called whenever the window gets the keyboard focus, before urxvt
+ does focus in processing.
+
+ on_focus_out $term
+ Called wheneever the window loses keyboard focus, before urxvt does
+ focus out processing.
+
+ on_view_change $term, $offset
+ Called whenever the view offset changes, i..e the user or program
+ scrolls. Offset 0 means display the normal terminal, positive values
+ show this many lines of scrollback.
+
+ on_scroll_back $term, $lines, $saved
+ Called whenever lines scroll out of the terminal area into the
+ scrollback buffer. $lines is the number of lines scrolled out and
+ may be larger than the scroll back buffer or the terminal.
+
+ It is called before lines are scrolled out (so rows 0 .. min ($lines
+ - 1, $nrow - 1) represent the lines to be scrolled out). $saved is
+ the total number of lines that will be in the scrollback buffer.
+
+ on_tty_activity $term *NYI*
+ Called whenever the program(s) running in the urxvt window send
+ output.
+
+ on_refresh_begin $term
+ Called just before the screen gets redrawn. Can be used for overlay
+ or similar effects by modify terminal contents in refresh_begin, and
+ restoring them in refresh_end. The built-in overlay and selection
+ display code is run after this hook, and takes precedence.
+
+ on_refresh_end $term
+ Called just after the screen gets redrawn. See "on_refresh_begin".
+
+ Functions in the "urxvt" Package
+ urxvt::fatal $errormessage
+ Fatally aborts execution with the given error message. Avoid at all
+ costs! The only time this is acceptable is when the terminal process
+ starts up.
+
+ urxvt::warn $string
+ 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.
+
+ $time = urxvt::NOW
+ Returns the "current time" (as per the event loop).
+
+ The "urxvt::term" Class
+ $value = $term->resource ($name[, $newval])
+ Returns the current resource value associated with a given name and
+ optionally sets a new value. Setting values is most useful in the
+ "init" hook. Unset resources are returned and accepted as "undef".
+
+ The new value must be properly encoded to a suitable character
+ encoding before passing it to this method. Similarly, the returned
+ value may need to be converted from the used encoding to text.
+
+ Resource names are as defined in src/rsinc.h. Colours can be
+ specified as resource names of the form "color+<index>", e.g.
+ "color+5". (will likely change).
+
+ Please note that resource strings will currently only be freed when
+ the terminal is destroyed, so changing options frequently will eat
+ memory.
+
+ 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:
+
+ answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
+ 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 perl_eval
+ 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
+
+ ($row, $col) = $term->selection_mark ([$row, $col])
+ ($row, $col) = $term->selection_beg ([$row, $col])
+ ($row, $col) = $term->selection_end ([$row, $col])
+ Return the current values of the selection mark, begin or end
+ positions, and optionally set them to new values.
+
+ $success = $term->selection_grab ($eventtime)
+ Try to request the primary selection from the server (for example,
+ as set by the next method).
+
+ $oldtext = $term->selection ([$newtext])
+ Return the current selection text and optionally replace it by
+ $newtext.
+
+ $term->scr_overlay ($x, $y, $text)
+ Create a simple multi-line overlay box. See the next method for
+ details.
+
+ $term->scr_overlay_new ($x, $y, $width, $height)
+ Create a new (empty) overlay at the given position with the given
+ width/height. A border will be put around the box. If either $x or
+ $y is negative, then this is counted from the right/bottom side,
+ respectively.
+
+ $term->scr_overlay_off
+ Switch the overlay off again.
+
+ $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
+ Put a single character (specified numerically) at the given overlay
+ position.
+
+ $term->scr_overlay_set ($x, $y, $text)
+ Write a string at the given position into the overlay.
+
+ $cellwidth = $term->strwidth $string
+ Returns the number of screen-cells this string would need. Correctly
+ accounts for wide and combining characters.
+
+ $octets = $term->locale_encode $string
+ Convert the given text string into the corresponding locale
+ encoding.
+
+ $string = $term->locale_decode $octets
+ Convert the given locale-encoded octets into a perl string.
+
+ $term->tt_write ($octets)
+ Write the octets given in $data to the tty (i.e. as program input).
+ To pass characters instead of octets, you should convetr you strings
+ first to the locale-specific encoding using "$term->locale_encode".
+
+ The "urxvt::timer" Class
+ 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->{timer} = urxvt::timer
+ ->new
+ ->start (urxvt::NOW)
+ ->cb (sub {
+ my ($timer) = @_;
+ my $time = $timer->at;
+ $timer->start ($time + 1);
+ $self->scr_overlay (-1, 0,
+ POSIX::strftime "%H:%M:%S", localtime $time);
+ });
+
+ $timer = new urxvt::timer
+ Create a new timer object in stopped state.
+
+ $timer = $timer->cb (sub { my ($timer) = @_; ... })
+ Set the callback to be called when the timer triggers.
+
+ $tstamp = $timer->at
+ Return the time this watcher will fire next.
+
+ $timer = $timer->set ($tstamp)
+ Set the time the event is generated to $tstamp.
+
+ $timer = $timer->start
+ Start the timer.
+
+ $timer = $timer->start ($tstamp)
+ Set the event trigger time to $tstamp and start the timer.
+
+ $timer = $timer->stop
+ Stop the timer.
+
+ The "urxvt::iow" Class
+ This class implements io watchers/events. Example:
+
+ $term->{socket} = ...
+ $term->{iow} = urxvt::iow
+ ->new
+ ->fd (fileno $term->{socket})
+ ->events (1) # wait for read data
+ ->start
+ ->cb (sub {
+ my ($iow, $revents) = @_;
+ # $revents must be 1 here, no need to check
+ sysread $term->{socket}, my $buf, 8192
+ or end-of-file;
+ });
+
+ $iow = new urxvt::iow
+ Create a new io watcher object in stopped state.
+
+ $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
+ Set the callback to be called when io events are triggered.
+ $reventmask is a bitset as described in the "events" method.
+
+ $iow = $iow->fd ($fd)
+ Set the filedescriptor (not handle) to watch.
+
+ $iow = $iow->events ($eventmask)
+ Set the event mask to watch. Bit #0 (value 1) enables watching for
+ read data, Bit #1 (value 2) enables watching for write data.
+
+ $iow = $iow->start
+ Start watching for requested events on the given handle.
+
+ $iow = $iow->stop
+ Stop watching for events on the given filehandle.
+
+ENVIRONMENT
+ URXVT_PERL_VERBOSITY
+ This variable controls the verbosity level of the perl extension. Higher
+ numbers indicate more verbose output.
+
+ 0 - only fatal messages
+ 3 - script loading and management
+ 10 - all events received
+
+AUTHOR
+ Marc Lehmann <pcg@goof.com>
+ http://software.schmorp.de/pkg/rxvt-unicode
+
@IF_PERL@ $(INSTALL) -d $(DESTDIR)$(libdir)/urxvt
@IF_PERL@ $(INSTALL) -d $(DESTDIR)$(libdir)/urxvt/perl-ext
@IF_PERL@ $(INSTALL_DATA) urxvt.pm $(DESTDIR)$(libdir)/urxvt/urxvt.pm
-@IF_PERL@ for ext in perl-ext/*; do $(INSTALL_DATA) "$$ext" $(DESTDIR)$(libdir)/urxvt/"$$ext"; done
+@IF_PERL@ for ext in perl-ext/*; do test -f "$$ext" && $(INSTALL_DATA) "$$ext" $(DESTDIR)$(libdir)/urxvt/"$$ext"; done
install: allbin alldoc install-perl
$(INSTALL) -d $(DESTDIR)$(bindir)
projects / dana / urxvt.git / commitdiff