--- rxvt-unicode/src/urxvt.pm	2014/05/28 15:51:29	1.239
+++ rxvt-unicode/src/urxvt.pm	2014/12/26 21:01:46	1.248
@@ -45,8 +45,15 @@
 
   URxvt.perl-ext-common: default,selection-autotransform
 
-Extensions that add command line parameters or resources on their own are
-loaded automatically when used.
+Extensions may add additional resources and C<actions>, i.e., methods
+which can be bound to a key and invoked by the user. An extension can
+define the resources it support and also default bindings for one or
+more actions it provides using so called META comments, described
+below. Similarly to builtin resources, extension resources can also be
+specified on the command line as long options (with C<.> replaced by
+C<->), in which case the corresponding extension is loaded
+automatically. For this to work the extension B<must> define META
+comments for its resources.
 
 =head1 API DOCUMENTATION
 
@@ -108,6 +115,23 @@
 Additional methods only supported for extension objects are described in
 the C<urxvt::extension> section below.
 
+=head2 META comments
+
+Rxvt-unicode recognizes special meta comments in extensions that define
+different types of metadata.
+
+Currently, it recxognises only one such comment:
+
+=over 4
+
+=item #:META:RESOURCE:name:type:desc
+
+The RESOURCE comment defines a resource used by the extension, where
+C<name> is the resource name, C<type> is the resource type, C<boolean>
+or C<string>, and C<desc> is the resource description.
+
+=back
+
 =head2 Hooks
 
 The following subroutines can be declared in extension files, and will be
@@ -283,6 +307,14 @@
 
 Called just after the screen gets redrawn. See C<on_refresh_begin>.
 
+=item on_action $term, $string
+
+Called whenever an action is invoked for the corresponding extension
+(e.g. via a C<extension:string> builtin action bound to a key, see
+description of the B<keysym> resource in the urxvt(1) manpage). The
+event is simply the action string. Note that an action event is always
+associated to a single extension.
+
 =item on_user_command $term, $string *DEPRECATED*
 
 Called whenever a user-configured event is being activated (e.g. via
@@ -557,19 +589,21 @@
 sub parse_resource {
    my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
 
-   $name =~ y/-/./ if $isarg;
-
    $term->scan_extensions;
 
    my $r = $term->{meta}{resource};
    keys %$r; # reset iterator
-   while (my ($pattern, $v) = each %$r) {
-      if (
-         $pattern =~ /\.$/
-         ? $pattern eq substr $name, 0, length $pattern
-         : $pattern eq $name
-      ) {
-         $name = "$urxvt::RESCLASS.$name";
+   while (my ($k, $v) = each %$r) {
+      my $pattern = $k;
+      $pattern =~ y/./-/ if $isarg;
+      my $prefix = $name;
+      my $suffix;
+      if ($pattern =~ /\-$/) {
+         $prefix = substr $name, 0, length $pattern;
+         $suffix = substr $name, length $pattern;
+      }
+      if ($pattern eq $prefix) {
+         $name = "$urxvt::RESCLASS.$k$suffix";
 
          push @{ $term->{perl_ext_3} }, $v->[0];
 
@@ -677,22 +711,19 @@
       }
 
       for (
-         grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2
+         (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2),
+         @{ delete $TERM->{perl_ext_3} }
       ) {
          if ($_ eq "default") {
 
             $ext_arg{$_} = []
-               for
-                  qw(selection option-popup selection-popup readline),
-                  map $_->[0], values %{ $TERM->{meta}{binding} },
-                  @{ delete $TERM->{perl_ext_3} };
+               for qw(selection option-popup selection-popup readline searchable-scrollback);
 
             for ($TERM->_keysym_resources) {
                next if /^(?:string|command|builtin|builtin-string|perl)/;
                next unless /^([A-Za-z0-9_\-]+):/;
 
                my $ext = $1;
-               $ext =~ y/-/_/;
 
                $ext_arg{$ext} = [];
             }
@@ -708,13 +739,6 @@
          }
       }
 
-      # now register default key bindings
-      for my $ext (sort keys %ext_arg) {
-         while (my ($k, $v) = each %{ $TERM->{meta}{ext}{$ext}{binding} }) {
-            $TERM->bind_action ($k, "$v->[0]:$v->[1]");
-         }
-      }
-
       for my $ext (sort keys %ext_arg) {
          my @files = grep -f $_, map "$_/$ext", @dirs;
 
@@ -944,16 +968,25 @@
    bless \%disable, "urxvt::extension::on_disable"
 }
 
+=item $self->bind_action ($hotkey, $action)
+
 =item $self->x_resource ($pattern)
 
 =item $self->x_resource_boolean ($pattern)
 
-These methods support an additional C<%> prefix when called on an
-extension object - see the description of these methods in the
-C<urxvt::term> class for details.
+These methods support an additional C<%> prefix for C<$action> or
+C<$pattern> when called on an extension object, compared to the
+C<urxvt::term> methods of the same name - see the description of these
+methods in the C<urxvt::term> class for details.
 
 =cut
 
+sub bind_action {
+   my ($self, $hotkey, $action) = @_;
+   $action =~ s/^%:/$_[0]{_name}:/;
+   $self->{term}->bind_action ($hotkey, $action)
+}
+
 sub x_resource {
    my ($self, $name) = @_;
    $name =~ s/^%(\.|$)/$_[0]{_name}$1/;
@@ -1130,9 +1163,6 @@
                } else {
                   $ext{resource}{$pattern} = [$ext, $type, $desc];
                }
-            } elsif (/^#:META:BINDING:(.*)/) {
-               my ($keysym, $action) = split /:/, $1;
-               $ext{binding}{$keysym} = [$ext, $action];
             } elsif (/^\s*(?:#|$)/) {
                # skip other comments and empty lines
             } else {
@@ -1144,11 +1174,10 @@
       }
    }
 
-   # and now merge resources and bindings
+   # and now merge resources
    while (my ($k, $v) = each %{ $meta{ext} }) {
       #TODO: should check for extensions overriding each other
       %{ $meta{resource} } = (%{ $meta{resource} }, %{ $v->{resource} });
-      %{ $meta{binding}  } = (%{ $meta{binding}  }, %{ $v->{binding}  });
    }
 }
 
@@ -1274,15 +1303,15 @@
 same value as used by this instance of rxvt-unicode. Returns C<undef> if no
 resource with that pattern exists.
 
-Extensions that define extra resource or command line arguments also need
-to call this method to access their values.
+Extensions that define extra resources also need to call this method
+to access their values.
 
 If the method is called on an extension object (basically, from an
 extension), then the special prefix C<%.> will be replaced by the name of
 the extension and a dot, and the lone string C<%> will be replaced by the
 extension name itself. This makes it possible to code extensions so you
-can rename them and get a new set of commandline switches and resources
-without having to change the actual code.
+can rename them and get a new set of resources without having to change
+the actual code.
 
 This method should only be called during the C<on_start> hook, as there is
 only one resource database per display, and later invocations might return
@@ -1304,11 +1333,26 @@
    $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
 }
 
-=item $success = $term->bind_action ($key, $octets)
+=item $success = $term->bind_action ($key, $action)
 
 Adds a key binding exactly as specified via a C<keysym> resource. See the
 C<keysym> resource in the urxvt(1) manpage.
 
+To add default bindings for an extension, the extension should call C<<
+->bind_action >> on it's C<init> hook for every such binding. Doing it
+in the C<init> hook allows users the override or remove the the binding
+again.
+
+Example: the C<searchable-scrollback> by default binds itself
+on C<Meta-s>, using C<< $self->bind_action >>, which calls C<<
+$term->bind_action >>.
+
+   sub init {
+      my ($self) = @_;
+
+      $self->bind_action ("M-s" => "%:start");
+   }
+
 =item $rend = $term->rstyle ([$new_rstyle])
 
 Return and optionally change the current rendition. Text that is output by
@@ -1475,8 +1519,9 @@
 
 Write the given text string to the screen, as if output by the application
 running inside the terminal. It may not contain command sequences (escape
-codes), but is free to use line feeds, carriage returns and tabs. The
-string is a normal text string, not in locale-dependent encoding.
+codes - see C<cmd_parse> for that), but is free to use line feeds,
+carriage returns and tabs. The string is a normal text string, not in
+locale-dependent encoding.
 
 Normally its not a good idea to use this function, as programs might be
 confused by changes in cursor position or scrolling. Its useful inside a
@@ -1494,9 +1539,10 @@
 
 =item $term->tt_write ($octets)
 
-Write the octets given in C<$octets> to the tty (i.e. as program input). To
-pass characters instead of octets, you should convert your strings first
-to the locale-specific encoding using C<< $term->locale_encode >>.
+Write the octets given in C<$octets> to the tty (i.e. as user input
+to the program, see C<cmd_parse> for the opposite direction). To pass
+characters instead of octets, you should convert your strings first to the
+locale-specific encoding using C<< $term->locale_encode >>.
 
 =item $term->tt_write_user_input ($octets)