rxvt-unicode/src/urxvt.pm

=encoding utf8

=head1 NAME

@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter

=head1 SYNOPSIS

   # create a file grab_test in $HOME:

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

   # start a @@RXVT_NAME@@ using it:

   @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test

=head1 DESCRIPTION

Everytime a terminal object gets created, scripts specified via the
C<perl> resource are loaded and associated with it.

Scripts are compiled in a 'use strict' and 'use utf8' environment, and
thus must be encoded as UTF-8.

Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
scripts will be shared (but not enabled) for all terminals.

=head2 Prepackaged Extensions

This section describes the extensiosn delivered with this version. You can
find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.

You can activate them like this:

  @@RXVT_NAME@@ -pe <extensionname>

=over 4

=item selection

Miscellaneous selection modifications.

=over 4

=item rot13

Rot-13 the selection when activated. Used via keyboard trigger:

   URxvt.keysym.C-M-r: perl:selection:rot13

=back

=item digital-clock

Displays a very simple digital clock in the upper right corner of the
window. Illustrates overwriting the refresh callbacks to create your own
overlays or changes.

=item simple-overlay-clock

Displays a digital clock using the built-in overlay (colorful, useless).

=back

=head2 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 C<_ptr> or
C<_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.

=head2 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 I<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 C<()>).

=over 4

=item on_init $term

Called after a new terminal object has been initialized, but before
windows are created or the command gets run.

=item 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.

=item on_start $term

Called at the very end of initialisation of a new terminal, just before
returning to the mainloop.

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

Returning a true value aborts selection making by urxvt, in which case you
have to make a selection yourself by calling C<< $term->selection_grab >>.

=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 C<< $term->selection >>.

Returning a true value aborts selection grabbing. It will still be hilighted.

=item on_focus_in $term

Called whenever the window gets the keyboard focus, before urxvt does
focus in processing.

=item on_focus_out $term

Called wheneever the window loses keyboard focus, before urxvt does focus
out processing.

=item on_view_change $term, $offset

Called whenever the view offset changes, i..e the user or program
scrolls. Offset C<0> means display the normal terminal, positive values
show this many lines of scrollback.

=item on_scroll_back $term, $lines, $saved

Called whenever lines scroll out of the terminal area into the scrollback
buffer. C<$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). C<$saved> is the total
number of lines that will be in the scrollback buffer.

=item on_tty_activity $term *NYI*

Called whenever the program(s) running in the urxvt window send output.

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

=item on_refresh_end $term

Called just after the screen gets redrawn. See C<on_refresh_begin>.

=item on_keyboard_command $term, $string

Called whenever the user presses a key combination that has a
C<perl:string> action bound to it (see description of the B<keysym>
resource in the @@RXVT_NAME@@(1) manpage).

=back

=head2 Functions in the C<urxvt> Package

=over 4

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

=item urxvt::warn $string

Calls C<rxvt_warn> with the given string which should not include a
newline. The module also overwrites the C<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.

=item $time = urxvt::NOW

Returns the "current time" (as per the event loop).

=cut

package urxvt;

use strict;

our $term;
our @HOOKNAME;
our $LIBDIR;

BEGIN {
   urxvt->bootstrap;

   # overwrite perl's warn
   *CORE::GLOBAL::warn = sub {
      my $msg = join "", @_;
      $msg .= "\n"
         unless $msg =~ /\n$/;
      urxvt::warn ($msg);
   };
}

my @hook_count;
my $verbosity = $ENV{URXVT_PERL_VERBOSITY};

sub verbose {
   my ($level, $msg) = @_;
   warn "$msg\n" if $level <= $verbosity;
}

# find on_xxx subs in the package and register them
# as hooks
sub register_package($) {
   my ($pkg) = @_;

   for my $htype (0.. $#HOOKNAME) {
      my $name = $HOOKNAME[$htype];

      my $ref = $pkg->can ("on_" . lc $name)
         or next;

      $term->{_hook}[$htype]{$ref*1} = $ref;
      $hook_count[$htype]++
         or set_should_invoke $htype, 1;
   }
}

my $script_pkg = "script0000";
my %script_pkg;

# load a single script into its own package, once only
sub script_package($) {
   my ($path) = @_;

   $script_pkg{$path} ||= do {
      my $pkg = "urxvt::" . ($script_pkg++);

      verbose 3, "loading script '$path' into package '$pkg'";

      open my $fh, "<:raw", $path
         or die "$path: $!";

      my $source = "package $pkg; use strict; use utf8;\n"
                   . "#line 1 \"$path\"\n{\n"
                   . (do { local $/; <$fh> })
                   . "\n};\n1";

      eval $source or die "$path: $@";

      $pkg
   }
}

# called by the rxvt core
sub invoke {
   local $term = shift;
   my $htype = shift;

   if ($htype == 0) { # INIT
      my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");

      for my $ext (split /:/, $term->resource ("perl_ext")) {
         my @files = grep -f $_, map "$_/$ext", @dirs;

         if (@files) {
            register_package script_package $files[0];
         } else {
            warn "perl extension '$ext' not found in perl library search path\n";
         }
      }

   } elsif ($htype == 1) { # DESTROY
      if (my $hook = $term->{_hook}) {
         for my $htype (0..$#$hook) {
            $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
               or set_should_invoke $htype, 0;
         }
      }
   }

   my $cb = $term->{_hook}[$htype]
      or return;

   verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
      if $verbosity >= 10;

   while (my ($k, $v) = each %$cb) {
      return 1 if $v->($term, @_);
   }

   0
}

=back

=head2 The C<urxvt::term> Class

=over 4

=item $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 C<init>
hook. Unset resources are returned and accepted as C<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 F<src/rsinc.h>. Colours can be specified
as resource names of the form C<< color+<index> >>, e.g. C<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_eval perl_ext
  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

=cut

sub urxvt::term::resource($$;$) {
   my ($self, $name) = (shift, shift);
   unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
   goto &urxvt::term::_resource;
}

=item ($row, $col) = $term->selection_mark ([$row, $col])

=item ($row, $col) = $term->selection_beg ([$row, $col])

=item ($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.

=item $success = $term->selection_grab ($eventtime)

Try to request the primary selection from the server (for example, as set
by the next method).

=item $oldtext = $term->selection ([$newtext])

Return the current selection text and optionally replace it by C<$newtext>.

=item $term->scr_overlay ($x, $y, $text)

Create a simple multi-line overlay box. See the next method for details.

=cut

sub urxvt::term::scr_overlay {
   my ($self, $x, $y, $text) = @_;

   my @lines = split /\n/, $text;

   my $w = 0;
   for (map $self->strwidth ($_), @lines) {
      $w = $_ if $w < $_;
   }

   $self->scr_overlay_new ($x, $y, $w, scalar @lines);
   $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
}

=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 C<$x> or
C<$y> is negative, then this is counted from the right/bottom side,
respectively.

=item $term->scr_overlay_off

Switch the overlay off again.

=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)

Put a single character (specified numerically) at the given overlay
position.

=item $term->scr_overlay_set ($x, $y, $text)

Write a string at the given position into the overlay.

=item $cellwidth = $term->strwidth $string

Returns the number of screen-cells this string would need. Correctly
accounts for wide and combining characters.

=item $octets = $term->locale_encode $string

Convert the given text string into the corresponding locale encoding.

=item $string = $term->locale_decode $octets

Convert the given locale-encoded octets into a perl string.

=item $term->tt_write ($octets)

Write the octets given in C<$data> to the tty (i.e. as program input). To
pass characters instead of octets, you should convert your strings first
to the locale-specific encoding using C<< $term->locale_encode >>.

=item $nrow = $term->nrow

=item $ncol = $term->ncol

Return the number of rows/columns of the terminal window (i.e. as
specified by C<-geometry>, excluding any scrollback).

=item $nsaved = $term->nsaved

Returns the number of lines in the scrollback buffer.

=item $view_start = $term->view_start ([$newvalue])

Returns the negative row number of the topmost line. Minimum value is
C<0>, which displays the normal terminal contents. Larger values scroll
this many lines into the scrollback buffer.

=item $term->want_refresh

Requests a screen refresh. At the next opportunity, rxvt-unicode will
compare the on-screen display with its stored representation. If they
differ, it redraws the differences.

Used after changing terminal contents to display them.

=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])

Returns the text of the entire row with number C<$row_number>. Row C<0>
is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
terminal line. The scrollback buffer starts at line C<-1> and extends to
line C<< -$term->nsaved >>.

If C<$new_text> is specified, it will replace characters in the current
line, starting at column C<$start_col> (default C<0>), which is useful
to replace only parts of a line. The font iindex in the rendition will
automatically be updated.

C<$text> is in a special encoding: tabs and wide characters that use more
than one cell when displayed are padded with urxvt::NOCHAR characters
(C<chr 65535>). Characters with combining characters and other characters
that do not fit into the normal tetx encoding will be replaced with
characters in the private use area.

You have to obey this encoding when changing text. The advantage is
that C<substr> and similar functions work on screen cells and not on
characters.

The methods C<< $term->special_encode >> and C<< $term->special_decode >>
can be used to convert normal strings into this encoding and vice versa.

=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])

Like C<< $term->ROW_t >>, but returns an arrayref with rendition
bitsets. Rendition bitsets contain information about colour, font, font
styles and similar information. See also C<< $term->ROW_t >>.

When setting rendition, the font mask will be ignored.

See the section on RENDITION, below.

=item $length = $term->ROW_l ($row_number[, $new_length])

Returns the number of screen cells that are in use ("the line length"). If
it is C<-1>, then the line is part of a multiple-row logical "line", which
means all characters are in use and it is continued on the next row.

=item $text = $term->special_encode $string

Converts a perl string into the special encoding used by rxvt-unicode,
where one character corresponds to one screen cell. See
C<< $term->ROW_t >> for details.

=item $string = $term->special_decode $text

Converts rxvt-unicodes text reprsentation into a perl string. See
C<< $term->ROW_t >> for details.

=back

=head2 RENDITION

Rendition bitsets contain information about colour, font, font styles and
similar information for each screen cell.

The following "macros" deal with changes in rendition sets. You should
never just create a bitset, you should always modify an existing one,
as they contain important information required for correct operation of
rxvt-unicode.

=over 4

=item $rend = urxvt::DEFAULT_RSTYLE

Returns the default rendition, as used when the terminal is starting up or
being reset. Useful as a base

=back

=cut

=head2 The C<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);
                    });

=over 4

=item $timer = new urxvt::timer

Create a new timer object in stopped state.

=item $timer = $timer->cb (sub { my ($timer) = @_; ... })

Set the callback to be called when the timer triggers.

=item $tstamp = $timer->at

Return the time this watcher will fire next.

=item $timer = $timer->set ($tstamp)

Set the time the event is generated to $tstamp.

=item $timer = $timer->start

Start the timer.

=item $timer = $timer->start ($tstamp)

Set the event trigger time to C<$tstamp> and start the timer.

=item $timer = $timer->stop

Stop the timer.

=back

=head2 The C<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;
                 });


=over 4

=item $iow = new urxvt::iow

Create a new io watcher object in stopped state.

=item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })

Set the callback to be called when io events are triggered. C<$reventmask>
is a bitset as described in the C<events> method.

=item $iow = $iow->fd ($fd)

Set the filedescriptor (not handle) to watch.

=item $iow = $iow->events ($eventmask)

Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
data, Bit #1 (value C<2>) enables watching for write data.

=item $iow = $iow->start

Start watching for requested events on the given handle.

=item $iow = $iow->stop

Stop watching for events on the given filehandle.

=back

=head1 ENVIRONMENT

=head2 URXVT_PERL_VERBOSITY

This variable controls the verbosity level of the perl extension. Higher
numbers indicate more verbose output.

=over 4

=item 0 - only fatal messages

=item 3 - script loading and management

=item 10 - all events received

=back

=head1 AUTHOR

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

=cut

1
Revision:	1.17
Committed:	Tue Jan 3 01:45:03 2006 UTC (18 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.16:	+3 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.17	=encoding utf8
2
3	root	1.1	=head1 NAME
4
5	root	1.11	@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
6	root	1.1
7			=head1 SYNOPSIS
8
9	root	1.10	# create a file grab_test in $HOME:
10	root	1.1
11			sub on_sel_grab {
12			warn "you selected ", $_[0]->selection;
13	root	1.3	()
14	root	1.1	}
15
16	root	1.10	# start a @@RXVT_NAME@@ using it:
17
18			@@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19	root	1.1
20			=head1 DESCRIPTION
21
22	root	1.8	Everytime a terminal object gets created, scripts specified via the
23	root	1.10	C<perl> resource are loaded and associated with it.
24
25			Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26			thus must be encoded as UTF-8.
27	root	1.6
28			Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
29	root	1.16	scripts will be shared (but not enabled) for all terminals.
30	root	1.6
31	root	1.17	=head2 Prepackaged Extensions
32	root	1.15
33			This section describes the extensiosn delivered with this version. You can
34			find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35
36			You can activate them like this:
37
38			@@RXVT_NAME@@ -pe <extensionname>
39
40			=over 4
41
42			=item selection
43
44			Miscellaneous selection modifications.
45
46			=over 4
47
48			=item rot13
49
50			Rot-13 the selection when activated. Used via keyboard trigger:
51
52			URxvt.keysym.C-M-r: perl:selection:rot13
53
54			=back
55
56			=item digital-clock
57
58			Displays a very simple digital clock in the upper right corner of the
59			window. Illustrates overwriting the refresh callbacks to create your own
60			overlays or changes.
61
62			=item simple-overlay-clock
63
64			Displays a digital clock using the built-in overlay (colorful, useless).
65
66			=back
67
68	root	1.6	=head2 General API Considerations
69
70			All objects (such as terminals, time watchers etc.) are typical
71			reference-to-hash objects. The hash can be used to store anything you
72	root	1.7	like. All members starting with an underscore (such as C<_ptr> or
73			C<_hook>) are reserved for internal uses and must not be accessed or
74			modified).
75	root	1.6
76			When objects are destroyed on the C++ side, the perl object hashes are
77			emptied, so its best to store related objects such as time watchers and
78			the like inside the terminal object so they get destroyed as soon as the
79			terminal is destroyed.
80
81	root	1.1	=head2 Hooks
82
83			The following subroutines can be declared in loaded scripts, and will be called
84			whenever the relevant event happens.
85
86			All of them must return a boolean value. If it is true, then the event
87			counts as being I<consumed>, and the invocation of other hooks is skipped,
88			and the relevant action might not be carried out by the C++ code.
89
90			When in doubt, return a false value (preferably C<()>).
91
92			=over 4
93
94			=item on_init $term
95
96			Called after a new terminal object has been initialized, but before
97			windows are created or the command gets run.
98
99			=item on_reset $term
100
101			Called after the screen is "reset" for any reason, such as resizing or
102			control sequences. Here is where you can react on changes to size-related
103			variables.
104
105			=item on_start $term
106
107			Called at the very end of initialisation of a new terminal, just before
108			returning to the mainloop.
109
110			=item on_sel_make $term, $eventtime
111
112			Called whenever a selection has been made by the user, but before the
113			selection text is copied, so changes to the beginning, end or type of the
114			selection will be honored.
115
116			Returning a true value aborts selection making by urxvt, in which case you
117			have to make a selection yourself by calling C<< $term->selection_grab >>.
118
119			=item on_sel_grab $term, $eventtime
120
121			Called whenever a selection has been copied, but before the selection is
122			requested from the server. The selection text can be queried and changed
123			by calling C<< $term->selection >>.
124
125			Returning a true value aborts selection grabbing. It will still be hilighted.
126
127			=item on_focus_in $term
128
129			Called whenever the window gets the keyboard focus, before urxvt does
130			focus in processing.
131
132			=item on_focus_out $term
133
134			Called wheneever the window loses keyboard focus, before urxvt does focus
135			out processing.
136
137			=item on_view_change $term, $offset
138
139			Called whenever the view offset changes, i..e the user or program
140			scrolls. Offset C<0> means display the normal terminal, positive values
141			show this many lines of scrollback.
142
143			=item on_scroll_back $term, $lines, $saved
144
145			Called whenever lines scroll out of the terminal area into the scrollback
146			buffer. C<$lines> is the number of lines scrolled out and may be larger
147			than the scroll back buffer or the terminal.
148
149			It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
150			$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
151			number of lines that will be in the scrollback buffer.
152
153			=item on_tty_activity $term NYI
154
155			Called whenever the program(s) running in the urxvt window send output.
156
157			=item on_refresh_begin $term
158
159			Called just before the screen gets redrawn. Can be used for overlay
160			or similar effects by modify terminal contents in refresh_begin, and
161			restoring them in refresh_end. The built-in overlay and selection display
162			code is run after this hook, and takes precedence.
163
164			=item on_refresh_end $term
165
166			Called just after the screen gets redrawn. See C<on_refresh_begin>.
167
168	root	1.11	=item on_keyboard_command $term, $string
169
170			Called whenever the user presses a key combination that has a
171			C<perl:string> action bound to it (see description of the B<keysym>
172			resource in the @@RXVT_NAME@@(1) manpage).
173
174	root	1.1	=back
175
176			=head2 Functions in the C<urxvt> Package
177
178			=over 4
179
180			=item urxvt::fatal $errormessage
181
182			Fatally aborts execution with the given error message. Avoid at all
183			costs! The only time this is acceptable is when the terminal process
184			starts up.
185
186			=item urxvt::warn $string
187
188	root	1.6	Calls C<rxvt_warn> with the given string which should not include a
189	root	1.1	newline. The module also overwrites the C<warn> builtin with a function
190			that calls this function.
191
192			Using this function has the advantage that its output ends up in the
193			correct place, e.g. on stderr of the connecting urxvtc client.
194
195			=item $time = urxvt::NOW
196
197			Returns the "current time" (as per the event loop).
198
199			=cut
200
201			package urxvt;
202
203			use strict;
204
205			our $term;
206			our @HOOKNAME;
207			our $LIBDIR;
208
209			BEGIN {
210			urxvt->bootstrap;
211
212			# overwrite perl's warn
213			*CORE::GLOBAL::warn = sub {
214			my $msg = join "", @_;
215			$msg .= "\n"
216			unless $msg =~ /\n$/;
217			urxvt::warn ($msg);
218			};
219			}
220
221	root	1.8	my @hook_count;
222	root	1.7	my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
223	root	1.1
224			sub verbose {
225			my ($level, $msg) = @_;
226	root	1.8	warn "$msg\n" if $level <= $verbosity;
227	root	1.1	}
228
229			# find on_xxx subs in the package and register them
230			# as hooks
231			sub register_package($) {
232			my ($pkg) = @_;
233
234	root	1.7	for my $htype (0.. $#HOOKNAME) {
235			my $name = $HOOKNAME[$htype];
236	root	1.1
237			my $ref = $pkg->can ("on_" . lc $name)
238			or next;
239
240	root	1.7	$term->{_hook}[$htype]{$ref*1} = $ref;
241			$hook_count[$htype]++
242			or set_should_invoke $htype, 1;
243	root	1.1	}
244			}
245
246			my $script_pkg = "script0000";
247			my %script_pkg;
248
249			# load a single script into its own package, once only
250	root	1.7	sub script_package($) {
251	root	1.1	my ($path) = @_;
252
253			$script_pkg{$path} \|\|= do {
254	root	1.8	my $pkg = "urxvt::" . ($script_pkg++);
255
256	root	1.1	verbose 3, "loading script '$path' into package '$pkg'";
257
258			open my $fh, "<:raw", $path
259			or die "$path: $!";
260
261	root	1.8	my $source = "package $pkg; use strict; use utf8;\n"
262			. "#line 1 \"$path\"\n{\n"
263			. (do { local $/; <$fh> })
264			. "\n};\n1";
265
266			eval $source or die "$path: $@";
267	root	1.1
268			$pkg
269	root	1.7	}
270	root	1.1	}
271
272	root	1.8	# called by the rxvt core
273			sub invoke {
274			local $term = shift;
275			my $htype = shift;
276	root	1.6
277	root	1.8	if ($htype == 0) { # INIT
278	root	1.9	my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
279	root	1.6
280	root	1.8	for my $ext (split /:/, $term->resource ("perl_ext")) {
281			my @files = grep -f $_, map "$_/$ext", @dirs;
282	root	1.6
283	root	1.8	if (@files) {
284			register_package script_package $files[0];
285			} else {
286			warn "perl extension '$ext' not found in perl library search path\n";
287			}
288			}
289	root	1.6
290	root	1.8	} elsif ($htype == 1) { # DESTROY
291			if (my $hook = $term->{_hook}) {
292			for my $htype (0..$#$hook) {
293			$hook_count[$htype] -= scalar keys %{ $hook->[$htype] \|\| {} }
294			or set_should_invoke $htype, 0;
295			}
296			}
297			}
298	root	1.6
299	root	1.8	my $cb = $term->{_hook}[$htype]
300			or return;
301	root	1.6
302	root	1.8	verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
303			if $verbosity >= 10;
304	root	1.7
305	root	1.8	while (my ($k, $v) = each %$cb) {
306			return 1 if $v->($term, @_);
307	root	1.7	}
308
309	root	1.8	0
310	root	1.7	}
311	root	1.1
312			=back
313
314			=head2 The C<urxvt::term> Class
315
316			=over 4
317
318	root	1.4	=item $value = $term->resource ($name[, $newval])
319
320			Returns the current resource value associated with a given name and
321			optionally sets a new value. Setting values is most useful in the C<init>
322			hook. Unset resources are returned and accepted as C<undef>.
323
324			The new value must be properly encoded to a suitable character encoding
325			before passing it to this method. Similarly, the returned value may need
326			to be converted from the used encoding to text.
327
328			Resource names are as defined in F<src/rsinc.h>. Colours can be specified
329			as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
330			likely change).
331
332			Please note that resource strings will currently only be freed when the
333			terminal is destroyed, so changing options frequently will eat memory.
334
335	root	1.5	Here is a a likely non-exhaustive list of resource names, not all of which
336			are supported in every build, please see the source to see the actual
337			list:
338
339			answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
340			borderLess color cursorBlink cursorUnderline cutchars delete_key
341			display_name embed ext_bwidth fade font geometry hold iconName
342			imFont imLocale inputMethod insecure int_bwidth intensityStyles
343	root	1.8	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
344			mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
345	root	1.6	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
346			reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
347			scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
348			scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
349			shade term_name title transparent transparent_all tripleclickwords
350			utmpInhibit visualBell
351	root	1.5
352	root	1.4	=cut
353
354			sub urxvt::term::resource($$;$) {
355			my ($self, $name) = (shift, shift);
356			unshift @_, $self, $name, ($name =~ s/\s\+\s(\d+)$// ? $1 : 0);
357			goto &urxvt::term::_resource;
358			}
359
360	root	1.1	=item ($row, $col) = $term->selection_mark ([$row, $col])
361
362			=item ($row, $col) = $term->selection_beg ([$row, $col])
363
364			=item ($row, $col) = $term->selection_end ([$row, $col])
365
366			Return the current values of the selection mark, begin or end positions,
367			and optionally set them to new values.
368
369			=item $success = $term->selection_grab ($eventtime)
370
371			Try to request the primary selection from the server (for example, as set
372			by the next method).
373
374			=item $oldtext = $term->selection ([$newtext])
375
376			Return the current selection text and optionally replace it by C<$newtext>.
377
378			=item $term->scr_overlay ($x, $y, $text)
379
380			Create a simple multi-line overlay box. See the next method for details.
381
382			=cut
383
384			sub urxvt::term::scr_overlay {
385			my ($self, $x, $y, $text) = @_;
386
387			my @lines = split /\n/, $text;
388
389			my $w = 0;
390	root	1.6	for (map $self->strwidth ($_), @lines) {
391	root	1.1	$w = $_ if $w < $_;
392			}
393
394			$self->scr_overlay_new ($x, $y, $w, scalar @lines);
395			$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
396			}
397
398			=item $term->scr_overlay_new ($x, $y, $width, $height)
399
400			Create a new (empty) overlay at the given position with the given
401			width/height. A border will be put around the box. If either C<$x> or
402			C<$y> is negative, then this is counted from the right/bottom side,
403			respectively.
404
405			=item $term->scr_overlay_off
406
407			Switch the overlay off again.
408
409			=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
410
411			Put a single character (specified numerically) at the given overlay
412			position.
413
414			=item $term->scr_overlay_set ($x, $y, $text)
415
416			Write a string at the given position into the overlay.
417
418	root	1.6	=item $cellwidth = $term->strwidth $string
419
420			Returns the number of screen-cells this string would need. Correctly
421			accounts for wide and combining characters.
422
423			=item $octets = $term->locale_encode $string
424
425			Convert the given text string into the corresponding locale encoding.
426
427			=item $string = $term->locale_decode $octets
428
429			Convert the given locale-encoded octets into a perl string.
430
431			=item $term->tt_write ($octets)
432
433			Write the octets given in C<$data> to the tty (i.e. as program input). To
434	root	1.12	pass characters instead of octets, you should convert your strings first
435			to the locale-specific encoding using C<< $term->locale_encode >>.
436
437	root	1.13	=item $nrow = $term->nrow
438
439			=item $ncol = $term->ncol
440
441			Return the number of rows/columns of the terminal window (i.e. as
442			specified by C<-geometry>, excluding any scrollback).
443
444	root	1.12	=item $nsaved = $term->nsaved
445
446			Returns the number of lines in the scrollback buffer.
447
448			=item $view_start = $term->view_start ([$newvalue])
449
450			Returns the negative row number of the topmost line. Minimum value is
451			C<0>, which displays the normal terminal contents. Larger values scroll
452			this many lines into the scrollback buffer.
453
454	root	1.14	=item $term->want_refresh
455
456			Requests a screen refresh. At the next opportunity, rxvt-unicode will
457			compare the on-screen display with its stored representation. If they
458			differ, it redraws the differences.
459
460			Used after changing terminal contents to display them.
461
462	root	1.13	=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
463	root	1.12
464			Returns the text of the entire row with number C<$row_number>. Row C<0>
465			is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
466			terminal line. The scrollback buffer starts at line C<-1> and extends to
467			line C<< -$term->nsaved >>.
468
469	root	1.13	If C<$new_text> is specified, it will replace characters in the current
470			line, starting at column C<$start_col> (default C<0>), which is useful
471			to replace only parts of a line. The font iindex in the rendition will
472			automatically be updated.
473	root	1.12
474			C<$text> is in a special encoding: tabs and wide characters that use more
475			than one cell when displayed are padded with urxvt::NOCHAR characters
476			(C<chr 65535>). Characters with combining characters and other characters
477			that do not fit into the normal tetx encoding will be replaced with
478			characters in the private use area.
479
480			You have to obey this encoding when changing text. The advantage is
481			that C<substr> and similar functions work on screen cells and not on
482			characters.
483
484			The methods C<< $term->special_encode >> and C<< $term->special_decode >>
485			can be used to convert normal strings into this encoding and vice versa.
486
487	root	1.13	=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
488
489			Like C<< $term->ROW_t >>, but returns an arrayref with rendition
490			bitsets. Rendition bitsets contain information about colour, font, font
491			styles and similar information. See also C<< $term->ROW_t >>.
492
493			When setting rendition, the font mask will be ignored.
494	root	1.12
495	root	1.13	See the section on RENDITION, below.
496
497			=item $length = $term->ROW_l ($row_number[, $new_length])
498
499			Returns the number of screen cells that are in use ("the line length"). If
500			it is C<-1>, then the line is part of a multiple-row logical "line", which
501			means all characters are in use and it is continued on the next row.
502	root	1.12
503			=item $text = $term->special_encode $string
504
505			Converts a perl string into the special encoding used by rxvt-unicode,
506			where one character corresponds to one screen cell. See
507			C<< $term->ROW_t >> for details.
508
509			=item $string = $term->special_decode $text
510
511			Converts rxvt-unicodes text reprsentation into a perl string. See
512			C<< $term->ROW_t >> for details.
513	root	1.6
514	root	1.1	=back
515
516	root	1.13	=head2 RENDITION
517
518			Rendition bitsets contain information about colour, font, font styles and
519			similar information for each screen cell.
520
521			The following "macros" deal with changes in rendition sets. You should
522			never just create a bitset, you should always modify an existing one,
523			as they contain important information required for correct operation of
524			rxvt-unicode.
525
526			=over 4
527
528			=item $rend = urxvt::DEFAULT_RSTYLE
529
530			Returns the default rendition, as used when the terminal is starting up or
531			being reset. Useful as a base
532
533			=back
534
535			=cut
536
537	root	1.1	=head2 The C<urxvt::timer> Class
538
539			This class implements timer watchers/events. Time is represented as a
540			fractional number of seconds since the epoch. Example:
541
542			# create a digital clock display in upper right corner
543			$term->{timer} = urxvt::timer
544			->new
545			->start (urxvt::NOW)
546			->cb (sub {
547			my ($timer) = @_;
548			my $time = $timer->at;
549			$timer->start ($time + 1);
550			$self->scr_overlay (-1, 0,
551			POSIX::strftime "%H:%M:%S", localtime $time);
552			});
553
554			=over 4
555
556			=item $timer = new urxvt::timer
557
558			Create a new timer object in stopped state.
559
560			=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
561
562			Set the callback to be called when the timer triggers.
563
564			=item $tstamp = $timer->at
565
566			Return the time this watcher will fire next.
567
568			=item $timer = $timer->set ($tstamp)
569
570			Set the time the event is generated to $tstamp.
571
572			=item $timer = $timer->start
573
574			Start the timer.
575
576			=item $timer = $timer->start ($tstamp)
577
578			Set the event trigger time to C<$tstamp> and start the timer.
579
580			=item $timer = $timer->stop
581
582			Stop the timer.
583
584			=back
585
586			=head2 The C<urxvt::iow> Class
587
588			This class implements io watchers/events. Example:
589
590			$term->{socket} = ...
591			$term->{iow} = urxvt::iow
592			->new
593			->fd (fileno $term->{socket})
594			->events (1) # wait for read data
595			->start
596			->cb (sub {
597			my ($iow, $revents) = @_;
598			# $revents must be 1 here, no need to check
599			sysread $term->{socket}, my $buf, 8192
600			or end-of-file;
601			});
602
603
604			=over 4
605
606			=item $iow = new urxvt::iow
607
608			Create a new io watcher object in stopped state.
609
610			=item $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
611
612			Set the callback to be called when io events are triggered. C<$reventmask>
613			is a bitset as described in the C<events> method.
614
615			=item $iow = $iow->fd ($fd)
616
617			Set the filedescriptor (not handle) to watch.
618
619			=item $iow = $iow->events ($eventmask)
620
621			Set the event mask to watch. Bit #0 (value C<1>) enables watching for read
622			data, Bit #1 (value C<2>) enables watching for write data.
623
624			=item $iow = $iow->start
625
626			Start watching for requested events on the given handle.
627
628			=item $iow = $iow->stop
629
630			Stop watching for events on the given filehandle.
631
632			=back
633
634	root	1.4	=head1 ENVIRONMENT
635
636			=head2 URXVT_PERL_VERBOSITY
637
638			This variable controls the verbosity level of the perl extension. Higher
639			numbers indicate more verbose output.
640
641			=over 4
642
643			=item 0 - only fatal messages
644
645			=item 3 - script loading and management
646
647			=item 10 - all events received
648
649			=back
650
651	root	1.1	=head1 AUTHOR
652
653			Marc Lehmann <pcg@goof.com>
654			http://software.schmorp.de/pkg/rxvt-unicode
655
656			=cut
657
658			1