source: perl/lib/BarnOwl.pm @ fc92548d

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