source: perl/lib/BarnOwl.pm @ ee183be

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