… | |
… | |
4 | |
4 | |
5 | urxvtperl - rxvt-unicode's embedded perl interpreter |
5 | urxvtperl - rxvt-unicode's embedded perl interpreter |
6 | |
6 | |
7 | =head1 SYNOPSIS |
7 | =head1 SYNOPSIS |
8 | |
8 | |
9 | # create a file grab_test in $HOME: |
9 | # create a file grab_test in some directory: |
10 | |
10 | |
11 | sub on_sel_grab { |
11 | sub on_sel_grab { |
12 | warn "you selected ", $_[0]->selection; |
12 | warn "you selected ", $_[0]->selection; |
13 | () |
13 | () |
14 | } |
14 | } |
15 | |
15 | |
16 | # start a urxvt using it: |
16 | # start a urxvt instance using it: |
17 | |
17 | |
18 | urxvt --perl-lib $HOME -pe grab_test |
18 | urxvt --perl-lib path/to/somedirectory -pe grab_test |
19 | |
19 | |
20 | =head1 DESCRIPTION |
20 | =head1 DESCRIPTION |
21 | |
21 | |
22 | Every time a terminal object gets created, extension scripts specified via |
22 | Every time a terminal object gets created, extension scripts specified via |
23 | the C<perl> resource are loaded and associated with it. |
23 | the C<perl> resource are loaded and associated with it. |
… | |
… | |
70 | terminal is destroyed. |
70 | terminal is destroyed. |
71 | |
71 | |
72 | Argument names also often indicate the type of a parameter. Here are some |
72 | Argument names also often indicate the type of a parameter. Here are some |
73 | hints on what they mean: |
73 | hints on what they mean: |
74 | |
74 | |
75 | =over 4 |
75 | =over |
76 | |
76 | |
77 | =item $text |
77 | =item $text |
78 | |
78 | |
79 | Rxvt-unicode's special way of encoding text, where one "unicode" character |
79 | Rxvt-unicode's special way of encoding text, where one "unicode" character |
80 | always represents one screen cell. See L<ROW_t> for a discussion of this format. |
80 | always represents one screen cell. See L<ROW_t> for a discussion of this format. |
… | |
… | |
115 | the C<urxvt::extension> section below. |
115 | the C<urxvt::extension> section below. |
116 | |
116 | |
117 | =head2 META comments |
117 | =head2 META comments |
118 | |
118 | |
119 | Rxvt-unicode recognizes special meta comments in extensions that define |
119 | Rxvt-unicode recognizes special meta comments in extensions that define |
120 | different types of metadata. |
120 | different types of metadata. These comments are scanned whenever a |
|
|
121 | terminal is created and are typically used to autoload extensions when |
|
|
122 | their resources or command line parameters are used. |
121 | |
123 | |
122 | Currently, it recognises only one such comment: |
124 | Currently, it recognises only one such comment: |
123 | |
125 | |
124 | =over 4 |
126 | =over |
125 | |
127 | |
126 | =item #:META:RESOURCE:name:type:desc |
128 | =item #:META:RESOURCE:name:type:desc |
127 | |
129 | |
128 | The RESOURCE comment defines a resource used by the extension, where |
130 | The RESOURCE comment defines a resource used by the extension, where |
129 | C<name> is the resource name, C<type> is the resource type, C<boolean> |
131 | C<name> is the resource name, C<type> is the resource type, C<boolean> |
130 | or C<string>, and C<desc> is the resource description. |
132 | or C<string>, and C<desc> is the resource description. |
131 | |
133 | |
|
|
134 | The extension will be autoloaded when this resource is specified or used |
|
|
135 | as a command line parameter. |
|
|
136 | |
132 | =back |
137 | =back |
133 | |
138 | |
134 | =head2 Hooks |
139 | =head2 Hooks |
135 | |
140 | |
136 | The following subroutines can be declared in extension files, and will be |
141 | The following subroutines can be declared in extension files, and will be |
… | |
… | |
143 | hooks returns true, then the event counts as being I<consumed>, and the |
148 | hooks returns true, then the event counts as being I<consumed>, and the |
144 | relevant action might not be carried out by the C++ code. |
149 | relevant action might not be carried out by the C++ code. |
145 | |
150 | |
146 | I<< When in doubt, return a false value (preferably C<()>). >> |
151 | I<< When in doubt, return a false value (preferably C<()>). >> |
147 | |
152 | |
148 | =over 4 |
153 | =over |
149 | |
154 | |
150 | =item on_init $term |
155 | =item on_init $term |
151 | |
156 | |
152 | Called after a new terminal object has been initialized, but before |
157 | Called after a new terminal object has been initialized, but before |
153 | windows are created or the command gets run. Most methods are unsafe to |
158 | windows are created or the command gets run. Most methods are unsafe to |
… | |
… | |
417 | |
422 | |
418 | our $NOCHAR = chr 0xffff; |
423 | our $NOCHAR = chr 0xffff; |
419 | |
424 | |
420 | =head2 Variables in the C<urxvt> Package |
425 | =head2 Variables in the C<urxvt> Package |
421 | |
426 | |
422 | =over 4 |
427 | =over |
423 | |
428 | |
424 | =item $urxvt::LIBDIR |
429 | =item $urxvt::LIBDIR |
425 | |
430 | |
426 | The rxvt-unicode library directory, where, among other things, the perl |
431 | The rxvt-unicode library directory, where, among other things, the perl |
427 | modules and scripts are stored. |
432 | modules and scripts are stored. |
… | |
… | |
457 | |
462 | |
458 | =back |
463 | =back |
459 | |
464 | |
460 | =head2 Functions in the C<urxvt> Package |
465 | =head2 Functions in the C<urxvt> Package |
461 | |
466 | |
462 | =over 4 |
467 | =over |
463 | |
468 | |
464 | =item urxvt::fatal $errormessage |
469 | =item urxvt::fatal $errormessage |
465 | |
470 | |
466 | Fatally aborts execution with the given error message (which should |
471 | Fatally aborts execution with the given error message (which should |
467 | include a trailing newline). Avoid at all costs! The only time this |
472 | include a trailing newline). Avoid at all costs! The only time this |
… | |
… | |
518 | PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP, |
523 | PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP, |
519 | PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys, |
524 | PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys, |
520 | PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11, |
525 | PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11, |
521 | PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress, |
526 | PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress, |
522 | PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent, |
527 | PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent, |
523 | PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtModeMouse, |
528 | PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8, |
524 | PrivMode_ExtMouseRight, PrivMode_BlinkingCursor, PrivMode_mouse_report, |
529 | PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report, |
525 | PrivMode_Default |
530 | PrivMode_Default |
526 | |
531 | |
527 | Constants for checking DEC private modes. |
532 | Constants for checking DEC private modes. |
528 | |
533 | |
529 | =back |
534 | =back |
… | |
… | |
536 | The following "macros" deal with changes in rendition sets. You should |
541 | The following "macros" deal with changes in rendition sets. You should |
537 | never just create a bitset, you should always modify an existing one, |
542 | never just create a bitset, you should always modify an existing one, |
538 | as they contain important information required for correct operation of |
543 | as they contain important information required for correct operation of |
539 | rxvt-unicode. |
544 | rxvt-unicode. |
540 | |
545 | |
541 | =over 4 |
546 | =over |
542 | |
547 | |
543 | =item $rend = urxvt::DEFAULT_RSTYLE |
548 | =item $rend = urxvt::DEFAULT_RSTYLE |
544 | |
549 | |
545 | Returns the default rendition, as used when the terminal is starting up or |
550 | Returns the default rendition, as used when the terminal is starting up or |
546 | being reset. Useful as a base to start when creating renditions. |
551 | being reset. Useful as a base to start when creating renditions. |
… | |
… | |
600 | sub parse_resource { |
605 | sub parse_resource { |
601 | my ($term, $name, $isarg, $longopt, $flag, $value) = @_; |
606 | my ($term, $name, $isarg, $longopt, $flag, $value) = @_; |
602 | |
607 | |
603 | $term->scan_extensions; |
608 | $term->scan_extensions; |
604 | |
609 | |
|
|
610 | # iterating over all resources has quadratic time overhead |
|
|
611 | # overall, maybe this could be optimised? |
605 | my $r = $term->{meta}{resource}; |
612 | my $r = $term->{meta}{resource}; |
606 | keys %$r; # reset iterator |
613 | keys %$r; # reset iterator |
607 | while (my ($k, $v) = each %$r) { |
614 | while (my ($k, $v) = each %$r) { |
608 | my $pattern = $k; |
615 | my $pattern = $k; |
609 | $pattern =~ y/./-/ if $isarg; |
616 | $pattern =~ y/./-/ if $isarg; |
… | |
… | |
722 | @TERM_EXT = (); |
729 | @TERM_EXT = (); |
723 | $TERM->register_package ($_) for @pkg; |
730 | $TERM->register_package ($_) for @pkg; |
724 | } |
731 | } |
725 | |
732 | |
726 | for ( |
733 | for ( |
|
|
734 | @{ delete $TERM->{perl_ext_3} }, |
727 | (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2), |
735 | (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2), |
728 | @{ delete $TERM->{perl_ext_3} } |
|
|
729 | ) { |
736 | ) { |
730 | if ($_ eq "default") { |
737 | if ($_ eq "default") { |
731 | |
738 | |
732 | $ext_arg{$_} = [] |
739 | $ext_arg{$_} = [] |
733 | for qw(selection option-popup selection-popup readline searchable-scrollback); |
740 | for qw(selection option-popup selection-popup readline searchable-scrollback confirm-paste); |
734 | |
741 | |
735 | for ($TERM->_keysym_resources) { |
742 | for ($TERM->_keysym_resources) { |
736 | next if /^(?:string|command|builtin|builtin-string|perl)/; |
743 | next if /^(?:string|command|builtin|builtin-string|perl)/; |
737 | next unless /^([A-Za-z0-9_\-]+):/; |
744 | next unless /^([A-Za-z0-9_\-]+):/; |
738 | |
745 | |
… | |
… | |
851 | |
858 | |
852 | The methods (And data members) documented below can be called on extension |
859 | The methods (And data members) documented below can be called on extension |
853 | objects, in addition to call methods documented for the <urxvt::term> |
860 | objects, in addition to call methods documented for the <urxvt::term> |
854 | class. |
861 | class. |
855 | |
862 | |
856 | =over 4 |
863 | =over |
857 | |
864 | |
858 | =item $urxvt_term = $self->{term} |
865 | =item $urxvt_term = $self->{term} |
859 | |
866 | |
860 | Returns the C<urxvt::term> object associated with this instance of the |
867 | Returns the C<urxvt::term> object associated with this instance of the |
861 | extension. This member I<must not> be changed in any way. |
868 | extension. This member I<must not> be changed in any way. |
… | |
… | |
1102 | |
1109 | |
1103 | package urxvt::term; |
1110 | package urxvt::term; |
1104 | |
1111 | |
1105 | =head2 The C<urxvt::term> Class |
1112 | =head2 The C<urxvt::term> Class |
1106 | |
1113 | |
1107 | =over 4 |
1114 | =over |
1108 | |
1115 | |
1109 | =cut |
1116 | =cut |
1110 | |
1117 | |
1111 | # find on_xxx subs in the package and register them |
1118 | # find on_xxx subs in the package and register them |
1112 | # as hooks |
1119 | # as hooks |
… | |
… | |
1277 | insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell |
1284 | insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell |
1278 | mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs |
1285 | mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs |
1279 | pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right |
1286 | pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right |
1280 | scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen |
1287 | scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen |
1281 | secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords |
1288 | secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords |
1282 | urgentOnBell utmpInhibit visualBell |
1289 | urgentOnBell utmpInhibit visualBell disablePasteBrackets |
1283 | |
1290 | |
1284 | =item $value = $term->resource ($name[, $newval]) |
1291 | =item $value = $term->resource ($name[, $newval]) |
1285 | |
1292 | |
1286 | Returns the current resource value associated with a given name and |
1293 | Returns the current resource value associated with a given name and |
1287 | optionally sets a new value. Setting values is most useful in the C<init> |
1294 | optionally sets a new value. Setting values is most useful in the C<init> |
… | |
… | |
1313 | preeditType print_pipe pty_fd reverseVideo saveLines scrollBar |
1320 | preeditType print_pipe pty_fd reverseVideo saveLines scrollBar |
1314 | scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness |
1321 | scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness |
1315 | scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle |
1322 | scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle |
1316 | secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll |
1323 | secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll |
1317 | term_name title transient_for transparent tripleclickwords urgentOnBell |
1324 | term_name title transient_for transparent tripleclickwords urgentOnBell |
1318 | utmpInhibit visualBell |
1325 | utmpInhibit visualBell rewrapMode disablePasteBrackets |
1319 | |
1326 | |
1320 | =cut |
1327 | =cut |
1321 | |
1328 | |
1322 | sub resource($$;$) { |
1329 | sub resource($$;$) { |
1323 | my ($self, $name) = (shift, shift); |
1330 | my ($self, $name) = (shift, shift); |
… | |
… | |
1470 | This method returns an urxvt::overlay object. The overlay will be visible |
1477 | This method returns an urxvt::overlay object. The overlay will be visible |
1471 | as long as the perl object is referenced. |
1478 | as long as the perl object is referenced. |
1472 | |
1479 | |
1473 | The methods currently supported on C<urxvt::overlay> objects are: |
1480 | The methods currently supported on C<urxvt::overlay> objects are: |
1474 | |
1481 | |
1475 | =over 4 |
1482 | =over |
1476 | |
1483 | |
1477 | =item $overlay->set ($x, $y, $text[, $rend]) |
1484 | =item $overlay->set ($x, $y, $text[, $rend]) |
1478 | |
1485 | |
1479 | Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts |
1486 | Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts |
1480 | text in rxvt-unicode's special encoding and an array of rendition values |
1487 | text in rxvt-unicode's special encoding and an array of rendition values |
… | |
… | |
1715 | # mouse reporting is turned on |
1722 | # mouse reporting is turned on |
1716 | } |
1723 | } |
1717 | |
1724 | |
1718 | =item $view_start = $term->view_start ([$newvalue]) |
1725 | =item $view_start = $term->view_start ([$newvalue]) |
1719 | |
1726 | |
1720 | Returns the row number of the topmost displayed line. Maximum value is |
1727 | Returns the row number of the topmost displayed line and changes it, |
1721 | C<0>, which displays the normal terminal contents. Lower values scroll |
1728 | if an argument is given. Values greater than or equal to C<0> display |
1722 | this many lines into the scrollback buffer. |
1729 | the terminal contents. Lower values scroll this many lines into the |
|
|
1730 | scrollback buffer. |
1723 | |
1731 | |
1724 | =item $term->want_refresh |
1732 | =item $term->want_refresh |
1725 | |
1733 | |
1726 | Requests a screen refresh. At the next opportunity, rxvt-unicode will |
1734 | Requests a screen refresh. At the next opportunity, rxvt-unicode will |
1727 | compare the on-screen display with its stored representation. If they |
1735 | compare the on-screen display with its stored representation. If they |
… | |
… | |
1785 | |
1793 | |
1786 | Create and return a new C<urxvt::line> object that stores information |
1794 | Create and return a new C<urxvt::line> object that stores information |
1787 | about the logical line that row C<$row_number> is part of. It supports the |
1795 | about the logical line that row C<$row_number> is part of. It supports the |
1788 | following methods: |
1796 | following methods: |
1789 | |
1797 | |
1790 | =over 4 |
1798 | =over |
1791 | |
1799 | |
1792 | =item $text = $line->t ([$new_text]) |
1800 | =item $text = $line->t ([$new_text]) |
1793 | |
1801 | |
1794 | Returns or replaces the full text of the line, similar to C<ROW_t> |
1802 | Returns or replaces the full text of the line, similar to C<ROW_t> |
1795 | |
1803 | |
… | |
… | |
1975 | |
1983 | |
1976 | package urxvt::popup; |
1984 | package urxvt::popup; |
1977 | |
1985 | |
1978 | =head2 The C<urxvt::popup> Class |
1986 | =head2 The C<urxvt::popup> Class |
1979 | |
1987 | |
1980 | =over 4 |
1988 | =over |
1981 | |
1989 | |
1982 | =cut |
1990 | =cut |
1983 | |
1991 | |
1984 | sub add_item { |
1992 | sub add_item { |
1985 | my ($self, $item) = @_; |
1993 | my ($self, $item) = @_; |
… | |
… | |
2121 | ->cb (sub { |
2129 | ->cb (sub { |
2122 | $term->{overlay}->set (0, 0, |
2130 | $term->{overlay}->set (0, 0, |
2123 | sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); |
2131 | sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); |
2124 | }); |
2132 | }); |
2125 | |
2133 | |
2126 | =over 4 |
2134 | =over |
2127 | |
2135 | |
2128 | =item $timer = new urxvt::timer |
2136 | =item $timer = new urxvt::timer |
2129 | |
2137 | |
2130 | Create a new timer object in started state. It is scheduled to fire |
2138 | Create a new timer object in started state. It is scheduled to fire |
2131 | immediately. |
2139 | immediately. |
… | |
… | |
2180 | sysread $term->{socket}, my $buf, 8192 |
2188 | sysread $term->{socket}, my $buf, 8192 |
2181 | or end-of-file; |
2189 | or end-of-file; |
2182 | }); |
2190 | }); |
2183 | |
2191 | |
2184 | |
2192 | |
2185 | =over 4 |
2193 | =over |
2186 | |
2194 | |
2187 | =item $iow = new urxvt::iow |
2195 | =item $iow = new urxvt::iow |
2188 | |
2196 | |
2189 | Create a new io watcher object in stopped state. |
2197 | Create a new io watcher object in stopped state. |
2190 | |
2198 | |
… | |
… | |
2217 | |
2225 | |
2218 | This class implements idle watchers, that get called automatically when |
2226 | This class implements idle watchers, that get called automatically when |
2219 | the process is idle. They should return as fast as possible, after doing |
2227 | the process is idle. They should return as fast as possible, after doing |
2220 | some useful work. |
2228 | some useful work. |
2221 | |
2229 | |
2222 | =over 4 |
2230 | =over |
2223 | |
2231 | |
2224 | =item $iw = new urxvt::iw |
2232 | =item $iw = new urxvt::iw |
2225 | |
2233 | |
2226 | Create a new idle watcher object in stopped state. |
2234 | Create a new idle watcher object in stopped state. |
2227 | |
2235 | |
… | |
… | |
2252 | ->cb (sub { |
2260 | ->cb (sub { |
2253 | my ($pw, $exit_status) = @_; |
2261 | my ($pw, $exit_status) = @_; |
2254 | ... |
2262 | ... |
2255 | }); |
2263 | }); |
2256 | |
2264 | |
2257 | =over 4 |
2265 | =over |
2258 | |
2266 | |
2259 | =item $pw = new urxvt::pw |
2267 | =item $pw = new urxvt::pw |
2260 | |
2268 | |
2261 | Create a new process watcher in stopped state. |
2269 | Create a new process watcher in stopped state. |
2262 | |
2270 | |
… | |
… | |
2279 | =head2 URXVT_PERL_VERBOSITY |
2287 | =head2 URXVT_PERL_VERBOSITY |
2280 | |
2288 | |
2281 | This variable controls the verbosity level of the perl extension. Higher |
2289 | This variable controls the verbosity level of the perl extension. Higher |
2282 | numbers indicate more verbose output. |
2290 | numbers indicate more verbose output. |
2283 | |
2291 | |
2284 | =over 4 |
2292 | =over |
2285 | |
2293 | |
2286 | =item == 0 - fatal messages |
2294 | =item == 0 - fatal messages |
2287 | |
2295 | |
2288 | =item >= 3 - script loading and management |
2296 | =item >= 3 - script loading and management |
2289 | |
2297 | |