source: perl/lib/BarnOwl.pm @ eb6cedc

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