-- Leo's gemini proxy
-- Connecting to git.thebackupbox.net:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini
repo: rxvt-unicode-sixel action: commit revision: path_from: revision_from: 16d315903e453efec5a9cbd56c9d34b4af663c51: path_to: revision_to:
commit 16d315903e453efec5a9cbd56c9d34b4af663c51
Author: Marc Lehmann <schmorp@schmorp.de>
Date: Mon Jan 2 19:36:07 2006 +0000
*** empty log message ***
diff --git a/MANIFEST b/MANIFEST
--- a/MANIFEST +++ b/MANIFEST @@ -30,6 +30,8 @@ doc/README.menu doc/README.xvt doc/changes.txt doc/podtbl +doc/rxvt-unicode.spec + doc/rxvt.1.pod doc/rxvt.7.pod doc/rxvtc.1.pod @@ -38,17 +40,17 @@ doc/rxvt.1.man.in 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 diff --git a/README.configure b/README.configure
--- a/README.configure
+++ b/README.configure
@@ -240,6 +240,11 @@ CONFIGURE OPTIONS
--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".
diff --git a/doc/Makefile.in b/doc/Makefile.in
--- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -50,7 +50,7 @@ rxvtperl.3.pod: ../src/urxvt.pm 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 diff --git a/doc/rxvt.1.html b/doc/rxvt.1.html
--- a/doc/rxvt.1.html
+++ b/doc/rxvt.1.html
@@ -627,6 +627,12 @@ longer example is in <em>doc/pty-fd</em>):</p>
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>
@@ -857,7 +863,7 @@ Select the fonts to be used. This is a comma separated list of font
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
@@ -1216,7 +1222,7 @@ built-in default:
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 />
@@ -1235,7 +1241,7 @@ option <strong>-imfont</strong>.
<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 />
@@ -1409,6 +1415,32 @@ info):</p>
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>
diff --git a/doc/rxvt.1.man.in b/doc/rxvt.1.man.in
--- a/doc/rxvt.1.man.in
+++ b/doc/rxvt.1.man.in
@@ -534,6 +534,9 @@ longer example is in \fIdoc/pty\-fd\fR):
\& 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
@@ -694,7 +697,7 @@ Select the fonts to be used. This is a comma separated list of font
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.
@@ -927,7 +930,7 @@ built-in default:
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
@@ -940,7 +943,7 @@ option \fB\-imfont\fR.
.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
@@ -1077,6 +1080,22 @@ info):
\& 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
diff --git a/doc/rxvt.1.pod b/doc/rxvt.1.pod
--- a/doc/rxvt.1.pod
+++ b/doc/rxvt.1.pod
@@ -455,6 +455,10 @@ longer example is in F<doc/pty-fd>):
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)
@@ -639,7 +643,7 @@ Select the fonts to be used. This is a comma separated list of font
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:>.
@@ -904,7 +908,7 @@ I<name> of inputMethod to use; option B<-im>.
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>
@@ -919,7 +923,7 @@ option B<-imfont>.
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>
@@ -1052,6 +1056,25 @@ info):
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
diff --git a/doc/rxvt.1.txt b/doc/rxvt.1.txt
--- a/doc/rxvt.1.txt
+++ b/doc/rxvt.1.txt
@@ -392,6 +392,9 @@ OPTIONS
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.
@@ -547,7 +550,7 @@ 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 -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
@@ -776,7 +779,7 @@ RESOURCES (available also as long-options)
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
@@ -789,7 +792,7 @@ RESOURCES (available also as long-options)
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
@@ -915,6 +918,22 @@ RESOURCES (available also as long-options)
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
diff --git a/doc/rxvt.7.html b/doc/rxvt.7.html
--- a/doc/rxvt.7.html +++ b/doc/rxvt.7.html @@ -3016,6 +3016,14 @@ the screen in a fixed position. 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> diff --git a/doc/rxvt.7.man.in b/doc/rxvt.7.man.in
--- a/doc/rxvt.7.man.in +++ b/doc/rxvt.7.man.in @@ -2535,6 +2535,11 @@ the screen in a fixed position. .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 diff --git a/doc/rxvt.7.pod b/doc/rxvt.7.pod
--- a/doc/rxvt.7.pod +++ b/doc/rxvt.7.pod @@ -2566,6 +2566,12 @@ the screen in a fixed position. 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 diff --git a/doc/rxvt.7.txt b/doc/rxvt.7.txt
--- a/doc/rxvt.7.txt
+++ b/doc/rxvt.7.txt
@@ -2000,6 +2000,11 @@ CONFIGURE OPTIONS
--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".
diff --git a/doc/rxvtperl.3.html b/doc/rxvtperl.3.html
--- a/doc/rxvtperl.3.html +++ b/doc/rxvtperl.3.html @@ -17,6 +17,7 @@ <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> @@ -44,8 +45,6 @@ <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> @@ -59,6 +58,26 @@ thus must be encoded as UTF-8.</p> </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> @@ -185,7 +204,7 @@ starts up. <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> @@ -194,13 +213,6 @@ that calls this function. 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> @@ -244,13 +256,13 @@ list:</p> 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 /> @@ -310,6 +322,33 @@ position. <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> diff --git a/doc/rxvtperl.3.man.in b/doc/rxvtperl.3.man.in
--- a/doc/rxvtperl.3.man.in
+++ b/doc/rxvtperl.3.man.in
@@ -136,9 +136,6 @@ rxvtperl \- rxvt\-unicode's embedded perl interpreter
.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
@@ -154,6 +151,28 @@ thus must be encoded as \s-1UTF\-8\s0.
.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
@@ -250,17 +269,12 @@ starts up.
.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).
@@ -295,13 +309,13 @@ list:
\& 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
@@ -348,6 +362,24 @@ position.
.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"
diff --git a/doc/rxvtperl.3.txt b/doc/rxvtperl.3.txt
new file mode 100644
index 0000000000000000000000000000000000000000..075e7b1e48795f4dd064e6f86e20e3d0caae7056
--- /dev/null
+++ b/doc/rxvtperl.3.txt
@@ -0,0 +1,304 @@
+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
+
diff --git a/src/Makefile.in b/src/Makefile.in
--- a/src/Makefile.in +++ b/src/Makefile.in @@ -98,7 +98,7 @@ install-perl: @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)
-----END OF PAGE-----
-- Response ended
-- Page fetched on Sun Jun 2 13:44:33 2024