… | |
… | |
120 | different types of metadata. These comments are scanned whenever a |
120 | different types of metadata. These comments are scanned whenever a |
121 | terminal is created and are typically used to autoload extensions when |
121 | terminal is created and are typically used to autoload extensions when |
122 | their resources or command line parameters are used. |
122 | their resources or command line parameters are used. |
123 | |
123 | |
124 | Currently, it recognises these comments below. Individual components are |
124 | Currently, it recognises these comments below. Individual components are |
125 | separated by cololns (C<:>), and shoudl not contain colons themselves - |
125 | separated by colons (C<:>), and should not contain colons themselves - |
126 | there is also currently no escaping mechanism provided for this. |
126 | there is also currently no escaping mechanism provided for this. |
127 | |
127 | |
128 | =over |
128 | =over |
129 | |
129 | |
130 | =item #:META:RESOURCE:name:type:desc |
130 | =item #:META:RESOURCE:name:type:desc |
… | |
… | |
134 | or C<string>, and C<desc> is the resource description. |
134 | or C<string>, and C<desc> is the resource description. |
135 | |
135 | |
136 | The extension will be autoloaded when this resource is specified or used |
136 | The extension will be autoloaded when this resource is specified or used |
137 | as a command line parameter. |
137 | as a command line parameter. |
138 | |
138 | |
139 | Example: matcher provides the C<matcher.launcher> ressource by having this |
139 | Example: matcher provides the C<matcher.launcher> resource by having this |
140 | comment: |
140 | comment: |
141 | |
141 | |
142 | #:META:RESOURCE:%.launcher:string:default launcher command |
142 | #:META:RESOURCE:%.launcher:string:default launcher command |
143 | |
143 | |
144 | Example: load this extension when the C<-tr> command line option or |
144 | Example: load this extension when the C<-tr> command line option or |
… | |
… | |
154 | |
154 | |
155 | This will cause the extension to be autoloaded when the OSC sequence is |
155 | This will cause the extension to be autoloaded when the OSC sequence is |
156 | used for the first time. |
156 | used for the first time. |
157 | |
157 | |
158 | Note that autoloading carries some extra responsibilities with it: |
158 | Note that autoloading carries some extra responsibilities with it: |
159 | although the terminal cnanot really protect itself against malicious |
159 | although the terminal cannot really protect itself against malicious |
160 | sources of command sequences, therefore relying on the programs running |
160 | sources of command sequences, therefore relying on the programs running |
161 | I<inside> to sanitize data that they output, it is very common for |
161 | I<inside> to sanitize data that they output, it is very common for |
162 | programs to emit command sequences from untrusted sources. |
162 | programs to emit command sequences from untrusted sources. |
163 | |
163 | |
164 | While this means that extensions should, as a defense-in-depth mechanism, |
164 | While this means that extensions should, as a defense-in-depth mechanism, |
… | |
… | |
196 | relevant action might not be carried out by the C++ code. |
196 | relevant action might not be carried out by the C++ code. |
197 | |
197 | |
198 | I<< When in doubt, return a false value (preferably C<()>). >> |
198 | I<< When in doubt, return a false value (preferably C<()>). >> |
199 | |
199 | |
200 | =over |
200 | =over |
|
|
201 | |
|
|
202 | =item on_attach $term |
|
|
203 | |
|
|
204 | Called when an extension package is attached to a running terminal |
|
|
205 | instance. Must return true in all cases, and runs with the same |
|
|
206 | limitations as C<on_init>. |
|
|
207 | |
|
|
208 | Unlike C<on_init> or C<on_start>, this is called when the extension is |
|
|
209 | attached to a terminal, regardless of whether the extension is loaded |
|
|
210 | before or after the terminal is started. Extensions that need to do |
|
|
211 | something before they work can do it in this callback, as opposed to e.g. |
|
|
212 | C<on_init>, which might not be called. |
201 | |
213 | |
202 | =item on_init $term |
214 | =item on_init $term |
203 | |
215 | |
204 | Called after a new terminal object has been initialized, but before |
216 | Called after a new terminal object has been initialized, but before |
205 | windows are created or the command gets run. Most methods are unsafe to |
217 | windows are created or the command gets run. Most methods are unsafe to |
… | |
… | |
823 | |
835 | |
824 | eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval"); |
836 | eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval"); |
825 | warn $@ if $@; |
837 | warn $@ if $@; |
826 | } |
838 | } |
827 | |
839 | |
828 | $retval = undef; |
|
|
829 | |
|
|
830 | if ($htype == HOOK_OSC_SEQ) { |
840 | if ($htype == HOOK_OSC_SEQ) { |
831 | if (my $exts = delete $TERM->{meta}{autoload_osc}{$_[0]}) { |
841 | if (my $exts = delete $TERM->{meta}{autoload_osc}{$_[0]}) { |
832 | $TERM->autoload_extension ($_->[0]) for @$exts; |
842 | $TERM->autoload_extension ($_->[0]) for @$exts; |
833 | } |
843 | } |
834 | } elsif ($htype == HOOK_OSC_SEQ_PERL) { |
844 | } elsif ($htype == HOOK_OSC_SEQ_PERL) { |
835 | if ($_[0] =~ /^([^;]+)/ and (my $exts = delete $TERM->{meta}{autoload_osc_perl}{$1})) { |
845 | if ($_[0] =~ /^([^;]+)/ and (my $exts = delete $TERM->{meta}{autoload_osc_perl}{$1})) { |
836 | $TERM->autoload_extension ($_->[0]) for @$exts; |
846 | $TERM->autoload_extension ($_->[0]) for @$exts; |
837 | } |
847 | } |
838 | } |
848 | } |
|
|
849 | |
|
|
850 | $retval = undef; |
839 | |
851 | |
840 | if (my $cb = $TERM->{_hook}[$htype]) { |
852 | if (my $cb = $TERM->{_hook}[$htype]) { |
841 | verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" |
853 | verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")" |
842 | if $verbosity >= 10; |
854 | if $verbosity >= 10; |
843 | |
855 | |
… | |
… | |
1180 | # find on_xxx subs in the package and register them |
1192 | # find on_xxx subs in the package and register them |
1181 | # as hooks |
1193 | # as hooks |
1182 | sub register_package { |
1194 | sub register_package { |
1183 | my ($self, $pkg, $argv) = @_; |
1195 | my ($self, $pkg, $argv) = @_; |
1184 | |
1196 | |
|
|
1197 | return if $self->{_pkg}{$pkg}; |
|
|
1198 | |
1185 | no strict 'refs'; |
1199 | no strict 'refs'; |
1186 | |
1200 | |
1187 | urxvt::verbose 6, "register package $pkg to $self"; |
1201 | urxvt::verbose 6, "register package $pkg to $self"; |
1188 | |
1202 | |
1189 | @{"$pkg\::ISA"} = urxvt::term::extension::; |
1203 | @{"$pkg\::ISA"} = urxvt::term::extension::; |
… | |
… | |
1200 | for my $name (@HOOKNAME) { |
1214 | for my $name (@HOOKNAME) { |
1201 | if (my $ref = $pkg->can ("on_" . lc $name)) { |
1215 | if (my $ref = $pkg->can ("on_" . lc $name)) { |
1202 | $proxy->enable ($name => $ref); |
1216 | $proxy->enable ($name => $ref); |
1203 | } |
1217 | } |
1204 | } |
1218 | } |
1205 | } |
|
|
1206 | |
1219 | |
|
|
1220 | if (my $attach_hook = $pkg->can ("on_attach")) { |
|
|
1221 | $attach_hook->($proxy) |
|
|
1222 | or urxvt::verbose 1, "$pkg->on_attach returned false, extension failed to attach"; |
|
|
1223 | } |
|
|
1224 | } |
|
|
1225 | |
1207 | # map extension name to filesyystem path |
1226 | # map extension name to filesystem path |
1208 | sub extension_path { |
1227 | sub extension_path { |
1209 | (grep -f $_, map "$_/$_[1]", $_[0]->perl_libdirs)[0] |
1228 | (grep -f $_, map "$_/$_[1]", $_[0]->perl_libdirs)[0] |
1210 | } |
1229 | } |
1211 | |
1230 | |
1212 | # load an extension by name |
1231 | # load an extension by name |
… | |
… | |
1345 | Works like the combination of the C<fork>/C<exec> builtins, which executes |
1364 | Works like the combination of the C<fork>/C<exec> builtins, which executes |
1346 | ("starts") programs in the background. This function takes care of setting |
1365 | ("starts") programs in the background. This function takes care of setting |
1347 | the user environment before exec'ing the command (e.g. C<PATH>) and should |
1366 | the user environment before exec'ing the command (e.g. C<PATH>) and should |
1348 | be preferred over explicit calls to C<exec> or C<system>. |
1367 | be preferred over explicit calls to C<exec> or C<system>. |
1349 | |
1368 | |
|
|
1369 | It also sets the C<URXVT_EXT_WINDOWID> environment variable to the window |
|
|
1370 | ID of the terminal (C<< $self->parent >>), similar to the C<WINDOWID> |
|
|
1371 | variable set for the process spawned inside the terminal. |
|
|
1372 | |
1350 | Returns the pid of the subprocess or C<undef> on error. |
1373 | Returns the pid of the subprocess or C<undef> on error. |
1351 | |
1374 | |
1352 | =cut |
1375 | =cut |
1353 | |
1376 | |
1354 | sub exec_async { |
1377 | sub exec_async { |
… | |
… | |
1357 | my $pid = fork; |
1380 | my $pid = fork; |
1358 | |
1381 | |
1359 | return $pid |
1382 | return $pid |
1360 | if !defined $pid or $pid; |
1383 | if !defined $pid or $pid; |
1361 | |
1384 | |
|
|
1385 | %ENV = ( |
1362 | %ENV = %{ $self->env }; |
1386 | %{ $self->env }, |
|
|
1387 | URXVT_EXT_WINDOWID => $self->parent, |
|
|
1388 | ); |
1363 | |
1389 | |
1364 | exec @_; |
1390 | exec @_; |
1365 | urxvt::_exit 255; |
1391 | urxvt::_exit 255; |
1366 | } |
1392 | } |
1367 | |
1393 | |
… | |
… | |
1625 | Returns the number of screen-cells this string would need. Correctly |
1651 | Returns the number of screen-cells this string would need. Correctly |
1626 | accounts for wide and combining characters. |
1652 | accounts for wide and combining characters. |
1627 | |
1653 | |
1628 | =item $octets = $term->locale_encode ($string) |
1654 | =item $octets = $term->locale_encode ($string) |
1629 | |
1655 | |
1630 | Convert the given text string into the corresponding locale encoding. |
1656 | Convert the given text string into the corresponding locale |
|
|
1657 | encoding. Returns C<undef> if C<$string> is C<undef>. |
1631 | |
1658 | |
1632 | =item $string = $term->locale_decode ($octets) |
1659 | =item $string = $term->locale_decode ($octets) |
1633 | |
1660 | |
1634 | Convert the given locale-encoded octets into a perl string. |
1661 | Convert the given locale-encoded octets into a perl string. Returns |
|
|
1662 | C<undef> if C<$octets> is C<undef>. |
1635 | |
1663 | |
1636 | =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) |
1664 | =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) |
1637 | |
1665 | |
1638 | XORs the rendition values in the given span with the provided value |
1666 | XORs the rendition values in the given span with the provided value |
1639 | (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in |
1667 | (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in |
… | |
… | |
2001 | where one character corresponds to one screen cell. See |
2029 | where one character corresponds to one screen cell. See |
2002 | C<< $term->ROW_t >> for details. |
2030 | C<< $term->ROW_t >> for details. |
2003 | |
2031 | |
2004 | =item $string = $term->special_decode $text |
2032 | =item $string = $term->special_decode $text |
2005 | |
2033 | |
2006 | Converts rxvt-unicodes text representation into a perl string. See |
2034 | Converts rxvt-unicode's text representation into a perl string. See |
2007 | C<< $term->ROW_t >> for details. |
2035 | C<< $term->ROW_t >> for details. |
2008 | |
2036 | |
2009 | =item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) |
2037 | =item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt]) |
2010 | |
2038 | |
2011 | =item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) |
2039 | =item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) |