source: perl/lib/BarnOwl.pm @ 8eac1a5

release-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 8eac1a5 was 8eac1a5, checked in by Nelson Elhage <nelhage@mit.edu>, 12 years ago
Implement and test BarnOwl::Completion::Context. This is the class responsible for tokenizing the command-line for tab-completion.
  • Property mode set to 100644
File size: 8.9 KB
Line 
1use strict;
2use warnings;
3
4package BarnOwl;
5
6use base qw(Exporter);
7our @EXPORT_OK = qw(command getcurmsg getnumcols getidletime
8                    zephyr_getsender zephyr_getrealm zephyr_zwrite
9                    zephyr_stylestrip zephyr_smartstrip_user zephyr_getsubs
10                    queue_message admin_message
11                    start_question start_password start_edit_win
12                    get_data_dir get_config_dir popless_text popless_ztext
13                    error debug
14                    create_style getnumcolors wordwrap
15                    add_dispath remove_dispatch
16                    new_command
17                    new_variable_int new_variable_bool new_variable_string
18                    quote);
19our %EXPORT_TAGS = (all => \@EXPORT_OK);
20
21BEGIN {
22# bootstrap in C bindings and glue
23    *owl:: = \*BarnOwl::;
24    bootstrap BarnOwl 1.2;
25};
26
27use lib(get_data_dir() . "/lib");
28use lib(get_config_dir() . "/lib");
29
30use BarnOwl::Hook;
31use BarnOwl::Hooks;
32use BarnOwl::Message;
33use BarnOwl::Style;
34use BarnOwl::Timer;
35use BarnOwl::Editwin;
36use BarnOwl::Completion;
37
38=head1 NAME
39
40BarnOwl
41
42=head1 DESCRIPTION
43
44The BarnOwl module contains the core of BarnOwl's perl
45bindings. Source in this module is also run at startup to bootstrap
46barnowl by defining things like the default style.
47
48=for NOTE
49These following functions are defined in perlglue.xs. Keep the
50documentation here in sync with the user-visible commands defined
51there!
52
53=head2 command STRING
54
55Executes a BarnOwl command in the same manner as if the user had
56executed it at the BarnOwl command prompt. If the command returns a
57value, return it as a string, otherwise return undef.
58
59=head2 getcurmsg
60
61Returns the current message as a C<BarnOwl::Message> subclass, or
62undef if there is no message selected
63
64=head2 getnumcols
65
66Returns the width of the display window BarnOwl is currently using
67
68=head2 getidletime
69
70Returns the length of time since the user has pressed a key, in
71seconds.
72
73=head2 zephyr_getrealm
74
75Returns the zephyr realm barnowl is running in
76
77=head2 zephyr_getsender
78
79Returns the fully-qualified name of the zephyr sender barnowl is
80running as, e.g. C<nelhage@ATHENA.MIT.EDU>
81
82=head2 zephyr_zwrite COMMAND MESSAGE
83
84Sends a zephyr programmatically. C<COMMAND> should be a C<zwrite>
85command line, and C<MESSAGE> is the zephyr body to send.
86
87=head2 ztext_stylestrip STRING
88
89Strips zephyr formatting from a string and returns the result
90
91=head2 zephyr_getsubs
92
93Returns the list of subscription triples <class,instance,recipient>,
94separated by newlines.
95
96=head2 queue_message MESSAGE
97
98Enqueue a message in the BarnOwl message list, logging it and
99processing it appropriately. C<MESSAGE> should be an instance of
100BarnOwl::Message or a subclass.
101
102=head2 admin_message HEADER BODY
103
104Display a BarnOwl B<Admin> message, with the given header and body.
105
106=head2 start_question PROMPT CALLBACK
107
108Displays C<PROMPT> on the screen and lets the user enter a line of
109text, and calls C<CALLBACK>, which must be a perl subroutine
110reference, with the text the user entered
111
112=head2 start_password PROMPT CALLBACK
113
114Like C<start_question>, but echoes the user's input as C<*>s when they
115input.
116
117=head2 start_edit_win PROMPT CALLBACK
118
119Like C<start_question>, but displays C<PROMPT> on a line of its own
120and opens the editwin. If the user cancels the edit win, C<CALLBACK>
121is not invoked.
122
123=head2 get_data_dir
124
125Returns the BarnOwl system data directory, where system libraries and
126modules are stored
127
128=head2 get_config_dir
129
130Returns the BarnOwl user configuration directory, where user modules
131and configuration are stored (by default, C<$HOME/.owl>)
132
133=head2 popless_text TEXT
134
135Show a popup window containing the given C<TEXT>
136
137=head2 popless_ztext TEXT
138
139Show a popup window containing the provided zephyr-formatted C<TEXT>
140
141=head2 error STRING
142
143Reports an error and log it in `show errors'. Note that in any
144callback or hook called in perl code from BarnOwl, a C<die> will be
145caught and passed to C<error>.
146
147=head2 debug STRING
148
149Logs a debugging message to BarnOwl's debug log
150
151=head2 getnumcolors
152
153Returns the number of colors this BarnOwl is capable of displaying
154
155=head2 add_dispatch FD CALLBACK
156
157Adds a file descriptor to C<BarnOwl>'s internal C<select()>
158loop. C<CALLBACK> will be invoked whenever data is available to be
159read from C<FD>.
160
161=head2 remove_dispatch FD
162
163Remove a file descriptor previously registered via C<add_dispatch>
164
165=head2 create_style NAME OBJECT
166
167Creates a new barnowl style with the given NAME defined by the given
168object. The object must have a C<description> method which returns a
169string description of the style, and a and C<format_message> method
170which accepts a C<BarnOwl::Message> object and returns a string that
171is the result of formatting the message for display.
172
173=cut
174
175# perlconfig.c will set this to the value of the -c command-line
176# switch, if present.
177our $configfile;
178
179if(!$configfile && -f $ENV{HOME} . "/.barnowlconf") {
180    $configfile = $ENV{HOME} . "/.barnowlconf";
181}
182$configfile ||= $ENV{HOME}."/.owlconf";
183
184# populate global variable space for legacy owlconf files
185sub _receive_msg_legacy_wrap {
186    my ($m) = @_;
187    $m->legacy_populate_global();
188    return &BarnOwl::Hooks::_receive_msg($m);
189}
190
191=head2 new_command NAME FUNC [{ARGS}]
192
193Add a new owl command. When owl executes the command NAME, FUNC will
194be called with the arguments passed to the command, with NAME as the
195first argument.
196
197ARGS should be a hashref containing any or all of C<summary>,
198C<usage>, or C<description> keys:
199
200=over 4
201
202=item summary
203
204A one-line summary of the purpose of the command
205
206=item usage
207
208A one-line usage synopsis, showing available options and syntax
209
210=item description
211
212A longer description of the syntax and semantics of the command,
213explaining usage and options
214
215=back
216
217=cut
218
219sub new_command {
220    my $name = shift;
221    my $func = shift;
222    my $args = shift || {};
223    my %args = (
224        summary     => "",
225        usage       => "",
226        description => "",
227        %{$args}
228    );
229
230    BarnOwl::Internal::new_command($name, $func, $args{summary}, $args{usage}, $args{description});
231}
232
233=head2 new_variable_int NAME [{ARGS}]
234
235=head2 new_variable_bool NAME [{ARGS}]
236
237=head2 new_variable_string NAME [{ARGS}]
238
239Add a new owl variable, either an int, a bool, or a string, with the
240specified name.
241
242ARGS can optionally contain the following keys:
243
244=over 4
245
246=item default
247
248The default and initial value for the variable
249
250=item summary
251
252A one-line summary of the variable's purpose
253
254=item description
255
256A longer description of the function of the variable
257
258=back
259
260=cut
261
262sub new_variable_int {
263    unshift @_, \&BarnOwl::Internal::new_variable_int, 0;
264    goto \&_new_variable;
265}
266
267sub new_variable_bool {
268    unshift @_, \&BarnOwl::Internal::new_variable_bool, 0;
269    goto \&_new_variable;
270}
271
272sub new_variable_string {
273    unshift @_, \&BarnOwl::Internal::new_variable_string, "";
274    goto \&_new_variable;
275}
276
277sub _new_variable {
278    my $func = shift;
279    my $default_default = shift;
280    my $name = shift;
281    my $args = shift || {};
282    my %args = (
283        summary     => "",
284        description => "",
285        default     => $default_default,
286        %{$args});
287    $func->($name, $args{default}, $args{summary}, $args{description});
288}
289
290=head2 quote STRING
291
292Return a version of STRING fully quoted to survive processing by
293BarnOwl's command parser.
294
295=cut
296
297sub quote {
298    my $str = shift;
299    return "''" if $str eq '';
300    if ($str !~ /['" ]/) {
301        return "$str";
302    }
303    if ($str !~ /'/) {
304        return "'$str'";
305    }
306    $str =~ s/"/"'"'"/g;
307    return '"' . $str . '"';
308}
309
310=head2 Modify filters by appending text
311
312=cut
313
314BarnOwl::new_command("filterappend",
315    sub { filter_append_helper('appending', '', @_); },
316    {
317        summary => "append '<text>' to filter",
318        usage => "filterappend <filter> <text>",
319    });
320
321BarnOwl::new_command("filterand",
322    sub { filter_append_helper('and-ing', 'and', @_); },
323    {
324        summary => "append 'and <text>' to filter",
325        usage => "filterand <filter> <text>",
326    });
327
328BarnOwl::new_command("filteror",
329    sub { filter_append_helper('or-ing', 'or', @_); },
330    {
331        summary => "append 'or <text>' to filter",
332        usage => "filteror <filter> <text>",
333    });
334
335=head3 filter_append_helper ACTION SEP FUNC FILTER APPEND_TEXT
336
337Helper to append to filters.
338
339=cut
340
341sub filter_append_helper
342{
343    my $action = shift;
344    my $sep = shift;
345    my $func = shift;
346    my $filter = shift;
347    my @append = @_;
348    my $oldfilter = BarnOwl::getfilter($filter);
349    chomp $oldfilter;
350    my $newfilter = join(' ', $oldfilter, $sep, @_);
351    my $msgtext = "To filter '$filter' $action\n'".join(' ', @append)."' to get\n'$newfilter'";
352    if (BarnOwl::getvar('showfilterchange') eq 'on') {
353        BarnOwl::admin_message("Filter", $msgtext);
354    }
355    BarnOwl::filter($filter, $newfilter);
356    return;
357}
358BarnOwl::new_variable_bool("showfilterchange",
359                           { default => 1,
360                             summary => 'Show modifications to filters by filterappend and friends.'});
361
3621;
Note: See TracBrowser for help on using the repository browser.