--- rxvt-unicode/src/urxvt.pm 2012/07/14 08:00:34 1.224 +++ rxvt-unicode/src/urxvt.pm 2022/12/29 01:10:08 1.272 @@ -2,30 +2,30 @@ =head1 NAME -@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter +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 @@RXVT_NAME@@ using it: + # start a urxvt instance using it: - @@RXVT_NAME@@ --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 resource are loaded and associated with it. -Scripts are compiled in a 'use strict "vars"' and 'use utf8' environment, and -thus must be encoded as UTF-8. +Scripts are compiled in a 'use strict qw(vars subs)' and 'use utf8' +environment, and thus must be encoded as UTF-8. -Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where +Each script will only ever be loaded once, even in urxvtd, where scripts will be shared (but not enabled) for all terminals. You can disable the embedded perl interpreter by setting both "perl-ext" @@ -34,19 +34,25 @@ =head1 PREPACKAGED EXTENSIONS A number of extensions are delivered with this release. You can find them -in F<@@RXVT_LIBDIR@@/urxvt/perl/>, and the documentation can be viewed -using F<< man urxvt- >>. +in F<< /urxvt/perl/ >>, and the documentation can be viewed using +F<< man urxvt- >>. You can activate them like this: - @@RXVT_NAME@@ -pe + urxvt -pe Or by adding them to the resource for extensions loaded by default: 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, i.e., methods +which can be bound to a key and invoked by the user. An extension can +define the resources it support 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 define META +comments for its resources. =head1 API DOCUMENTATION @@ -66,7 +72,7 @@ Argument names also often indicate the type of a parameter. Here are some hints on what they mean: -=over 4 +=over =item $text @@ -108,6 +114,75 @@ Additional methods only supported for extension objects are described in the C section below. +=head2 META comments + +Rxvt-unicode recognizes special meta comments in extensions that define +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 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 + +The RESOURCE comment defines a resource used by the extension, where +C is the resource name, C is the resource type, C +or C, and C 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 resource by having this +comment: + + #:META:RESOURCE:%.launcher:string:default launcher command + +Example: load this extension when the C<-tr> command line option or +resource name is used. + + #:META:RESOURCE:tr:boolean:set root pixmap as background + +=item #:META:OSC:number:desc + +The OSC comment specifies an OSC sequence, where C is the +numerical OSC code and C is a short description that is currently +unused. + +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 cannot really protect itself against malicious +sources of command sequences, therefore relying on the programs running +I 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, +always consider whether OSC sequences are safe, autoloading automatically +exposes any autoloaded extension in all terminal windows, so extra care +should be taken. + +Example: the background extension registers OSC C<20> like this: + + #:META:OSC:20:change/query background image + +=item #:META:OSC_PERL:prefix:desc + +The same as the OSC comment, but for the Perl OSC sequence (C<777>). The +C should be unique among extensions, of course, which is most +easily arranged by using the extension name, although this is not +required. + +Example: the overlay-osc extension registers its Perl OSC like this: + + #:META:OSC_PERL:overlay:man overlay-osc + +=back + =head2 Hooks The following subroutines can be declared in extension files, and will be @@ -122,7 +197,19 @@ I<< When in doubt, return a false value (preferably C<()>). >> -=over 4 +=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. + +Unlike C or C, 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, which might not be called. =item on_init $term @@ -214,12 +301,12 @@ =item on_osc_seq_perl $term, $args, $resp -Called whenever the B command sequence (OSC = -operating system command) is processed. Cursor position and other state -information is up-to-date when this happens. For interoperability, the -string should start with the extension name (sans -osc) and a semicolon, -to distinguish it from commands for other extensions, and this might be -enforced in the future. +Called whenever the B command sequence +(OSC = operating system command) is processed. Cursor position and other +state information is up-to-date when this happens. For interoperability, +the argument should start with the extension name (sans -osc) or some +other suitable prefix, and a semicolon, to distinguish it from commands +for other extensions. For example, C uses this: @@ -283,27 +370,28 @@ Called just after the screen gets redrawn. See C. -=item on_user_command $term, $string +=item on_action $term, $string -Called whenever a user-configured event is being activated (e.g. via -a C action bound to a key, see description of the B -resource in the @@RXVT_NAME@@(1) manpage). +Called whenever an action is invoked for the corresponding extension +(e.g. via a C builtin action bound to a key, see +description of the B 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. -The event is simply the action string. This interface is assumed to change -slightly in the future. +=item on_user_command $term, $string *DEPRECATED* -=item on_register_command $term, $keysym, $modifiermask, $string +Called whenever a user-configured event is being activated (e.g. via +a C action bound to a key, see description of the B +resource in the urxvt(1) manpage). -Called after parsing a keysym resource but before registering the -associated binding. If this hook returns TRUE the binding is not -registered. It can be used to modify a binding by calling -C. +The event is simply the action string. This interface is going away in +preference to the C hook. =item on_resize_all_windows $term, $new_width, $new_height Called just after the new window size has been calculated, but before windows are actually being resized or hints are being set. If this hook -returns TRUE, setting of the window hints is being skipped. +returns a true value, setting of the window hints is being skipped. =item on_x_event $term, $event @@ -353,8 +441,6 @@ C additionally receives the string rxvt-unicode would output, if any, in locale-specific encoding. -subwindow. - =item on_client_message $term, $event =item on_wm_protocols $term, $event @@ -375,7 +461,7 @@ package urxvt; use utf8; -use strict 'vars'; +use strict qw(vars subs); use Carp (); use Scalar::Util (); use List::Util (); @@ -397,7 +483,7 @@ =head2 Variables in the C Package -=over 4 +=over =item $urxvt::LIBDIR @@ -437,7 +523,7 @@ =head2 Functions in the C Package -=over 4 +=over =item urxvt::fatal $errormessage @@ -492,6 +578,18 @@ 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 @@ -504,7 +602,7 @@ as they contain important information required for correct operation of rxvt-unicode. -=over 4 +=over =item $rend = urxvt::DEFAULT_RSTYLE @@ -566,22 +664,28 @@ sub parse_resource { my ($term, $name, $isarg, $longopt, $flag, $value) = @_; - $name =~ y/-/./ if $isarg; - - $term->scan_meta; + $term->scan_extensions; + # iterating over all resources has quadratic time overhead + # overall, maybe this could be optimised? my $r = $term->{meta}{resource}; - keys %$r; # reste iterator - while (my ($pattern, $v) = each %$r) { - if ( - $pattern =~ /\.$/ - ? $pattern eq substr $name, 0, length $pattern - : $pattern eq $name - ) { - $name = "$urxvt::RESCLASS.$name"; + keys %$r; # reset iterator + 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]; + return 1 unless $isarg; + if ($v->[1] eq "boolean") { $term->put_option_db ($name, $flag ? "true" : "false"); return 1; @@ -598,7 +702,7 @@ sub usage { my ($term, $usage_type) = @_; - $term->scan_meta; + $term->scan_extensions; my $r = $term->{meta}{resource}; @@ -623,7 +727,7 @@ } } -my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; +my $verbosity = $ENV{URXVT_PERL_VERBOSITY} // 2; sub verbose { my ($level, $msg) = @_; @@ -650,7 +754,7 @@ or die "$path: $!"; my $source = - "package $pkg; use strict 'vars'; use utf8; no warnings 'utf8';\n" + "package $pkg; use strict qw(vars subs); use utf8; no warnings 'utf8';\n" . "#line 1 \"$path\"\n{\n" . (do { local $/; <$fh> }) . "\n};\n1"; @@ -669,8 +773,8 @@ local $TERM = shift; my $htype = shift; - if ($htype == 0) { # INIT - my @dirs = $TERM->perl_libdirs; + if ($htype == HOOK_INIT) { + $TERM->scan_extensions; my %ext_arg; @@ -685,26 +789,47 @@ for ( @{ delete $TERM->{perl_ext_3} }, - grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2 + (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2), ) { if ($_ eq "default") { - $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback readline); - } elsif (/^-(.*)$/) { + + $ext_arg{$_} = [] + 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_\-]+):/; + + my $ext = $1; + + $ext_arg{$ext} = []; + } + + } elsif (/^-(.*)$/) { # remove from set delete $ext_arg{$1}; - } elsif (/^([^<]+)<(.*)>$/) { - push @{ $ext_arg{$1} }, $2; + + } elsif (/^\/(.*)$/) { # prohibit loading + undef $TERM->{ext_prohibit}{$1}; + + } elsif (/^([^<]+)(?:<(.*)>)?$/) { # add to set, clear prohibit status + delete $TERM->{ext_prohibit}{$1}; + push @{ $ext_arg{$1} }, defined $2 ? $2 : (); + } else { - $ext_arg{$_} ||= []; + verbose 2, "cannot parse extension specification '$_', ignoring."; } } + $TERM->set_should_invoke (HOOK_OSC_SEQ , +1) if $TERM->{meta}{autoload_osc}; + $TERM->set_should_invoke (HOOK_OSC_SEQ_PERL, +1) if $TERM->{meta}{autoload_osc_perl}; + for my $ext (sort keys %ext_arg) { - my @files = grep -f $_, map "$_/$ext", @dirs; + my $path = $TERM->extension_path ($ext); - if (@files) { - $TERM->register_package (extension_package $files[0], $ext_arg{$ext}); + if (defined $path) { + $TERM->autoload_extension ($ext, $ext_arg{$ext}); } else { - warn "perl extension '$ext' not found in perl library search path\n"; + verbose 2, "perl extension '$ext' not found in perl library search path"; } } @@ -712,12 +837,35 @@ warn $@ if $@; } + 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; + if ($htype == HOOK_ACTION) { + # this hook is only sent to the extension with the name + # matching the first arg + my $pkg = shift; + $pkg =~ y/-/_/; + $pkg = "urxvt::ext::$pkg"; + + $cb = $cb->{$pkg} + or return undef; #TODO: maybe warn user? + + $cb = { $pkg => $cb }; + } + for my $pkg (keys %$cb) { my $retval_ = eval { $cb->{$pkg}->($TERM->{_pkg}{$pkg} || $TERM, @_) }; $retval ||= $retval_; @@ -732,7 +880,7 @@ if $verbosity >= 11; } - if ($htype == 1) { # DESTROY + if ($htype == HOOK_DESTROY) { # clear package objects %$_ = () for values %{ $TERM->{_pkg} }; @@ -786,7 +934,7 @@ objects, in addition to call methods documented for the class. -=over 4 +=over =item $urxvt_term = $self->{term} @@ -829,8 +977,11 @@ =item $self->enable ($hook_name => $cb[, $hook_name => $cb..]) Dynamically enable the given hooks (named without the C prefix) for -this extension, replacing any previous hook. This is useful when you want -to overwrite time-critical hooks only temporarily. +this extension, replacing any hook previously installed via C in +this extension. + +This is useful when you want to overwrite time-critical hooks only +temporarily. To install additional callbacks for the same hook, you can use the C method of the C class. @@ -911,16 +1062,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 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 methods of the same name - see the description of these +methods in the C 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/; @@ -1025,7 +1185,7 @@ =head2 The C Class -=over 4 +=over =cut @@ -1034,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"; @@ -1054,6 +1216,35 @@ $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 filesystem path +sub extension_path { + (grep -f $_, map "$_/$_[1]", $_[0]->perl_libdirs)[0] +} + +# load an extension by name +sub load_extension_file { + my ($self, $path, $argv) = @_; + + $self->register_package (urxvt::extension_package $path, $argv); +} + +# autoload an extension unless loading it is prohibited +sub autoload_extension { + my ($self, $name, $argv) = @_; + + return if exists $self->{ext_prohibit}{$name}; + + my $path = $self->extension_path ($name) + // return urxvt::verbose 2, "perl extension '$name' not found in perl library search path (during autoload)"; + + $self->load_extension_file ($path, $argv); } sub perl_libdirs { @@ -1064,28 +1255,42 @@ "$LIBDIR/perl" } -sub scan_meta { +# scan for available extensions and collect their metadata +sub scan_extensions { my ($self) = @_; - my @libdirs = perl_libdirs $self; - return if $self->{meta_libdirs} eq join "\x00", @libdirs; + return if exists $self->{meta}; - my %meta; + my @urxvtdirs = perl_libdirs $self; +# my @cpandirs = grep -d, map "$_/URxvt/Ext", @INC; - $self->{meta_libdirs} = join "\x00", @libdirs; - $self->{meta} = \%meta; + $self->{meta} = \my %allmeta; + + # first gather extensions + + my $gather = sub { + my ($dir, $core) = @_; - for my $dir (reverse @libdirs) { opendir my $fh, $dir - or next; + or return; + for my $ext (readdir $fh) { - $ext ne "." - and $ext ne ".." - and open my $fh, "<", "$dir/$ext" + $ext !~ /^\./ + or next; + + open my $fh, "<", "$dir/$ext" + or next; + + -f $fh + or next; + + $ext =~ s/\.uext$// or $core or next; + my %meta = (dir => $dir); + while (<$fh>) { - if (/^#:META:X_RESOURCE:(.*)/) { + if (/^#:META:(?:X_)?RESOURCE:(.*)/) { my ($pattern, $type, $desc) = split /:/, $1; $pattern =~ s/^%(\.|$)/$ext$1/g; # % in pattern == extension name if ($pattern =~ /[^a-zA-Z0-9\-\.]/) { @@ -1093,13 +1298,35 @@ } else { $meta{resource}{$pattern} = [$ext, $type, $desc]; } + + } elsif (/^#:META:OSC:([0-9]+):(.*)/) { + push @{$allmeta{autoload_osc}{$1}}, [$ext, $2]; + + } elsif (/^#:META:OSC_PERL:([^:]+):(.*)/) { + push @{$allmeta{autoload_osc_perl}{$1}}, [$ext, $2]; + } elsif (/^\s*(?:#|$)/) { # skip other comments and empty lines + } else { last; # stop parsing on first non-empty non-comment line } } + + $allmeta{ext}{$ext} = \%meta; } + }; + +# $gather->($_, 0) for @cpandirs; + $gather->($_, 1) for @urxvtdirs; + + # and now merge resources + + $allmeta{resource} = \my %resource; + + while (my ($k, $v) = each %{ $allmeta{ext} }) { + #TODO: should check for extensions overriding each other + %resource = (%resource, %{ $v->{resource} }); } } @@ -1129,7 +1356,7 @@ =item $term->destroy Destroy the terminal object (close the window, free resources -etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event +etc.). Please note that urxvt will not exit as long as any event watchers (timers, io watchers) are still active. =item $term->exec_async ($cmd[, @args]) @@ -1139,6 +1366,10 @@ the user environment before exec'ing the command (e.g. C) and should be preferred over explicit calls to C or C. +It also sets the C environment variable to the window +ID of the terminal (C<< $self->parent >>), similar to the C +variable set for the process spawned inside the terminal. + Returns the pid of the subprocess or C on error. =cut @@ -1151,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; @@ -1172,7 +1406,7 @@ 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]) @@ -1208,7 +1442,7 @@ scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle secondaryScreen secondaryScroll shade skipBuiltinGlyphs skipScroll term_name title transient_for transparent tripleclickwords urgentOnBell - utmpInhibit visualBell + utmpInhibit visualBell rewrapMode disablePasteBrackets =cut @@ -1225,15 +1459,15 @@ same value as used by this instance of rxvt-unicode. Returns C 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 hook, as there is only one resource database per display, and later invocations might return @@ -1255,17 +1489,30 @@ $res =~ /^\s*(?:true|yes|on|1)\s*$/i ? 1 : defined $res && 0 } -=item $success = $term->parse_keysym ($key, $octets) +=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 otherwise. + +=item $success = $term->bind_action ($key, $action) -Adds a key binding exactly as specified via a resource. See the -C resource in the @@RXVT_NAME@@(1) manpage. +Adds a key binding exactly as specified via a C resource. See the +C resource in the urxvt(1) manpage. -=item $term->register_command ($keysym, $modifiermask, $string) +To add default bindings for actions, an extension should call C<< +->bind_action >> in its C hook for every such binding. Doing it +in the C hook allows users to override or remove the binding +again. -Adds a key binding. This is a lower level api compared to -C, as it expects a parsed key description, and can be -used only inside either the C hook, to add a binding, or the -C hook, to modify a parsed binding. +Example: the C by default binds itself +on C, 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]) @@ -1352,7 +1599,7 @@ The methods currently supported on C objects are: -=over 4 +=over =item $overlay->set ($x, $y, $text[, $rend]) @@ -1406,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 if C<$string> is C. =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 if C<$octets> is C. =item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) @@ -1433,8 +1682,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 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 @@ -1452,9 +1702,18 @@ =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 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) + +Like C, but should be used when writing strings in response to +the user pressing a key, to invoke the additional actions requested by +the user for that case (C doesn't do that). + +The typical use case would be inside C hooks. =item $term->tt_paste ($octets) @@ -1503,31 +1762,32 @@ 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 @@ -1574,11 +1834,22 @@ 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 -C<0>, which displays the normal terminal contents. Lower values scroll -this many lines into the scrollback buffer. +Returns the row number of the topmost displayed line and changes it, +if an argument is given. Values greater than or equal to C<0> display +the terminal contents. Lower values scroll this many lines into the +scrollback buffer. =item $term->want_refresh @@ -1588,6 +1859,10 @@ Used after changing terminal contents to display them. +=item $term->refresh_check + +Checks if a refresh has been requested and, if so, schedules one. + =item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) Returns the text of the entire row with number C<$row_number>. Row C<< $term->top_row >> @@ -1642,7 +1917,7 @@ 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]) @@ -1698,11 +1973,10 @@ sub urxvt::line::t { my ($self) = @_; - if (@_ > 1) - { - $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) - for $self->{beg} .. $self->{end}; - } + if (@_ > 1) { + $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) + for $self->{beg} .. $self->{end}; + } defined wantarray && substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), @@ -1712,11 +1986,10 @@ sub urxvt::line::r { my ($self) = @_; - if (@_ > 1) - { - $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) - for $self->{beg} .. $self->{end}; - } + if (@_ > 1) { + $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol}) + for $self->{beg} .. $self->{end}; + } if (defined wantarray) { my $rend = [ @@ -1750,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]) @@ -1834,7 +2107,7 @@ =head2 The C Class -=over 4 +=over =cut @@ -1980,7 +2253,7 @@ sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); }); -=over 4 +=over =item $timer = new urxvt::timer @@ -2039,7 +2312,7 @@ }); -=over 4 +=over =item $iow = new urxvt::iow @@ -2076,7 +2349,7 @@ the process is idle. They should return as fast as possible, after doing some useful work. -=over 4 +=over =item $iw = new urxvt::iw @@ -2111,7 +2384,7 @@ ... }); -=over 4 +=over =item $pw = new urxvt::pw @@ -2138,9 +2411,11 @@ This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output. -=over 4 +=over + +=item == 0 - fatal messages only -=item == 0 - fatal messages +=item >= 2 - general warnings (default level) =item >= 3 - script loading and management