Skip to content
This repository
README.pod

NAME

uberprompt.pl

DESCRIPTION

This script replaces the default prompt status-bar item with one capable of displaying additional information, under either user control or via scripts.

INSTALLATION

Copy into your ~/.irssi/scripts/ directory and load with /SCRIPT LOAD filename.

It is recommended that you make it autoload in one of the usual ways.

SETUP

If you have a custom prompt format, you may need to copy it to the uberprompt_format setting. See below for details.

USAGE

Although the script is designed primarily for other scripts to set status information into the prompt, the following commands are available:

  • /prompt set [-inner|-pre|-post|only] <msg>

    Sets the prompt to the given argument. Any use of $p in the argument will be replaced by the original prompt content.

    A parameter corresponding to the UP_* constants listed below is required, in the format /prompt set -inner Hello!

  • /prompt clear

    Clears the additional data provided to the prompt.

  • /prompt on

    Eenables the uberprompt (things may get confused if this is used whilst the prompt is already enabled)

  • /prompt off

    Restore the original irssi prompt and prompt_empty statusbars. unloading the script has the same effect.

  • /help prompt

    show help for uberprompt commands

SETTINGS

UBERPROMPT FORMAT

/set uberprompt_format <format>

The default is [$*$uber], which is the same as the default provided in default.theme.

Changing this setting will update the prompt immediately, unlike editing your theme.

An additional variable available within this format is $uber, which expands to the content of prompt data provided with the UP_INNER or /prompt set -inner placement argument.

For all other placement arguments, it will expand to the empty string.

Note: This setting completely overrides the prompt="..."; line in your .theme file, and may cause unexpected behaviour if your theme wishes to set a different form of prompt. It can be simply copied from the theme file into the above setting.

OTHER SETTINGS

  • uberprompt_autostart

    Boolean value, which determines if uberprompt should enable itself automatically upon loading. If Off, it must be enabled manually with /prompt on. Defaults to On.

  • uberprompt_debug

    Boolean value, which determines if uberprompt should print debugging information. Defaults to Off, and should probably be left that way unless requested for bug-tracing purposes.

  • uberprompt_format

    String value containing the format-string which uberprompt uses to display the prompt. Defaults to "[$*$uber] ", where $* is the content the prompt would normally display, and $uber is a placeholder variable for dynamic content, as described in the section above.

  • uberprompt_load_hook

    String value which can contain one or more commands to be run whenever the uberprompt is enabled, either via autostart, or /prompt on. Defaults to the empty string, in which case no commands are run. Some examples include:

    /set uberprompt_load_hook /echo prompt enabled or

    /^sbar prompt add -after input vim_mode for those using vim_mode.pl who want the command status indicator on the prompt line.

  • uberprompt_unload_hook

    String value, defaulting to the empty string, which can contain commands which are executed when the uberprompt is disabled, either by unloading the script, or by the command /prompt off.

  • uberprompt_use_replaces

    Boolean value, defaults to Off. If enabled, the format string for the prompt will be subject to the replaces section of the theme. The most obvious effect of this is that bracket characters [ ] are displayed in a different colour, typically quite dark.

Note: For both uberprompt_*_hook settings above, multiple commands can be chained together in the form /eval /^cmd1 ; /^cmd2. The ^ prevents any output from the commands (such as error messages) being displayed.

SCRIPTING USAGE

The primary purpose of uberprompt is to be used by other scripts to display information in a way that is not possible by printing to the active window or using statusbar items.

The content of the prompt can be set from other scripts via the "change prompt" signal.

For Example:

    signal_emit 'change prompt' 'some_string', UberPrompt::UP_INNER;

will set the prompt to include that content, by default '[$* some_string]'

The possible position arguments are the following strings:

  • UP_PRE - place the provided string before the prompt - $string$prompt
  • UP_INNER - place the provided string inside the prompt - {prompt $* $string}
  • UP_POST - place the provided string after the prompt - $prompt$string
  • UP_ONLY - replace the prompt with the provided string - $string

All strings may use the special variable '$prompt' to include the prompt verbatim at that position in the string. It is probably only useful for the UP_ONLY mode however. '$prompt_nt' will include the prompt, minus any trailing whitespace.

CHANGE NOTIFICATIONS

You can also be notified when the prompt changes in response to the previous signal or manual /prompt commands via:

    signal_add 'prompt changed', sub { my ($text, $len) = @_; ... do something ... };

This callback will occur whenever the contents of the prompt is changed.

NOTES FOR SCRIPT WRITERS:

The following code snippet can be used within your own script as a preamble to ensure that uberprompt is loaded before your script to avoid any issues with loading order. It first checks if uberprompt is loaded, and if not, attempts to load it. If the load fails, the script will die with an error message, otherwise it will call your app_init() function.

---- start of snippet ----

    my $DEBUG_ENABLED = 0;
    sub DEBUG () { $DEBUG_ENABLED }

    # check we have uberprompt loaded.

    sub script_is_loaded {
       return exists($Irssi::Script::{$_[0] . '::'});
    }

    if (not script_is_loaded('uberprompt')) {

        print "This script requires 'uberprompt.pl' in order to work. "
          . "Attempting to load it now...";

        Irssi::signal_add('script error', 'load_uberprompt_failed');
        Irssi::command("script load uberprompt.pl");

        unless(script_is_loaded('uberprompt')) {
            load_uberprompt_failed("File does not exist");
        }
        app_init();
    } else {
        app_init();
    }

    sub load_uberprompt_failed {
        Irssi::signal_remove('script error', 'load_uberprompt_failed');

        print "Script could not be loaded. Script cannot continue. "
          . "Check you have uberprompt.pl installed in your path and "
            .  "try again.";

        die "Script Load Failed: " . join(" ", @_);
    }

---- end of snippet ----

AUTHORS

Copyright © 2011 Tom Feist <shabble+irssi@metavore.org>

LICENCE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

BUGS

TODO

  • report failure (somehow) to clients if hte prompt is disabled.
  • fix issue at autorun startup with sbar item doesn't exist.
Something went wrong with that request. Please try again.