--- rxvt-unicode/src/urxvt.pm	2021/07/24 11:58:27	1.266
+++ rxvt-unicode/src/urxvt.pm	2022/12/29 01:10:08	1.272
@@ -122,7 +122,7 @@
 their resources or command line parameters are used.
 
 Currently, it recognises these comments below. Individual components are
-separated by cololns (C<:>), and shoudl not contain colons themselves -
+separated by colons (C<:>), and should not contain colons themselves -
 there is also currently no escaping mechanism provided for this.
 
 =over
@@ -136,7 +136,7 @@
 The extension will be autoloaded when this resource is specified or used
 as a command line parameter.
 
-Example: matcher provides the C<matcher.launcher> ressource by having this
+Example: matcher provides the C<matcher.launcher> resource by having this
 comment:
 
    #:META:RESOURCE:%.launcher:string:default launcher command
@@ -156,7 +156,7 @@
 used for the first time.
 
 Note that autoloading carries some extra responsibilities with it:
-although the terminal cnanot really protect itself against malicious
+although the terminal cannot really protect itself against malicious
 sources of command sequences, therefore relying on the programs running
 I<inside> to sanitize data that they output, it is very common for
 programs to emit command sequences from untrusted sources.
@@ -199,6 +199,18 @@
 
 =over
 
+=item on_attach $term
+
+Called when an extension package is attached to a running terminal
+instance. Must return true in all cases, and runs with the same
+limitations as C<on_init>.
+
+Unlike C<on_init> or C<on_start>, this is called when the extension is
+attached to a terminal, regardless of whether the extension is loaded
+before or after the terminal is started. Extensions that need to do
+something before they work can do it in this callback, as opposed to e.g.
+C<on_init>, which might not be called.
+
 =item on_init $term
 
 Called after a new terminal object has been initialized, but before
@@ -825,8 +837,6 @@
       warn $@ if $@;
    }
 
-   $retval = undef;
-
    if ($htype == HOOK_OSC_SEQ) {
       if (my $exts = delete $TERM->{meta}{autoload_osc}{$_[0]}) {
          $TERM->autoload_extension ($_->[0]) for @$exts;
@@ -837,6 +847,8 @@
       }
    }
 
+   $retval = undef;
+
    if (my $cb = $TERM->{_hook}[$htype]) {
       verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
          if $verbosity >= 10;
@@ -1182,6 +1194,8 @@
 sub register_package {
    my ($self, $pkg, $argv) = @_;
 
+   return if $self->{_pkg}{$pkg};
+
    no strict 'refs';
 
    urxvt::verbose 6, "register package $pkg to $self";
@@ -1202,9 +1216,14 @@
          $proxy->enable ($name => $ref);
       }
    }
+
+   if (my $attach_hook = $pkg->can ("on_attach")) {
+      $attach_hook->($proxy)
+         or urxvt::verbose 1, "$pkg->on_attach returned false, extension failed to attach";
+   }
 }
 
-# map extension name to filesyystem path
+# map extension name to filesystem path
 sub extension_path {
    (grep -f $_, map "$_/$_[1]", $_[0]->perl_libdirs)[0]
 }
@@ -1347,6 +1366,10 @@
 the user environment before exec'ing the command (e.g. C<PATH>) and should
 be preferred over explicit calls to C<exec> or C<system>.
 
+It also sets the C<URXVT_EXT_WINDOWID> environment variable to the window
+ID of the terminal (C<< $self->parent >>), similar to the C<WINDOWID>
+variable set for the process spawned inside the terminal.
+
 Returns the pid of the subprocess or C<undef> on error.
 
 =cut
@@ -1359,7 +1382,10 @@
    return $pid
       if !defined $pid or $pid;
 
-   %ENV = %{ $self->env };
+   %ENV = (
+      %{ $self->env },
+      URXVT_EXT_WINDOWID => $self->parent,
+   );
 
    exec @_;
    urxvt::_exit 255;
@@ -1627,11 +1653,13 @@
 
 =item $octets = $term->locale_encode ($string)
 
-Convert the given text string into the corresponding locale encoding.
+Convert the given text string into the corresponding locale
+encoding. Returns C<undef> if C<$string> is C<undef>.
 
 =item $string = $term->locale_decode ($octets)
 
-Convert the given locale-encoded octets into a perl string.
+Convert the given locale-encoded octets into a perl string. Returns
+C<undef> if C<$octets> is C<undef>.
 
 =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
 
@@ -1995,15 +2023,15 @@
    )
 }
 
-=item $text = $term->special_encode $string
+=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
+=item $string = $term->special_decode ($text)
 
-Converts rxvt-unicodes text representation into a perl string. See
+Converts rxvt-unicode's text representation into a perl string. See
 C<< $term->ROW_t >> for details.
 
 =item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])