1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
=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
|
