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.3 by root, Mon Jan 2 15:59:25 2006 UTC vs.
Revision 1.7 by root, Mon Jan 2 19:05:05 2006 UTC

… …
3rxvtperl - rxvt-unicode's embedded perl interpreter 3rxvtperl - rxvt-unicode's embedded perl interpreter
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically. 7* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically.
8
9* Each script will only be loaded once, even in urxvtd, and will be valid
10globally.
11 8
12* Scripts 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 encoded as UTF-8. 10thus must be encoded as UTF-8.
14 11
15 sub on_sel_grab { 12 sub on_sel_grab {
… …
19 16
20 1 17 1
21 18
22=head1 DESCRIPTION 19=head1 DESCRIPTION
23 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.
44
24=head2 Hooks 45=head2 Hooks
25 46
26The 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
27whenever the relevant event happens. 48whenever the relevant event happens.
28 49
… …
120costs! The only time this is acceptable is when the terminal process 141costs! The only time this is acceptable is when the terminal process
121starts up. 142starts up.
122 143
123=item urxvt::warn $string 144=item urxvt::warn $string
124 145
125Calls 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
126newline. The module also overwrites the C<warn> builtin with a function 147newline. The module also overwrites the C<warn> builtin with a function
127that calls this function. 148that calls this function.
128 149
129Using 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
130correct place, e.g. on stderr of the connecting urxvtc client. 151correct place, e.g. on stderr of the connecting urxvtc client.
131
132=item $cellwidth = urxvt::wcswidth $string
133
134Returns the number of screen-cells this string would need. Correctly
135accounts for wide and combining characters.
136 152
137=item $time = urxvt::NOW 153=item $time = urxvt::NOW
138 154
139Returns the "current time" (as per the event loop). 155Returns the "current time" (as per the event loop).
140 156
… …
158 unless $msg =~ /\n$/; 174 unless $msg =~ /\n$/;
159 urxvt::warn ($msg); 175 urxvt::warn ($msg);
160 }; 176 };
161} 177}
162 178
163my $verbosity = $ENV{URXVT_PERL_VERBOSITY} || 10; 179my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
164 180
165sub verbose { 181sub verbose {
166 my ($level, $msg) = @_; 182 my ($level, $msg) = @_;
167 warn "$msg\n"; #d# 183 warn "$msg\n" if $level < $verbosity;
168} 184}
169 185
170my @invoke_cb; 186my %hook_global;
187my @hook_count;
171 188
172# called by the rxvt core 189# called by the rxvt core
173sub invoke { 190sub invoke {
174 local $term = shift; 191 local $term = shift;
175 my $htype = shift; 192 my $htype = shift;
176 193
177 my $cb = $invoke_cb[$htype];
178
179 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 194 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
180 if $verbosity >= 10; 195 if $verbosity >= 10;
181 196
197 for my $cb ($hook_global{_hook}[$htype], $term->{_hook}[$htype]) {
198 $cb or next;
199
182 while (my ($k, $v) = each %$cb) { 200 while (my ($k, $v) = each %$cb) {
183 return 1 if $v->($term, @_); 201 return 1 if $v->($term, @_);
202 }
184 } 203 }
185 204
186 0 205 0
187} 206}
188 207
189# find on_xxx subs in the package and register them 208# find on_xxx subs in the package and register them
190# as hooks 209# as hooks
191sub register_package($) { 210sub register_package($) {
192 my ($pkg) = @_; 211 my ($pkg) = @_;
193 212
194 for my $hook (0.. $#HOOKNAME) { 213 for my $htype (0.. $#HOOKNAME) {
195 my $name = $HOOKNAME[$hook]; 214 my $name = $HOOKNAME[$htype];
196 215
197 my $ref = $pkg->can ("on_" . lc $name) 216 my $ref = $pkg->can ("on_" . lc $name)
198 or next; 217 or next;
199 218
200 $invoke_cb[$hook]{$ref*1} = $ref; 219 $term->{_hook}[$htype]{$ref*1} = $ref;
220 $hook_count[$htype]++
201 set_should_invoke $hook, 1; 221 or set_should_invoke $htype, 1;
202 } 222 }
203} 223}
204 224
205my $script_pkg = "script0000"; 225my $script_pkg = "script0000";
206my %script_pkg; 226my %script_pkg;
207 227
208# load a single script into its own package, once only 228# load a single script into its own package, once only
209sub load_script($) { 229sub script_package($) {
210 my ($path) = @_; 230 my ($path) = @_;
211 231
212 $script_pkg{$path} ||= do { 232 $script_pkg{$path} ||= do {
213 my $pkg = $script_pkg++; 233 my $pkg = $script_pkg++;
214 verbose 3, "loading script '$path' into package '$pkg'"; 234 verbose 3, "loading script '$path' into package '$pkg'";
… …
219 eval "package $pkg; use strict; use utf8;\n" 239 eval "package $pkg; use strict; use utf8;\n"
220 . "#line 1 \"$path\"\n" 240 . "#line 1 \"$path\"\n"
221 . do { local $/; <$fh> } 241 . do { local $/; <$fh> }
222 or die "$path: $@"; 242 or die "$path: $@";
223 243
224 register_package $pkg;
225
226 $pkg 244 $pkg
227 }; 245 }
228} 246}
229 247
230load_script $_ for grep -f $_, <$LIBDIR/perl-ext/*>; 248sub load_scripts($) {
249 my ($dir) = @_;
231 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}
232 285
233=back 286=back
234 287
235=head2 The C<urxvt::term> Class 288=head2 The C<urxvt::term> Class
236 289
237=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}
238 333
239=item ($row, $col) = $term->selection_mark ([$row, $col]) 334=item ($row, $col) = $term->selection_mark ([$row, $col])
240 335
241=item ($row, $col) = $term->selection_beg ([$row, $col]) 336=item ($row, $col) = $term->selection_beg ([$row, $col])
242 337
… …
264 my ($self, $x, $y, $text) = @_; 359 my ($self, $x, $y, $text) = @_;
265 360
266 my @lines = split /\n/, $text; 361 my @lines = split /\n/, $text;
267 362
268 my $w = 0; 363 my $w = 0;
269 for (map urxvt::wcswidth $_, @lines) { 364 for (map $self->strwidth ($_), @lines) {
270 $w = $_ if $w < $_; 365 $w = $_ if $w < $_;
271 } 366 }
272 367
273 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 368 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
274 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 369 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
… …
291position. 386position.
292 387
293=item $term->scr_overlay_set ($x, $y, $text) 388=item $term->scr_overlay_set ($x, $y, $text)
294 389
295Write 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 >>.
296 410
297=back 411=back
298 412
299=head2 The C<urxvt::timer> Class 413=head2 The C<urxvt::timer> Class
300 414
… …
391 505
392Stop watching for events on the given filehandle. 506Stop watching for events on the given filehandle.
393 507
394=back 508=back
395 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
396=head1 AUTHOR 527=head1 AUTHOR
397 528
398 Marc Lehmann <pcg@goof.com> 529 Marc Lehmann <pcg@goof.com>
399 http://software.schmorp.de/pkg/rxvt-unicode 530 http://software.schmorp.de/pkg/rxvt-unicode
400 531

Diff Legend

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