From 3b34fd51ee3dce2b592e223f8c26573b706700f5 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 2 Jan 2006 19:36:07 +0000 Subject: [PATCH] *** empty log message *** --- MANIFEST | 14 +- README.configure | 5 + doc/Makefile.in | 2 +- doc/rxvt.1.html | 38 +++++- doc/rxvt.1.man.in | 25 +++- doc/rxvt.1.pod | 29 +++- doc/rxvt.1.txt | 25 +++- doc/rxvt.7.html | 8 ++ doc/rxvt.7.man.in | 5 + doc/rxvt.7.pod | 6 + doc/rxvt.7.txt | 5 + doc/rxvtperl.3.html | 73 +++++++--- doc/rxvtperl.3.man.in | 64 ++++++--- doc/rxvtperl.3.txt | 304 ++++++++++++++++++++++++++++++++++++++++++ src/Makefile.in | 2 +- 15 files changed, 552 insertions(+), 53 deletions(-) create mode 100644 doc/rxvtperl.3.txt diff --git a/MANIFEST b/MANIFEST index 25be7362..9e2c420d 100644 --- 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 index 788fbca1..ba51acdc 100644 --- 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 index 9995a8a9..0c56cb93 100644 --- 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 index 4c7f9999..2ca7efdd 100644 --- a/doc/rxvt.1.html +++ b/doc/rxvt.1.html @@ -627,6 +627,12 @@ longer example is in doc/pty-fd):

my $slave = $pty->slave; while (<$slave>) { print $slave "got <$_>\n" } +

+
-perl string
+
+
+Used by perl extension. See resource perl. +

@@ -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 -fn. +appended to it; option -fn.

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 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. +another locale; option -imlocale.

imFont: fontset
@@ -1235,7 +1241,7 @@ option -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 -tcw. +the end of the logical line only; option -tcw.

insecure: boolean
@@ -1409,6 +1415,32 @@ info):

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.

+

diff --git a/doc/rxvt.1.man.in b/doc/rxvt.1.man.in index 2072449f..ec409ea1 100644 --- 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 index 15eeeb87..4fa5d125 100644 --- a/doc/rxvt.1.pod +++ b/doc/rxvt.1.pod @@ -455,6 +455,10 @@ longer example is in F): my $slave = $pty->slave; while (<$slave>) { print $slave "got <$_>\n" } +=item B<-perl> I + +Used by perl extension. See resource B. + =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 or a Xft font (Compile I), prefixed with C. @@ -904,7 +908,7 @@ I of inputMethod to use; option B<-im>. The locale to use for opening the IM. You can use an C of e.g. C for normal text processing but C 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 I @@ -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 I @@ -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: I + +Used by perl extension and is free for any use, as it is not interpreted +by rxvt-unicode itself; option B. + +=item B: I + +Perl code to be evaluated when all extensions have been loaded. See the +rxvtperl(3) manpage. + +=item B: I + +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 index 5b159a87..342ff5c0 100644 --- 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 index 307b0cd7..1db0e95f 100644 --- 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.

+
--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)
diff --git a/doc/rxvt.7.man.in b/doc/rxvt.7.man.in index 575c5dec..79c59b57 100644 --- 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 index 13426c26..dd2ad4b8 100644 --- 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 manpage +(F) for more info on this feature, or the files in +F 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 index 183db6e3..19919bbc 100644 --- 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 index f23d159f..007335b2 100644 --- a/doc/rxvtperl.3.html +++ b/doc/rxvtperl.3.html @@ -17,6 +17,7 @@
  • DESCRIPTION
      • +
    • General API Considerations
    • Hooks
    • Functions in the urxvt Package
    • The urxvt::term Class
      • @@ -44,8 +45,6 @@

      SYNOPSIS

      * 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.

      @@ -59,6 +58,26 @@ thus must be encoded as UTF-8.
      
 
      
 
      
 
      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
      
@@ -185,7 +204,7 @@ starts up.
 
      urxvt::warn $string
      
 
      
 
      
-Calls 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.
 
      
@@ -194,13 +213,6 @@ that calls this function.
 correct place, e.g. on stderr of the connecting urxvtc client.

    -
    $cellwidth = urxvt::wcswidth $string
    -
    -
    -Returns the number of screen-cells this string would need. Correctly -accounts for wide and combining characters. -
    -

    $time = urxvt::NOW
    @@ -244,13 +256,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

    ($row, $col) = $term->selection_mark ([$row, $col])
    @@ -310,6 +322,33 @@ position.
    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. +

    diff --git a/doc/rxvtperl.3.man.in b/doc/rxvtperl.3.man.in index df2fc6e9..c926210d 100644 --- 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 00000000..075e7b1e --- /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+", 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 + http://software.schmorp.de/pkg/rxvt-unicode + diff --git a/src/Makefile.in b/src/Makefile.in index 3bc434ad..1a8d7257 100644 --- 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) -- 2.34.1