=pod

=head1 NAME

uberprompt.pl

=head1 DESCRIPTION

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

=head1 INSTALLATION

Copy into your F<~/.irssi/scripts/> directory and load with
C</SCRIPT LOAD F<filename>>.

It is recommended that you make it autoload in one of the
L<usual ways|https://github.com/shabble/irssi-docs/wiki/Guide#Autorunning_Scripts>.

=head1 SETUP

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

=head1 USAGE

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

=over 4

=item * C</prompt set [-inner|-pre|-post|only] E<lt>msgE<gt>>

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

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

=item * C</prompt clear>

Clears the additional data provided to the prompt.

=item * C</prompt on>

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

=item * C</prompt off>

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

=item * C</help prompt>

show help for uberprompt commands

=back

=head1 SETTINGS

=head2 UBERPROMPT FORMAT

C</set uberprompt_format E<lt>formatE<gt>>

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

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

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

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

B<Note:> This setting completely overrides the C<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.

=head2 OTHER SETTINGS

=over 4

=item * C<uberprompt_autostart>

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

=item * C<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.

=item * C<uberprompt_format>

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

=item * C<uberprompt_load_hook>

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

C</set uberprompt_load_hook /echo prompt enabled> or

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

=item * C<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 C</prompt off>.

=item * C<uberprompt_use_replaces>

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

=back

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

=head2 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 C<"change prompt">
signal.

For Example:

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

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

The possible position arguments are the following strings:

=over 4

=item * C<UP_PRE>   - place the provided string before the prompt - C<$string$prompt>

=item * C<UP_INNER> - place the provided string inside the prompt - C<{prompt $* $string}>

=item * C<UP_POST>  - place the provided string after the prompt  - C<$prompt$string>

=item * C<UP_ONLY>  - replace the prompt with the provided string - C<$string>

=back

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

=head2 CHANGE NOTIFICATIONS

You can also be notified when the prompt changes in response to the previous
signal or manual C</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.


=head2 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.

I<---- 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(" ", @_);
    }

I<---- end of snippet ---->

=head1 AUTHORS

Copyright E<copy> 2011 Tom Feist C<E<lt>shabble+irssi@metavore.orgE<gt>>

=head1 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.

=head1 BUGS

=over 4

=item * 

Resizing the terminal rapidly whilst using this script in debug mode may cause
irssi to crash. See bug report at http://bugs.irssi.org/index.php?do=details&task_id=772 for details.

=back

=head1 TODO

=over 4

=item * report failure (somehow) to clients if hte prompt is disabled.

=item * fix issue at autorun startup with sbar item doesn't exist.

=back



=cut