[ViewVC] Diff of: cvs/rxvt-unicode/src/urxvt.pm

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.266 by root, Sat Jul 24 11:58:27 2021 UTC vs.
Revision 1.272 by root, Thu Dec 29 01:10:08 2022 UTC

 different types of metadata. These comments are scanned whenever a
 terminal is created and are typically used to autoload extensions when
 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
 =item #:META:RESOURCE:name:type:desc
 or C<string>, and C<desc> is the resource description.
 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
 Example: load this extension when the C<-tr> command line option or
 This will cause the extension to be autoloaded when the OSC sequence is
 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.
 While this means that extensions should, as a defense-in-depth mechanism,
 relevant action might not be carried out by the C++ code.
 I<< When in doubt, return a false value (preferably C<()>). >>
 =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
 windows are created or the command gets run. Most methods are unsafe to
       eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
       warn $@ if $@;
    }
-   $retval = undef;
    if ($htype == HOOK_OSC_SEQ) {
       if (my $exts = delete $TERM->{meta}{autoload_osc}{$_[0]}) {
          $TERM->autoload_extension ($_->[0]) for @$exts;
       }
    } elsif ($htype == HOOK_OSC_SEQ_PERL) {
       if ($_[0] =~ /^([^;]+)/ and (my $exts = delete $TERM->{meta}{autoload_osc_perl}{$1})) {
          $TERM->autoload_extension ($_->[0]) for @$exts;
       }
    }
+   $retval = undef;
    if (my $cb = $TERM->{_hook}[$htype]) {
       verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
          if $verbosity >= 10;
 # find on_xxx subs in the package and register them
 # as hooks
 sub register_package {
    my ($self, $pkg, $argv) = @_;
+   return if $self->{_pkg}{$pkg};
    no strict 'refs';
    urxvt::verbose 6, "register package $pkg to $self";
    @{"$pkg\::ISA"} = urxvt::term::extension::;
    for my $name (@HOOKNAME) {
       if (my $ref = $pkg->can ("on_" . lc $name)) {
          $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]
 }
 # load an extension by name
 Works like the combination of the C<fork>/C<exec> builtins, which executes
 ("starts") programs in the background. This function takes care of setting
 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
 sub exec_async {
    my $pid = fork;
    return $pid
       if !defined $pid or $pid;
+   %ENV = (
-   %ENV = %{ $self->env };
+      %{ $self->env },
+      URXVT_EXT_WINDOWID => $self->parent,
+   );
    exec @_;
    urxvt::_exit 255;
 }
 Returns the number of screen-cells this string would need. Correctly
 accounts for wide and combining characters.
 =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])
 XORs the rendition values in the given span with the provided value
 (default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
       $offset / $self->{ncol} + $self->{beg},
       $offset % $self->{ncol}
    )
 }
-=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])
 =item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])

Diff Legend

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

Comparing rxvt-unicode/src/urxvt.pm (file contents): Revision 1.266 by root, Sat Jul 24 11:58:27 2021 UTC vs. Revision 1.272 by root, Thu Dec 29 01:10:08 2022 UTC

Diff Legend

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.266 by root, Sat Jul 24 11:58:27 2021 UTC vs.
Revision 1.272 by root, Thu Dec 29 01:10:08 2022 UTC