ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.1 by root, Mon Jan 2 15:35:43 2006 UTC vs.
Revision 1.7 by root, Mon Jan 2 19:05:05 2006 UTC

1=head1 NAME 1=head1 NAME
2 2
3urxvt - rxvt-unicode's embedded perl interpreter 3rxvtperl - rxvt-unicode's embedded perl interpreter
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7Put your scripts into $LIBDIR/perl-init/, they will be loaded automatically. 7* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically.
8 8
9Each script will only be loaded once, even in urxvtd, and will be valid
10globally.
11
12Scripts are evaluated in a 'use strict' and 'use utf8' environment, and 9* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
13thus must be written in utf-8. 10thus must be encoded as UTF-8.
14 11
15 sub on_sel_grab { 12 sub on_sel_grab {
16 warn "you selected ", $_[0]->selection; 13 warn "you selected ", $_[0]->selection;
14 ()
17 } 15 }
18 16
19 1 17 1
20 18
21=head1 DESCRIPTION 19=head1 DESCRIPTION
20
21On startup, @@RXVT_NAME@@ will scan F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>
22for files and will load them. Everytime a terminal object gets created,
23the directory specified by the C<perl-lib> resource will be additionally
24scanned.
25
26Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
27scripts will be shared for all terminals.
28
29Hooks in scripts specified by C<perl-lib> will only be called for the
30terminals created with that specific option value.
31
32=head2 General API Considerations
33
34All objects (such as terminals, time watchers etc.) are typical
35reference-to-hash objects. The hash can be used to store anything you
36like. All members starting with an underscore (such as C<_ptr> or
37C<_hook>) are reserved for internal uses and must not be accessed or
38modified).
39
40When objects are destroyed on the C++ side, the perl object hashes are
41emptied, so its best to store related objects such as time watchers and
42the like inside the terminal object so they get destroyed as soon as the
43terminal is destroyed.
22 44
23=head2 Hooks 45=head2 Hooks
24 46
25The following subroutines can be declared in loaded scripts, and will be called 47The following subroutines can be declared in loaded scripts, and will be called
26whenever the relevant event happens. 48whenever the relevant event happens.
… …
119costs! The only time this is acceptable is when the terminal process 141costs! The only time this is acceptable is when the terminal process
120starts up. 142starts up.
121 143
122=item urxvt::warn $string 144=item urxvt::warn $string
123 145
124Calls C<rxvt_warn> witht eh given string which should not include a 146Calls C<rxvt_warn> with the given string which should not include a
125newline. The module also overwrites the C<warn> builtin with a function 147newline. The module also overwrites the C<warn> builtin with a function
126that calls this function. 148that calls this function.
127 149
128Using this function has the advantage that its output ends up in the 150Using this function has the advantage that its output ends up in the
129correct place, e.g. on stderr of the connecting urxvtc client. 151correct place, e.g. on stderr of the connecting urxvtc client.
130
131=item $cellwidth = urxvt::wcswidth $string
132
133Returns the number of screen-cells this string would need. Correctly
134accounts for wide and combining characters.
135 152
136=item $time = urxvt::NOW 153=item $time = urxvt::NOW
137 154
138Returns the "current time" (as per the event loop). 155Returns the "current time" (as per the event loop).
139 156
… …
157 unless $msg =~ /\n$/; 174 unless $msg =~ /\n$/;
158 urxvt::warn ($msg); 175 urxvt::warn ($msg);
159 }; 176 };
160} 177}
161 178
162my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10; 179my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
163 180
164sub verbose { 181sub verbose {
165 my ($level, $msg) = @_; 182 my ($level, $msg) = @_;
166 warn "$msg\n"; #d# 183 warn "$msg\n" if $level < $verbosity;
167} 184}
168 185
169my @invoke_cb; 186my %hook_global;
187my @hook_count;
170 188
171# called by the rxvt core 189# called by the rxvt core
172sub invoke { 190sub invoke {
173 local $term = shift; 191 local $term = shift;
174 my $htype = shift; 192 my $htype = shift;
175 193
176 my $cb = $invoke_cb[$htype];
177
178 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 194 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
179 if $verbosity >= 10; 195 if $verbosity >= 10;
180 196
197 for my $cb ($hook_global{_hook}[$htype], $term->{_hook}[$htype]) {
198 $cb or next;
199
181 while (my ($k, $v) = each %$cb) { 200 while (my ($k, $v) = each %$cb) {
182 return 1 if $v->($term, @_); 201 return 1 if $v->($term, @_);
202 }
183 } 203 }
184 204
185 0 205 0
186} 206}
187 207
188# find on_xxx subs in the package and register them 208# find on_xxx subs in the package and register them
189# as hooks 209# as hooks
190sub register_package($) { 210sub register_package($) {
191 my ($pkg) = @_; 211 my ($pkg) = @_;
192 212
193 for my $hook (0.. $#HOOKNAME) { 213 for my $htype (0.. $#HOOKNAME) {
194 my $name = $HOOKNAME[$hook]; 214 my $name = $HOOKNAME[$htype];
195 215
196 my $ref = $pkg->can ("on_" . lc $name) 216 my $ref = $pkg->can ("on_" . lc $name)
197 or next; 217 or next;
198 218
199 $invoke_cb[$hook]{$ref*1} = $ref; 219 $term->{_hook}[$htype]{$ref*1} = $ref;
220 $hook_count[$htype]++
200 set_should_invoke $hook, 1; 221 or set_should_invoke $htype, 1;
201 } 222 }
202} 223}
203 224
204my $script_pkg = "script0000"; 225my $script_pkg = "script0000";
205my %script_pkg; 226my %script_pkg;
206 227
207# load a single script into its own package, once only 228# load a single script into its own package, once only
208sub load_script($) { 229sub script_package($) {
209 my ($path) = @_; 230 my ($path) = @_;
210 231
211 $script_pkg{$path} ||= do { 232 $script_pkg{$path} ||= do {
212 my $pkg = $script_pkg++; 233 my $pkg = $script_pkg++;
213 verbose 3, "loading script '$path' into package '$pkg'"; 234 verbose 3, "loading script '$path' into package '$pkg'";
… …
218 eval "package $pkg; use strict; use utf8;\n" 239 eval "package $pkg; use strict; use utf8;\n"
219 . "#line 1 \"$path\"\n" 240 . "#line 1 \"$path\"\n"
220 . do { local $/; <$fh> } 241 . do { local $/; <$fh> }
221 or die "$path: $@"; 242 or die "$path: $@";
222 243
223 register_package $pkg;
224
225 $pkg 244 $pkg
226 }; 245 }
227} 246}
228 247
229load_script $_ for grep -f $_, <$LIBDIR/perl-init/*>; 248sub load_scripts($) {
249 my ($dir) = @_;
230 250
251 verbose 3, "loading scripts from '$dir'";
252
253 register_package script_package $_
254 for grep -f $_,
255 <$dir/*>;
256}
257
258sub on_init {
259 my ($term) = @_;
260
261 my $libdir = $term->resource ("perl_lib");
262
263 load_scripts $libdir
264 if defined $libdir;
265}
266
267sub on_destroy {
268 my ($term) = @_;
269
270 my $hook = $term->{_hook}
271 or return;
272
273 for my $htype (0..$#$hook) {
274 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
275 or set_should_invoke $htype, 0;
276 }
277}
278
279{
280 local $term = \%hook_global;
281
282 register_package __PACKAGE__;
283 load_scripts "$LIBDIR/perl-ext";
284}
231 285
232=back 286=back
233 287
234=head2 The C<urxvt::term> Class 288=head2 The C<urxvt::term> Class
235 289
236=over 4 290=over 4
291
292=item $value = $term->resource ($name[, $newval])
293
294Returns the current resource value associated with a given name and
295optionally sets a new value. Setting values is most useful in the C<init>
296hook. Unset resources are returned and accepted as C<undef>.
297
298The new value must be properly encoded to a suitable character encoding
299before passing it to this method. Similarly, the returned value may need
300to be converted from the used encoding to text.
301
302Resource names are as defined in F<src/rsinc.h>. Colours can be specified
303as resource names of the form C<< color+<index> >>, e.g. C<color+5>. (will
304likely change).
305
306Please note that resource strings will currently only be freed when the
307terminal is destroyed, so changing options frequently will eat memory.
308
309Here is a a likely non-exhaustive list of resource names, not all of which
310are supported in every build, please see the source to see the actual
311list:
312
313 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
314 borderLess color cursorBlink cursorUnderline cutchars delete_key
315 display_name embed ext_bwidth fade font geometry hold iconName
316 imFont imLocale inputMethod insecure int_bwidth intensityStyles
317 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8
318 modifier mouseWheelScrollPage name pastableTabs path perl perl_eval
319 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
320 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
321 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
322 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
323 shade term_name title transparent transparent_all tripleclickwords
324 utmpInhibit visualBell
325
326=cut
327
328sub urxvt::term::resource($$;$) {
329 my ($self, $name) = (shift, shift);
330 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
331 goto &urxvt::term::_resource;
332}
237 333
238=item ($row, $col) = $term->selection_mark ([$row, $col]) 334=item ($row, $col) = $term->selection_mark ([$row, $col])
239 335
240=item ($row, $col) = $term->selection_beg ([$row, $col]) 336=item ($row, $col) = $term->selection_beg ([$row, $col])
241 337
… …
263 my ($self, $x, $y, $text) = @_; 359 my ($self, $x, $y, $text) = @_;
264 360
265 my @lines = split /\n/, $text; 361 my @lines = split /\n/, $text;
266 362
267 my $w = 0; 363 my $w = 0;
268 for (map urxvt::wcswidth $_, @lines) { 364 for (map $self->strwidth ($_), @lines) {
269 $w = $_ if $w < $_; 365 $w = $_ if $w < $_;
270 } 366 }
271 367
272 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 368 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
273 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 369 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
… …
290position. 386position.
291 387
292=item $term->scr_overlay_set ($x, $y, $text) 388=item $term->scr_overlay_set ($x, $y, $text)
293 389
294Write a string at the given position into the overlay. 390Write a string at the given position into the overlay.
391
392=item $cellwidth = $term->strwidth $string
393
394Returns the number of screen-cells this string would need. Correctly
395accounts for wide and combining characters.
396
397=item $octets = $term->locale_encode $string
398
399Convert the given text string into the corresponding locale encoding.
400
401=item $string = $term->locale_decode $octets
402
403Convert the given locale-encoded octets into a perl string.
404
405=item $term->tt_write ($octets)
406
407Write the octets given in C<$data> to the tty (i.e. as program input). To
408pass characters instead of octets, you should convetr you strings first to
409the locale-specific encoding using C<< $term->locale_encode >>.
295 410
296=back 411=back
297 412
298=head2 The C<urxvt::timer> Class 413=head2 The C<urxvt::timer> Class
299 414
… …
390 505
391Stop watching for events on the given filehandle. 506Stop watching for events on the given filehandle.
392 507
393=back 508=back
394 509
510=head1 ENVIRONMENT
511
512=head2 URXVT_PERL_VERBOSITY
513
514This variable controls the verbosity level of the perl extension. Higher
515numbers indicate more verbose output.
516
517=over 4
518
519=item 0 - only fatal messages
520
521=item 3 - script loading and management
522
523=item 10 - all events received
524
525=back
526
395=head1 AUTHOR 527=head1 AUTHOR
396 528
397 Marc Lehmann <pcg@goof.com> 529 Marc Lehmann <pcg@goof.com>
398 http://software.schmorp.de/pkg/rxvt-unicode 530 http://software.schmorp.de/pkg/rxvt-unicode
399 531

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines