source: perl/lib/BarnOwl/Logging.pm @ 9367711

Last change on this file since 9367711 was 9367711, checked in by Jason Gross <jgross@mit.edu>, 9 years ago
Add a comment about existence of logging dirs
  • Property mode set to 100644
File size: 8.3 KB
Line 
1use strict;
2use warnings;
3
4package BarnOwl::Logging;
5
6=head1 BarnOwl::Logging
7
8=head1 DESCRIPTION
9
10C<BarnOwl::Logging> implements the internals of logging.  All customizations
11to logging should be done in the appropriate subclass of L<BarnOwl::Message>.
12
13=head2 USAGE
14
15Modules wishing to customize how messages are logged should override the
16relevant subroutines in the appropriate subclass of L<BarnOwl::Message>.
17
18Modules wishing to log errors sending outgoing messages should call
19L<BarnOwl::Logging::log_outgoing_error> with the message that failed
20to be sent.
21
22=head2 EXPORTS
23
24None by default.
25
26=cut
27
28use Exporter;
29
30our @EXPORT_OK = qw();
31
32our %EXPORT_TAGS = (all => [@EXPORT_OK]);
33
34use File::Spec;
35
36$BarnOwl::Hooks::newMessage->add("BarnOwl::Logging::log");
37$BarnOwl::Hooks::startup->add("BarnOwl::Logging::_register_variables");
38
39sub _register_variables {
40    BarnOwl::new_variable_bool('logging',
41        {
42            default     => 0,
43            summary     => 'turn personal logging on or off',
44            description => "If this is set to on, personal messages are\n"
45                         . "logged in the directory specified\n"
46                         . "by the 'logpath' variable.  The filename in that\n"
47                         . "directory is derived from the sender of the message."
48        });
49
50    BarnOwl::new_variable_bool('classlogging',
51        {
52            default     => 0,
53            summary     => 'turn class logging on or off',
54            description => "If this is set to on, class messages are\n"
55                         . "logged in the directory specified by the\n"
56                         . "'classpath' variable.  The filename in that\n"
57                         . "directory is derived from the class to which\n"
58                         . "the message was sent."
59        });
60
61    BarnOwl::new_variable_string('logfilter',
62        {
63            default     => '',
64            summary     => 'name of a filter controlling which messages to log',
65            description => "If non empty, any messages matching the given filter will be logged.\n"
66                         . "This is a completely separate mechanism from the other logging\n"
67                         . "variables like logging, classlogging, loglogins, loggingdirection,\n"
68                         . "etc.  If you want this variable to control all logging, make sure\n"
69                         . "all other logging variables are in their default state."
70        });
71
72    BarnOwl::new_variable_bool('loglogins',
73        {
74            default     => 0,
75            summary     => 'enable logging of login notifications',
76            description => "When this is enabled, BarnOwl will log login and logout notifications\n"
77                         . "for AIM, zephyr, or other protocols.  If disabled BarnOwl will not print\n"
78                         . "login or logout notifications."
79        });
80
81    BarnOwl::new_variable_enum('loggingdirection',
82        {
83            default       => 'both',
84            validsettings => [qw(in out both)],
85            summary       => "specifies which kind of messages should be logged",
86            description   => "Can be one of 'both', 'in', or 'out'.  If 'in' is\n"
87                           . "selected, only incoming messages are logged, if 'out'\n"
88                           . "is selected only outgoing messages are logged.  If 'both'\n"
89                           . "is selected both incoming and outgoing messages are\n"
90                           . "logged."
91        });
92
93    BarnOwl::new_variable_string('logbasepath',
94        {
95            default       => '~/zlog',
96            validsettings => '<path>',
97            summary       => 'path for logging non-zephyr messages',
98            description   => "Specifies a directory which must exist.\n"
99                           . "Each non-zephyr protocol gets its own subdirectory in\n"
100                           . "logbasepath, and messages get logged there.  Note that\n"
101                           . "if the directory logbasepath/\$protocol does not exist,\n"
102                           . "logging will fail for \$protocol."
103        });
104
105    BarnOwl::new_variable_string('logpath',
106        {
107            default       => '~/zlog/people',
108            validsettings => '<path>',
109            summary       => 'path for logging personal messages',
110            description   => "Specifies a directory which must exist.\n"
111                            . "Files will be created in the directory for each sender."
112        });
113
114    BarnOwl::new_variable_string('classlogpath',
115        {
116            default       => '~/zlog/class',
117            validsettings => '<path>',
118            summary       => 'path for logging class zephyrs',
119            description   => "Specifies a directory which must exist.\n"
120                           . "Files will be created in the directory for each class."
121        });
122}
123
124=head2 sanitize_filename BASE_PATH FILENAME
125
126Sanitizes C<FILENAME> and concatenates it with C<BASE_PATH>.
127
128In any filename, C<"/"> and any control characters (characters which
129match C<[:cntrl:]> get replaced by underscores.  If the resulting
130filename is empty or equal to C<"."> or C<"..">, it is replaced with
131C<"weird">.
132
133=cut
134
135sub sanitize_filename {
136    my $base_path = BarnOwl::Internal::makepath(shift);
137    my $filename = shift;
138    $filename =~ s/[[:cntrl:]\/]/_/g;
139    if ($filename eq '' || $filename eq '.' || $filename eq '..') {
140        $filename = 'weird';
141    }
142    # The original C code also removed characters less than '!' and
143    # greater than or equal to '~', marked file names beginning with a
144    # non-alphanumeric or non-ASCII character as 'weird', and rejected
145    # filenames longer than 35 characters.
146    return File::Spec->catfile($base_path, $filename);
147}
148
149=head2 get_filenames MESSAGE
150
151Returns a list of filenames in which to log the passed message.
152
153This method calls C<log_filenames> on C<MESSAGE> to determine the list
154of filenames to which C<MESSAGE> gets logged.  All filenames are
155relative to C<MESSAGE->log_path>.  If C<MESSAGE->log_to_all_file>
156returns true, then the filename C<"all"> is appended to the list of
157filenames.
158
159Filenames are sanitized by C<sanitize_filename>.
160
161=cut
162
163sub get_filenames {
164    my ($m) = @_;
165    my @filenames = $m->log_filenames;
166    push @filenames, 'all' if $m->log_to_all_file;
167    return map { sanitize_filename($m->log_path, $_) } @filenames;
168}
169
170=head2 should_log_message MESSAGE
171
172Determines whether or not the passed message should be logged.
173
174To customize the behavior of this method, override
175L<BarnOwl::Message::should_log>.
176
177=cut
178
179sub should_log_message {
180    my ($m) = @_;
181    # If there's a logfilter and this message matches it, log.
182    # pass quiet=1, because we don't care if the filter doesn't exist
183    return 1 if BarnOwl::message_matches_filter($m, BarnOwl::getvar('logfilter'), 1);
184    # otherwise we do things based on the logging variables
185    # skip login/logout messages if appropriate
186    return 0 if $m->is_loginout && BarnOwl::getvar('loglogins') eq 'off';
187    # check direction
188    return 0 if $m->is_outgoing && BarnOwl::getvar('loggingdirection') eq 'in';
189    return 0 if $m->is_incoming && BarnOwl::getvar('loggingdirection') eq 'out';
190    return $m->should_log;
191}
192
193=head2 log MESSAGE
194
195Call this method to (potentially) log a message.
196
197To customize the behavior of this method for your messages, override
198L<BarnOwl::Message::log>, L<BarnOwl::Message::should_log>,
199L<BarnOwl::Message::log_base_path>, and/or
200L<BarnOwl::Message::log_filenames>.
201
202=cut
203
204sub log {
205    my ($m) = @_;
206    return unless defined $m;
207    return unless BarnOwl::Logging::should_log_message($m);
208    my $log_text = $m->log;
209    foreach my $filename (BarnOwl::Logging::get_filenames($m)) {
210        BarnOwl::Logging::enqueue_text($log_text, $filename);
211    }
212}
213
214=head2 log_outgoing_error MESSAGE
215
216Call this method to (potentially) log an error in sending an
217outgoing message.  Errors get logged to the same file(s) as
218successful messages.
219
220To customize the behavior of this method for your messages, override
221L<BarnOwl::Message::log_outgoing_error>,
222L<BarnOwl::Message::should_log>,
223L<BarnOwl::Message::log_base_path>, and/or
224L<BarnOwl::Message::log_filenames>.
225
226=cut
227
228sub log_outgoing_error {
229    my ($m) = @_;
230    return unless BarnOwl::Logging::should_log_message($m);
231    my $log_text = $m->log_outgoing_error;
232    foreach my $filename (BarnOwl::Logging::get_filenames($m)) {
233        BarnOwl::Logging::enqueue_text($log_text, $filename);
234    }
235}
236
2371;
Note: See TracBrowser for help on using the repository browser.