From ce375dbf92cd89780138cff01deae6fbefb71cf6 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 15:42:10 +0100 Subject: updated a whole bunch of README files. --- prompt_info/README.pod | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 prompt_info/README.pod (limited to 'prompt_info/README.pod') diff --git a/prompt_info/README.pod b/prompt_info/README.pod new file mode 100644 index 0000000..e69de29 -- cgit v1.2.3 From 486aef8d31b80242c5e85951591f5063a0f47f63 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 16:27:37 +0100 Subject: added uberprompt readme --- prompt_info/README.pod | 221 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) (limited to 'prompt_info/README.pod') diff --git a/prompt_info/README.pod b/prompt_info/README.pod index e69de29..84b929b 100644 --- a/prompt_info/README.pod +++ b/prompt_info/README.pod @@ -0,0 +1,221 @@ + + +=cut + + + +=cut + + + +=cut + + + +=cut + +=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>. + +It is recommended that you make it autoload in one of the +L. + +=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] + +/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: + +CformatE> + +The default is C<[$*$uber]>, which is the same as the default provided in +F. + +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 or +placement argument. + +For all other placement arguments, it will expand to the empty string. + +B This setting completely overrides the C 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 - place the provided string before the prompt - C<$string$prompt> +=item * C - place the provided string inside the prompt - C<{prompt $* $string}> +=item * C - place the provided string after the prompt - C<$prompt$string> +=item * C - 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 mode however. '$C' 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 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 2011 Tom Feist Cshabble+irssi@metavore.orgE> + +=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 + + + +=cut + -- cgit v1.2.3 From d924883845fd6e2d1e0a9f63e91884b894eab6a8 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 16:34:34 +0100 Subject: uberprompt: updated readme --- prompt_info/README.pod | 214 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) (limited to 'prompt_info/README.pod') diff --git a/prompt_info/README.pod b/prompt_info/README.pod index 84b929b..547def6 100644 --- a/prompt_info/README.pod +++ b/prompt_info/README.pod @@ -217,5 +217,219 @@ irssi to crash. See bug report at http://bugs.irssi.org/index.php?do=details&tas +=cut + +=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>. + +It is recommended that you make it autoload in one of the +L. + +=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 * CmsgE> + +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 constants listed below is required, in +the format C + +=item * C + +Clears the additional data provided to the prompt. + +=item * C + +Eenables the uberprompt (things may get confused if this is used +whilst the prompt is already enabled) + +=item * C + +Restore the original irssi prompt and prompt_empty statusbars. unloading the +script has the same effect. + +=item * C + +show help for uberprompt commands + +=back + +=head1 UBERPROMPT FORMAT: + +CformatE> + +The default is C<[$*$uber]>, which is the same as the default provided in +F. + +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 or C +placement argument. + +For all other placement arguments, it will expand to the empty string. + +B This setting completely overrides the C 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 - place the provided string before the prompt - C<$string$prompt> +=item * C - place the provided string inside the prompt - C<{prompt $* $string}> +=item * C - place the provided string after the prompt - C<$prompt$string> +=item * C - 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 mode however. '$C' 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 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 2011 Tom Feist Cshabble+irssi@metavore.orgE> + +=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 -- cgit v1.2.3 From 0baf0dc985765733499a2e1a2e5f4bce988c2c55 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 16:37:44 +0100 Subject: uberprompt: rebuild docs AGAIN. :( --- prompt_info/README.pod | 226 ++----------------------------------------------- 1 file changed, 5 insertions(+), 221 deletions(-) (limited to 'prompt_info/README.pod') diff --git a/prompt_info/README.pod b/prompt_info/README.pod index 547def6..882553d 100644 --- a/prompt_info/README.pod +++ b/prompt_info/README.pod @@ -1,224 +1,3 @@ - - -=cut - - - -=cut - - - -=cut - - - -=cut - -=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>. - -It is recommended that you make it autoload in one of the -L. - -=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] - -/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: - -CformatE> - -The default is C<[$*$uber]>, which is the same as the default provided in -F. - -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 or -placement argument. - -For all other placement arguments, it will expand to the empty string. - -B This setting completely overrides the C 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 - place the provided string before the prompt - C<$string$prompt> -=item * C - place the provided string inside the prompt - C<{prompt $* $string}> -=item * C - place the provided string after the prompt - C<$prompt$string> -=item * C - 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 mode however. '$C' 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 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 2011 Tom Feist Cshabble+irssi@metavore.orgE> - -=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 - - - -=cut - =pod =head1 NAME @@ -318,10 +97,15 @@ The possible position arguments are the following strings: =over 4 =item * C - place the provided string before the prompt - C<$string$prompt> + =item * C - place the provided string inside the prompt - C<{prompt $* $string}> + =item * C - place the provided string after the prompt - C<$prompt$string> + =item * C - 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 mode however. '$C' will include the prompt, minus any -- cgit v1.2.3 From 3ae56e9a2fb9485ea62ce78883d22bac07531cd2 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 19:28:49 +0100 Subject: uberprompt: added documentation for all the uberprompt settings, including the new uberprompt_*_hook commands. Updated Readme. --- prompt_info/README.pod | 56 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) (limited to 'prompt_info/README.pod') diff --git a/prompt_info/README.pod b/prompt_info/README.pod index 882553d..d8e3b3e 100644 --- a/prompt_info/README.pod +++ b/prompt_info/README.pod @@ -57,7 +57,9 @@ show help for uberprompt commands =back -=head1 UBERPROMPT FORMAT: +=head1 SETTINGS + +=head2 UBERPROMPT FORMAT CformatE> @@ -77,6 +79,58 @@ B This setting completely overrides the C line in your different form of prompt. It can be simply copied from the theme file into the above setting. +=head2 OTHER SETTINGS + +=over 4 + +=item * C + +Boolean value, which determines if uberprompt should enable itself automatically +upon loading. If Off, it must be enabled manually with C. Defaults to On. + +=item * C + +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 + +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 + +String value which can contain one or more commands to be run whenever the uberprompt +is enabled, either via autostart, or C. Defaults to the empty string, in +which case no commands are run. Some examples include: + +C or + +C for those using vim_mode.pl who want +the command status indicator on the prompt line. + +=item * C + +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. + +=item * C + +Boolean value, defaults to Off. If enabled, the format string for the prompt +will be subject to the I 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 For both C settings above, multiple commands can +be chained together in the form C. 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 -- cgit v1.2.3