uberprompt: converted header comments to POD

1 files changed, 199 insertions, 171 deletions

diff --git a/prompt_info/uberprompt.pl b/prompt_info/uberprompt.pl
index 63cd958..adafee7 100644
--- a/prompt_info/uberprompt.pl
+++ b/prompt_info/uberprompt.pl
@@ -1,173 +1,201 @@
-# This script replaces the default prompt status-bar item with one capable
-# of displaying additional information, under either user control or via
-# scripts.
-#
-# INSTALL:
-#
-# Place script in ~/.irssi/scripts/ and potentially symlink into autorun/
-# to ensure it starts at irssi startup.
-#
-# If not using autorun, manually load the script via:
-#
-# /script load uberprompt.pl
-#
-# 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:
-#
-# TODO: Document positional settings.
-#
-# /prompt set   - sets the prompt to the given argument. $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 set [-inner|-pre|-post|only] <msg>
-#
-# /prompt clear - clears the additional data provided to the prompt.
-# /prompt on    - enables 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
-#
-# Additionally, the format for the prompt can be set via:
-#
-# UBERPROMPT FORMAT:
-#
-# /set uberprompt_format <format>
-#
-# The default is [$*$uber], which is the same as the default provided in
-# default.theme. $uber is a placeholder variable to contain your additions
-# to the prompt when using the -inner mode.
-# 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 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.
-#
-# Usage from other Scripts: signal 'change prompt' => 'string' => position
-#
-# eg:
-#
-# 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.
-#
-# NOTIFICATIONS:
-#
-# You can also be notified when the prompt changes in response to the previous
-# signal or manual commands via:
-#
-# signal_add 'prompt changed', sub { my ($text, $len) = @_; ... do something ... };
-#
-#
-# 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 load 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_prompt_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 ----
-#
-#
-#
-# Bugs:
-#
-# * 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.
-#
-# TODO:
-#
-# * report failure (somehow) to clients if hte prompt is disabled.
-# * fix issue at autorun startup with sbar item doesn't exist.
-#
-#
-#
-#
-# LICENCE:
-#
-# Copyright (c) 2010 Tom Feist
-#
-# 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.
+=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:
+
+TODO: Document positional settings.
+
+/prompt set   - sets the prompt to the given argument. $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 set [-inner|-pre|-post|only] <msg>
+
+/prompt clear - clears the additional data provided to the prompt.
+/prompt on    - enables 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
+
+=head1 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 </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 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>
+
+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_prompt_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
 
 use strict;
 use warnings;
@@ -176,7 +204,7 @@ use Irssi;
 use Irssi::TextUI;
 use Data::Dumper;
 
-{ package Irssi::Nick }
+{ package Irssi::Nick } # magic.
 
 our $VERSION = "0.2";
 our %IRSSI =