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

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.253 by sf-exg, Fri Jan 16 20:13:01 2015 UTC vs.
Revision 1.265 by root, Sat Jul 24 09:48:43 2021 UTC

 urxvtperl - rxvt-unicode's embedded perl interpreter
 =head1 SYNOPSIS
-   # create a file grab_test in $HOME:
+   # create a file grab_test in some directory:
    sub on_sel_grab {
       warn "you selected ", $_[0]->selection;
       ()
    }
-   # start a urxvt using it:
+   # start a urxvt instance using it:
-   urxvt --perl-lib $HOME -pe grab_test
+   urxvt --perl-lib path/to/somedirectory -pe grab_test
 =head1 DESCRIPTION
 Every time a terminal object gets created, extension scripts specified via
 the C<perl> resource are loaded and associated with it.
 terminal is destroyed.
 Argument names also often indicate the type of a parameter. Here are some
 hints on what they mean:
-=over 4
+=over
 =item $text
 Rxvt-unicode's special way of encoding text, where one "unicode" character
 always represents one screen cell. See L<ROW_t> for a discussion of this format.
 the C<urxvt::extension> section below.
 =head2 META comments
 Rxvt-unicode recognizes special meta comments in extensions that define
-different types of metadata.
+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 only one such comment:
-=over 4
+=over
 =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.
+The extension will be autoloaded when this resource is specified or used
+as a command line parameter.
 =back
 =head2 Hooks
 The following subroutines can be declared in extension files, and will be
 hooks returns true, then the event counts as being I<consumed>, and the
 relevant action might not be carried out by the C++ code.
 I<< When in doubt, return a false value (preferably C<()>). >>
-=over 4
+=over
 =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
 our $NOCHAR = chr 0xffff;
 =head2 Variables in the C<urxvt> Package
-=over 4
+=over
 =item $urxvt::LIBDIR
 The rxvt-unicode library directory, where, among other things, the perl
 modules and scripts are stored.
 =back
 =head2 Functions in the C<urxvt> Package
-=over 4
+=over
 =item urxvt::fatal $errormessage
 Fatally aborts execution with the given error message (which should
 include a trailing newline). Avoid at all costs! The only time this
 CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
 SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
 Various constants for use in X calls and event processing.
+=item urxvt::PrivMode_132, PrivMode_132OK, PrivMode_rVideo, PrivMode_relOrigin,
+PrivMode_Screen, PrivMode_Autowrap, PrivMode_aplCUR, PrivMode_aplKP,
+PrivMode_HaveBackSpace, PrivMode_BackSpace, PrivMode_ShiftKeys,
+PrivMode_VisibleCursor, PrivMode_MouseX10, PrivMode_MouseX11,
+PrivMode_scrollBar, PrivMode_TtyOutputInh, PrivMode_Keypress,
+PrivMode_smoothScroll, PrivMode_vt52, PrivMode_LFNL, PrivMode_MouseBtnEvent,
+PrivMode_MouseAnyEvent, PrivMode_BracketPaste, PrivMode_ExtMouseUTF8,
+PrivMode_ExtMouseUrxvt, PrivMode_BlinkingCursor, PrivMode_mouse_report,
+PrivMode_Default
+Constants for checking DEC private modes.
 =back
 =head2 RENDITION
 Rendition bitsets contain information about colour, font, font styles and
 The following "macros" deal with changes in rendition sets. You should
 never just create a bitset, you should always modify an existing one,
 as they contain important information required for correct operation of
 rxvt-unicode.
-=over 4
+=over
 =item $rend = urxvt::DEFAULT_RSTYLE
 Returns the default rendition, as used when the terminal is starting up or
 being reset. Useful as a base to start when creating renditions.
 sub parse_resource {
    my ($term, $name, $isarg, $longopt, $flag, $value) = @_;
    $term->scan_extensions;
+   # iterating over all resources has quadratic time overhead
+   # overall, maybe this could be optimised?
    my $r = $term->{meta}{resource};
    keys %$r; # reset iterator
    while (my ($k, $v) = each %$r) {
       my $pattern = $k;
       $pattern =~ y/./-/ if $isarg;
       if ($pattern eq $prefix) {
          $name = "$urxvt::RESCLASS.$k$suffix";
          push @{ $term->{perl_ext_3} }, $v->[0];
+         return 1 unless $isarg;
          if ($v->[1] eq "boolean") {
             $term->put_option_db ($name, $flag ? "true" : "false");
             return 1;
          } else {
             $term->put_option_db ($name, $value);
          @TERM_EXT = ();
          $TERM->register_package ($_) for @pkg;
       }
       for (
+         @{ delete $TERM->{perl_ext_3} },
          (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 searchable-scrollback);
+               for qw(selection option-popup selection-popup readline searchable-scrollback confirm-paste);
             for ($TERM->_keysym_resources) {
                next if /^(?:string|command|builtin|builtin-string|perl)/;
                next unless /^([A-Za-z0-9_\-]+):/;
 The methods (And data members) documented below can be called on extension
 objects, in addition to call methods documented for the <urxvt::term>
 class.
-=over 4
+=over
 =item $urxvt_term = $self->{term}
 Returns the C<urxvt::term> object associated with this instance of the
 extension. This member I<must not> be changed in any way.
 package urxvt::term;
 =head2 The C<urxvt::term> Class
-=over 4
+=over
 =cut
 # find on_xxx subs in the package and register them
 # as hooks
  insecure intensityStyles iso14755 iso14755_52 jumpScroll loginShell
  mapAlert meta8 mouseWheelScrollPage override_redirect pastableTabs
  pointerBlank reverseVideo scrollBar scrollBar_floating scrollBar_right
  scrollTtyKeypress scrollTtyOutput scrollWithBuffer secondaryScreen
  secondaryScroll skipBuiltinGlyphs skipScroll transparent tripleclickwords
- urgentOnBell utmpInhibit visualBell
+ urgentOnBell utmpInhibit visualBell disablePasteBrackets
 =item $value = $term->resource ($name[, $newval])
 Returns the current resource value associated with a given name and
 optionally sets a new value. Setting values is most useful in the C<init>
   preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
   scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
   scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
   secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll
   term_name title transient_for transparent tripleclickwords urgentOnBell
-  utmpInhibit visualBell
+  utmpInhibit visualBell rewrapMode disablePasteBrackets
 =cut
 sub resource($$;$) {
    my ($self, $name) = (shift, shift);
    my $res = &x_resource;
    $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0
 }
+=item $action = $term->lookup_keysym ($keysym, $state)
+Returns the action bound to key combination C<($keysym, $state)>,
+if a binding for it exists, and C<undef> otherwise.
 =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.
 This method returns an urxvt::overlay object. The overlay will be visible
 as long as the perl object is referenced.
 The methods currently supported on C<urxvt::overlay> objects are:
-=over 4
+=over
 =item $overlay->set ($x, $y, $text[, $rend])
 Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
 text in rxvt-unicode's special encoding and an array of rendition values
 =item $term->key_release ($state, $keycode[, $time])
 Deliver various fake events to to terminal.
-=item $window_width = $term->width
+=item $window_width = $term->width ([$new_value])
-=item $window_height = $term->height
+=item $window_height = $term->height ([$new_value])
-=item $font_width = $term->fwidth
+=item $font_width = $term->fwidth ([$new_value])
-=item $font_height = $term->fheight
+=item $font_height = $term->fheight ([$new_value])
-=item $font_ascent = $term->fbase
+=item $font_ascent = $term->fbase ([$new_value])
-=item $terminal_rows = $term->nrow
+=item $terminal_rows = $term->nrow ([$new_value])
-=item $terminal_columns = $term->ncol
+=item $terminal_columns = $term->ncol ([$new_value])
-=item $has_focus = $term->focus
+=item $has_focus = $term->focus ([$new_value])
-=item $is_mapped = $term->mapped
+=item $is_mapped = $term->mapped ([$new_value])
-=item $max_scrollback = $term->saveLines
+=item $max_scrollback = $term->saveLines ([$new_value])
-=item $nrow_plus_saveLines = $term->total_rows
+=item $nrow_plus_saveLines = $term->total_rows ([$new_value])
-=item $topmost_scrollback_row = $term->top_row
+=item $topmost_scrollback_row = $term->top_row ([$new_value])
-Return various integers describing terminal characteristics.
+Return various integers describing terminal characteristics. If an
+argument is given, changes the value and returns the previous one.
 =item $x_display = $term->display_id
 Return the DISPLAY used by rxvt-unicode.
 =item $cursor_is_hidden = $term->hidden_cursor
 Returns whether the cursor is currently hidden or not.
+=item $priv_modes = $term->priv_modes
+Returns a bitset with the state of DEC private modes.
+Example:
+  if ($term->priv_modes & urxvt::PrivMode_mouse_report) {
+      # mouse reporting is turned on
+  }
 =item $view_start = $term->view_start ([$newvalue])
-Returns the row number of the topmost displayed line. Maximum value is
+Returns the row number of the topmost displayed line and changes it,
-C<0>, which displays the normal terminal contents. Lower values scroll
+if an argument is given. Values greater than or equal to C<0> display
-this many lines into the scrollback buffer.
+the terminal contents. Lower values scroll this many lines into the
+scrollback buffer.
 =item $term->want_refresh
 Requests a screen refresh. At the next opportunity, rxvt-unicode will
 compare the on-screen display with its stored representation. If they
 Create and return a new C<urxvt::line> object that stores information
 about the logical line that row C<$row_number> is part of. It supports the
 following methods:
-=over 4
+=over
 =item $text = $line->t ([$new_text])
 Returns or replaces the full text of the line, similar to C<ROW_t>
 package urxvt::popup;
 =head2 The C<urxvt::popup> Class
-=over 4
+=over
 =cut
 sub add_item {
    my ($self, $item) = @_;
                     ->cb (sub {
                        $term->{overlay}->set (0, 0,
                           sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
                     });
-=over 4
+=over
 =item $timer = new urxvt::timer
 Create a new timer object in started state. It is scheduled to fire
 immediately.
                    sysread $term->{socket}, my $buf, 8192
                       or end-of-file;
                  });
-=over 4
+=over
 =item $iow = new urxvt::iow
 Create a new io watcher object in stopped state.
 This class implements idle watchers, that get called automatically when
 the process is idle. They should return as fast as possible, after doing
 some useful work.
-=over 4
+=over
 =item $iw = new urxvt::iw
 Create a new idle watcher object in stopped state.
                     ->cb (sub {
                        my ($pw, $exit_status) = @_;
                        ...
                     });
-=over 4
+=over
 =item $pw = new urxvt::pw
 Create a new process watcher in stopped state.
 =head2 URXVT_PERL_VERBOSITY
 This variable controls the verbosity level of the perl extension. Higher
 numbers indicate more verbose output.
-=over 4
+=over
 =item == 0 - fatal messages
 =item >= 3 - script loading and management

Diff Legend

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

Comparing rxvt-unicode/src/urxvt.pm (file contents): Revision 1.253 by sf-exg, Fri Jan 16 20:13:01 2015 UTC vs. Revision 1.265 by root, Sat Jul 24 09:48:43 2021 UTC

Diff Legend

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.253 by sf-exg, Fri Jan 16 20:13:01 2015 UTC vs.
Revision 1.265 by root, Sat Jul 24 09:48:43 2021 UTC