From: root Date: Mon, 2 Jan 2006 15:59:25 +0000 (+0000) Subject: *** empty log message *** X-Git-Url: http://git.openbox.org/?a=commitdiff_plain;h=ba2a4a5f50941c0e6150bb09f57d460364c90228;p=dana%2Furxvt.git *** empty log message *** --- diff --git a/MANIFEST b/MANIFEST index c38a794e..f3a6b1f6 100644 --- a/MANIFEST +++ b/MANIFEST @@ -46,6 +46,8 @@ doc/rxvt.1.txt doc/rxvt.7.txt doc/rxvtc.1.txt doc/rxvtd.1.txt +doc/rxvtperl.3.man.in +doc/rxvtperl.3.html doc/rxvt-unicode.spec autoconf/.cvsignore diff --git a/autoconf/Make.common.in b/autoconf/Make.common.in index 4aa2dbdd..d2cee058 100644 --- a/autoconf/Make.common.in +++ b/autoconf/Make.common.in @@ -16,6 +16,8 @@ libdir = @libdir@ includedir = @includedir@ man1dir = @mandir@/man1 man1ext = 1 +man3dir = @mandir@/man3 +man3ext = 3 man7dir = @mandir@/man7 man7ext = 7 diff --git a/doc/Makefile.in b/doc/Makefile.in index 47a748bf..9995a8a9 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -15,9 +15,13 @@ dummy: all: -SEDREPLACE = -e 's%@@RXVT_VERSION@@%$(VERSION)%g;'\ - -e 's%@@RXVT_NAME@@%$(RXVTNAME)%g;'\ - -e 's%@@RXVT_DATE@@%$(DATE)%g;' +SEDREPLACE = -e 's%@@RXVT_VERSION@@%$(VERSION)%g;' \ + -e 's%@@RXVT_NAME@@%$(RXVTNAME)%g;' \ + -e 's%@@RXVT_DATE@@%$(DATE)%g;' \ + -e 's%@@RXVT_LIBDIR@@%$(libdir)%g;' + +rxvtperl.3.pod: ../src/urxvt.pm + cp $< $@ %.tbl: %.pod ./podtbl <$< >$@ @@ -25,6 +29,9 @@ SEDREPLACE = -e 's%@@RXVT_VERSION@@%$(VERSION)%g;'\ %.1.man.in: %.1.tbl pod2man -n rxvt -r"$(VERSION)" -q\" -s1 -c "RXVT-UNICODE" <$< >$@ +%.3.man.in: %.3.tbl + pod2man -n rxvt -r"$(VERSION)" -q\" -s3 -c "RXVT-UNICODE" <$< >$@ + %.7.man.in: %.7.tbl pod2man -n rxvt -r"$(VERSION)" -q\" -s7 -c "RXVT-UNICODE" <$< >$@ @@ -42,9 +49,9 @@ SEDREPLACE = -e 's%@@RXVT_VERSION@@%$(VERSION)%g;'\ tags allbin: -alldoc: rxvt.1.man.in rxvt.7.man.in rxvtc.1.man.in rxvtd.1.man.in \ +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.html rxvt.7.html rxvtc.1.html rxvtd.1.html \ + 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 @@ -64,15 +71,18 @@ distclean: install: $(INSTALL) -d $(DESTDIR)$(man1dir) - $(INSTALL) -d $(DESTDIR)$(man7dir) $(SED) $(SEDREPLACE) < rxvt.1.man.in >rxvt.1.man $(INSTALL_DATA) rxvt.1.man $(DESTDIR)$(man1dir)/$(RXVTNAME).$(man1ext) - $(SED) $(SEDREPLACE) < rxvt.7.man.in >rxvt.7.man - $(INSTALL_DATA) rxvt.7.man $(DESTDIR)$(man7dir)/$(RXVTNAME).$(man7ext) $(SED) $(SEDREPLACE) < rxvtc.1.man.in >rxvtc.1.man $(INSTALL_DATA) rxvtc.1.man $(DESTDIR)$(man1dir)/$(RXVTNAME)c.$(man1ext) $(SED) $(SEDREPLACE) < rxvtd.1.man.in >rxvtd.1.man $(INSTALL_DATA) rxvtd.1.man $(DESTDIR)$(man1dir)/$(RXVTNAME)d.$(man1ext) + $(INSTALL) -d $(DESTDIR)$(man7dir) + $(SED) $(SEDREPLACE) < rxvt.7.man.in >rxvt.7.man + $(INSTALL_DATA) rxvt.7.man $(DESTDIR)$(man7dir)/$(RXVTNAME).$(man7ext) +@IF_PERL@ $(INSTALL) -d $(DESTDIR)$(man3dir) +@IF_PERL@ $(SED) $(SEDREPLACE) < rxvtperl.3.man.in >rxvtperl.3.man +@IF_PERL@ $(INSTALL_DATA) rxvtperl.3.man $(DESTDIR)$(man3dir)/$(RXVTNAME)perl.$(man3ext) if test -x "@TIC@"; then if test -n "@TIC@"; then @TIC@ etc/rxvt-unicode.terminfo; fi; fi uninstall: diff --git a/doc/rxvtperl.3.html b/doc/rxvtperl.3.html new file mode 100644 index 00000000..bb91b270 --- /dev/null +++ b/doc/rxvtperl.3.html @@ -0,0 +1,392 @@ + + + +rxvtperl - rxvt-unicode's embedded perl interpreter + + + + + +

+ + +

Hooks
Functions in the urxvt Package
The urxvt::term Class
The urxvt::timer Class
The urxvt::iow Class

AUTHOR

+ + +

NAME

rxvtperl - rxvt-unicode's embedded perl interpreter

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.

+   sub on_sel_grab {
+      warn "you selected ", $_[0]->selection;
+      ()
+   }

+   1

DESCRIPTION

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 witht eh 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.
+
$cellwidth = urxvt::wcswidth $string
+: +Returns the number of screen-cells this string would need. Correctly +accounts for wide and combining characters. +
$time = urxvt::NOW
+: +Returns the ``current time'' (as per the event loop). +

The `urxvt::term` Class

($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. +

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

AUTHOR

+ Marc Lehmann <pcg@goof.com>
+ http://software.schmorp.de/pkg/rxvt-unicode

+ + + + diff --git a/doc/rxvtperl.3.man.in b/doc/rxvtperl.3.man.in new file mode 100644 index 00000000..e607e055 --- /dev/null +++ b/doc/rxvtperl.3.man.in @@ -0,0 +1,410 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "rxvt 3" +.TH rxvt 3 "2006-01-02" "6.2" "RXVT-UNICODE" +.SH "NAME" +rxvtperl \- rxvt\-unicode's embedded perl interpreter +.SH "SYNOPSIS" +.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 +.Vb 4 +\& sub on_sel_grab { +\& warn "you selected ", $_[0]->selection; +\& () +\& } +.Ve +.PP +.Vb 1 +\& 1 +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.Sh "Hooks" +.IX Subsection "Hooks" +The following subroutines can be declared in loaded scripts, and will be called +whenever the relevant event happens. +.PP +All of them must return a boolean value. If it is true, then the event +counts as being \fIconsumed\fR, and the invocation of other hooks is skipped, +and the relevant action might not be carried out by the \*(C+ code. +.PP +When in doubt, return a false value (preferably \f(CW\*(C`()\*(C'\fR). +.ie n .IP "on_init $term" 4 +.el .IP "on_init \f(CW$term\fR" 4 +.IX Item "on_init $term" +Called after a new terminal object has been initialized, but before +windows are created or the command gets run. +.ie n .IP "on_reset $term" 4 +.el .IP "on_reset \f(CW$term\fR" 4 +.IX Item "on_reset $term" +Called after the screen is \*(L"reset\*(R" for any reason, such as resizing or +control sequences. Here is where you can react on changes to size-related +variables. +.ie n .IP "on_start $term" 4 +.el .IP "on_start \f(CW$term\fR" 4 +.IX Item "on_start $term" +Called at the very end of initialisation of a new terminal, just before +returning to the mainloop. +.ie n .IP "on_sel_make $term\fR, \f(CW$eventtime" 4 +.el .IP "on_sel_make \f(CW$term\fR, \f(CW$eventtime\fR" 4 +.IX Item "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. +.Sp +Returning a true value aborts selection making by urxvt, in which case you +have to make a selection yourself by calling \f(CW\*(C`$term\->selection_grab\*(C'\fR. +.ie n .IP "on_sel_grab $term\fR, \f(CW$eventtime" 4 +.el .IP "on_sel_grab \f(CW$term\fR, \f(CW$eventtime\fR" 4 +.IX Item "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 \f(CW\*(C`$term\->selection\*(C'\fR. +.Sp +Returning a true value aborts selection grabbing. It will still be hilighted. +.ie n .IP "on_focus_in $term" 4 +.el .IP "on_focus_in \f(CW$term\fR" 4 +.IX Item "on_focus_in $term" +Called whenever the window gets the keyboard focus, before urxvt does +focus in processing. +.ie n .IP "on_focus_out $term" 4 +.el .IP "on_focus_out \f(CW$term\fR" 4 +.IX Item "on_focus_out $term" +Called wheneever the window loses keyboard focus, before urxvt does focus +out processing. +.ie n .IP "on_view_change $term\fR, \f(CW$offset" 4 +.el .IP "on_view_change \f(CW$term\fR, \f(CW$offset\fR" 4 +.IX Item "on_view_change $term, $offset" +Called whenever the view offset changes, i..e the user or program +scrolls. Offset \f(CW0\fR means display the normal terminal, positive values +show this many lines of scrollback. +.ie n .IP "on_scroll_back $term\fR, \f(CW$lines\fR, \f(CW$saved" 4 +.el .IP "on_scroll_back \f(CW$term\fR, \f(CW$lines\fR, \f(CW$saved\fR" 4 +.IX Item "on_scroll_back $term, $lines, $saved" +Called whenever lines scroll out of the terminal area into the scrollback +buffer. \f(CW$lines\fR is the number of lines scrolled out and may be larger +than the scroll back buffer or the terminal. +.Sp +It is called before lines are scrolled out (so rows 0 .. min ($lines \- 1, +\&\f(CW$nrow\fR \- 1) represent the lines to be scrolled out). \f(CW$saved\fR is the total +number of lines that will be in the scrollback buffer. +.ie n .IP "on_tty_activity $term *NYI*" 4 +.el .IP "on_tty_activity \f(CW$term\fR *NYI*" 4 +.IX Item "on_tty_activity $term *NYI*" +Called whenever the program(s) running in the urxvt window send output. +.ie n .IP "on_refresh_begin $term" 4 +.el .IP "on_refresh_begin \f(CW$term\fR" 4 +.IX Item "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. +.ie n .IP "on_refresh_end $term" 4 +.el .IP "on_refresh_end \f(CW$term\fR" 4 +.IX Item "on_refresh_end $term" +Called just after the screen gets redrawn. See \f(CW\*(C`on_refresh_begin\*(C'\fR. +.ie n .Sh "Functions in the ""urxvt"" Package" +.el .Sh "Functions in the \f(CWurxvt\fP Package" +.IX Subsection "Functions in the urxvt Package" +.ie n .IP "urxvt::fatal $errormessage" 4 +.el .IP "urxvt::fatal \f(CW$errormessage\fR" 4 +.IX Item "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. +.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 +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). +.ie n .Sh "The ""urxvt::term"" Class" +.el .Sh "The \f(CWurxvt::term\fP Class" +.IX Subsection "The urxvt::term Class" +.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 +.IX Item "($row, $col) = $term->selection_mark ([$row, $col])" +.PD 0 +.ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_beg ([$row, \f(CW$col])" 4 +.el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_beg ([$row, \f(CW$col\fR])" 4 +.IX Item "($row, $col) = $term->selection_beg ([$row, $col])" +.ie n .IP "($row, $col\fR) = \f(CW$term\fR\->selection_end ([$row, \f(CW$col])" 4 +.el .IP "($row, \f(CW$col\fR) = \f(CW$term\fR\->selection_end ([$row, \f(CW$col\fR])" 4 +.IX Item "($row, $col) = $term->selection_end ([$row, $col])" +.PD +Return the current values of the selection mark, begin or end positions, +and optionally set them to new values. +.ie n .IP "$success = $term\->selection_grab ($eventtime)" 4 +.el .IP "$success = \f(CW$term\fR\->selection_grab ($eventtime)" 4 +.IX Item "$success = $term->selection_grab ($eventtime)" +Try to request the primary selection from the server (for example, as set +by the next method). +.ie n .IP "$oldtext = $term\->selection ([$newtext])" 4 +.el .IP "$oldtext = \f(CW$term\fR\->selection ([$newtext])" 4 +.IX Item "$oldtext = $term->selection ([$newtext])" +Return the current selection text and optionally replace it by \f(CW$newtext\fR. +.ie n .IP "$term\->scr_overlay ($x, $y\fR, \f(CW$text)" 4 +.el .IP "$term\->scr_overlay ($x, \f(CW$y\fR, \f(CW$text\fR)" 4 +.IX Item "$term->scr_overlay ($x, $y, $text)" +Create a simple multi-line overlay box. See the next method for details. +.ie n .IP "$term\->scr_overlay_new ($x, $y\fR, \f(CW$width\fR, \f(CW$height)" 4 +.el .IP "$term\->scr_overlay_new ($x, \f(CW$y\fR, \f(CW$width\fR, \f(CW$height\fR)" 4 +.IX Item "$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 \f(CW$x\fR or +\&\f(CW$y\fR is negative, then this is counted from the right/bottom side, +respectively. +.IP "$term\->scr_overlay_off" 4 +.IX Item "$term->scr_overlay_off" +Switch the overlay off again. +.ie n .IP "$term\->scr_overlay_set_char ($x, $y\fR, \f(CW$char\fR, \f(CW$rend = \s-1OVERLAY_RSTYLE\s0)" 4 +.el .IP "$term\->scr_overlay_set_char ($x, \f(CW$y\fR, \f(CW$char\fR, \f(CW$rend\fR = \s-1OVERLAY_RSTYLE\s0)" 4 +.IX Item "$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)" +Put a single character (specified numerically) at the given overlay +position. +.ie n .IP "$term\->scr_overlay_set ($x, $y\fR, \f(CW$text)" 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 .Sh "The ""urxvt::timer"" Class" +.el .Sh "The \f(CWurxvt::timer\fP Class" +.IX Subsection "The urxvt::timer Class" +This class implements timer watchers/events. Time is represented as a +fractional number of seconds since the epoch. Example: +.PP +.Vb 11 +\& # 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); +\& }); +.Ve +.IP "$timer = new urxvt::timer" 4 +.IX Item "$timer = new urxvt::timer" +Create a new timer object in stopped state. +.ie n .IP "$timer = $timer\fR\->cb (sub { my ($timer) = \f(CW@_; ... })" 4 +.el .IP "$timer = \f(CW$timer\fR\->cb (sub { my ($timer) = \f(CW@_\fR; ... })" 4 +.IX Item "$timer = $timer->cb (sub { my ($timer) = @_; ... })" +Set the callback to be called when the timer triggers. +.ie n .IP "$tstamp = $timer\->at" 4 +.el .IP "$tstamp = \f(CW$timer\fR\->at" 4 +.IX Item "$tstamp = $timer->at" +Return the time this watcher will fire next. +.ie n .IP "$timer = $timer\->set ($tstamp)" 4 +.el .IP "$timer = \f(CW$timer\fR\->set ($tstamp)" 4 +.IX Item "$timer = $timer->set ($tstamp)" +Set the time the event is generated to \f(CW$tstamp\fR. +.ie n .IP "$timer = $timer\->start" 4 +.el .IP "$timer = \f(CW$timer\fR\->start" 4 +.IX Item "$timer = $timer->start" +Start the timer. +.ie n .IP "$timer = $timer\->start ($tstamp)" 4 +.el .IP "$timer = \f(CW$timer\fR\->start ($tstamp)" 4 +.IX Item "$timer = $timer->start ($tstamp)" +Set the event trigger time to \f(CW$tstamp\fR and start the timer. +.ie n .IP "$timer = $timer\->stop" 4 +.el .IP "$timer = \f(CW$timer\fR\->stop" 4 +.IX Item "$timer = $timer->stop" +Stop the timer. +.ie n .Sh "The ""urxvt::iow"" Class" +.el .Sh "The \f(CWurxvt::iow\fP Class" +.IX Subsection "The urxvt::iow Class" +This class implements io watchers/events. Example: +.PP +.Vb 12 +\& $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; +\& }); +.Ve +.IP "$iow = new urxvt::iow" 4 +.IX Item "$iow = new urxvt::iow" +Create a new io watcher object in stopped state. +.ie n .IP "$iow = $iow\fR\->cb (sub { my ($iow, \f(CW$reventmask\fR) = \f(CW@_; ... })" 4 +.el .IP "$iow = \f(CW$iow\fR\->cb (sub { my ($iow, \f(CW$reventmask\fR) = \f(CW@_\fR; ... })" 4 +.IX Item "$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })" +Set the callback to be called when io events are triggered. \f(CW$reventmask\fR +is a bitset as described in the \f(CW\*(C`events\*(C'\fR method. +.ie n .IP "$iow = $iow\->fd ($fd)" 4 +.el .IP "$iow = \f(CW$iow\fR\->fd ($fd)" 4 +.IX Item "$iow = $iow->fd ($fd)" +Set the filedescriptor (not handle) to watch. +.ie n .IP "$iow = $iow\->events ($eventmask)" 4 +.el .IP "$iow = \f(CW$iow\fR\->events ($eventmask)" 4 +.IX Item "$iow = $iow->events ($eventmask)" +Set the event mask to watch. Bit #0 (value \f(CW1\fR) enables watching for read +data, Bit #1 (value \f(CW2\fR) enables watching for write data. +.ie n .IP "$iow = $iow\->start" 4 +.el .IP "$iow = \f(CW$iow\fR\->start" 4 +.IX Item "$iow = $iow->start" +Start watching for requested events on the given handle. +.ie n .IP "$iow = $iow\->stop" 4 +.el .IP "$iow = \f(CW$iow\fR\->stop" 4 +.IX Item "$iow = $iow->stop" +Stop watching for events on the given filehandle. +.SH "AUTHOR" +.IX Header "AUTHOR" +.Vb 2 +\& Marc Lehmann +\& http://software.schmorp.de/pkg/rxvt-unicode +.Ve diff --git a/src/Makefile.in b/src/Makefile.in index 497d4b38..8b87390a 100644 --- a/src/Makefile.in +++ b/src/Makefile.in @@ -94,7 +94,14 @@ cleandir: realclean distclean: realclean (cd $(srcdir); $(RMF) Makefile) -install: allbin alldoc +install-perl: +@IF_PERL@ $(MKDIR) $(DESTDIR)$(libdir) +@IF_PERL@ $(MKDIR) $(DESTDIR)$(libdir)/urxvt +@IF_PERL@ $(MKDIR) $(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 + +install: allbin alldoc install-perl $(MKDIR) $(DESTDIR)$(bindir) $(RMF) $(RXVT_BINNAME) $(RMF) $(RXVTC_BINNAME) diff --git a/src/urxvt.pm b/src/urxvt.pm index 826f13e2..de147b35 100644 --- a/src/urxvt.pm +++ b/src/urxvt.pm @@ -1,19 +1,20 @@ =head1 NAME -urxvt - rxvt-unicode's embedded perl interpreter +rxvtperl - rxvt-unicode's embedded perl interpreter =head1 SYNOPSIS -Put your scripts into $LIBDIR/perl-init/, they will be loaded automatically. +* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically. -Each script will only be loaded once, even in urxvtd, and will be valid +* 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 written in utf-8. +* 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