1Mail::Reporter(3) User Contributed Perl Documentation Mail::Reporter(3)
2
6 Mail::Reporter - base-class and error reporter for Mail::Box
7
9 Mail::Reporter is extended by
10 Mail::Box
11 Mail::Box::Collection
12 Mail::Box::Identity
13 Mail::Box::Locker
14 Mail::Box::MH::Index
15 Mail::Box::MH::Labels
16 Mail::Box::Manager
17 Mail::Box::Parser
18 Mail::Box::Search
19 Mail::Box::Thread::Manager
20 Mail::Box::Thread::Node
21 Mail::Message
22 Mail::Message::Body
23 Mail::Message::Body::Delayed
24 Mail::Message::Convert
25 Mail::Message::Field
26 Mail::Message::Field::Attribute
27 Mail::Message::Head
28 Mail::Message::Head::FieldGroup
29 Mail::Message::TransferEnc
30 Mail::Server
31 Mail::Transport
32
34 $folder->log(WARNING => 'go away');
35 print $folder->trace; # current level
36 $folder->trace('PROGRESS'); # set level
37 print $folder->errors;
38 print $folder->report('PROGRESS');
39
41 The "Mail::Reporter" class is the base class for all classes, except
42 Mail::Message::Field::Fast because it would become slow... This base
43 class is used during initiation of the objects, and for configuring and
44 logging error messages.
45
47 Constructors
48 Mail::Reporter->new(OPTIONS)
49 This error container is also the base constructor for all modules,
50 (as long as there is no need for another base object) The
51 constructor always accepts the following OPTIONS related to error
52 reports.
53 -Option--Default
55 log 'WARNINGS'
56 trace 'WARNINGS'
57 log => LEVEL
59 Log messages which have a priority higher or equal to the
60 specified level are stored internally and can be retrieved later.
61 The global default for this option can be changed with
62 defaultTrace().
63 Known levels are "INTERNAL", "ERRORS", "WARNINGS", "PROGRESS",
65 "NOTICES" "DEBUG", and "NONE". The "PROGRESS" level relates to
66 the reading and writing of folders. "NONE" will cause only
67 "INTERNAL" errors to be logged. By the way: "ERROR" is an alias
68 for "ERRORS", as "WARNING" is an alias for "WARNINGS", and
69 "NOTICE" for "NOTICES".
70 trace => LEVEL
72 Trace messages which have a level higher or equal to the
73 specified level are directly printed using warn. The global
74 default for this option can be changed with defaultTrace().
75 Error handling
77 $obj->AUTOLOAD
78 By default, produce a nice warning if the sub-classes cannot
79 resolve a method.
80 $obj->addReport(OBJECT)
82 Add the report from other OBJECT to the report of this object. This
83 is useful when complex actions use temporary objects which are not
84 returned to the main application but where the main application
85 would like to know about any problems.
86 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
88 Mail::Reporter->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
89 CALLBACK])
90 Reports the default log and trace level which is used for object as
92 list of two elements. When not explicitly set, both are set to
93 "WARNINGS".
94 This method has three different uses. When one argument is
96 specified, that LEVEL is set for both loglevel as tracelevel.
97 With two arguments, the second determines which configuration you
99 like. If the second argument is a CODE reference, you install a
100 CALLBACK. The loglevel will be set to NONE, and all warnings
101 produced in your program will get passed to the CALLBACK function.
102 That function will get the problem level, the object or class which
103 reports the problem, and the problem text passed as arguments.
104 In any case two values are returned: the first is the log level,
106 the second represents the trace level. Both are special variables:
107 in numeric context they deliver a value (the internally used
108 value), and in string context the string name. Be warned that the
109 string is always in singular form!
110 example: setting loglevels
112 my ($loglevel, $tracelevel) = Mail::Reporter->defaultTrace;
114 Mail::Reporter->defaultTrace('NOTICES');
115 my ($l, $t) = Mail::Reporter->defaultTrace('WARNINGS', 'DEBUG');
117 print $l; # prints "WARNING" (no S!)
118 print $l+0; # prints "4"
119 print "Auch" if $l >= $self->logPriority('ERROR');
120 Mail::Reporter->defaultTrace('NONE'); # silence all reports
122 $folder->defaultTrace('DEBUG'); # Still set as global default!
124 $folder->trace('DEBUG'); # local default
125 example: installing a callback
127 Mail::Reporter->defaultTrace
129 $obj->errors
131 Equivalent to
132 $folder->report('ERRORS')
134 $obj->log([LEVEL [,STRINGS]])
136 Mail::Reporter->log([LEVEL [,STRINGS]])
137 As instance method this function has three different purposes.
139 Without any argument, it returns one scalar containing the number
140 which is internally used to represent the current log level, and
141 the textual representation of the string at the same time. See
142 Scalar::Util method "dualvar" for an explanation.
143 With one argument, a new level of logging detail is set (specify a
145 number of one of the predefined strings). With more arguments, it
146 is a report which may need to be logged or traced.
147 As class method, only a message can be passed. The global
149 configuration value set with defaultTrace() is used to decide
150 whether the message is shown or ignored.
151 Each log-entry has a LEVEL and a text string which will be
153 constructed by joining the STRINGS. If there is no newline, it
154 will be added.
155 example:
157 print $message->log; # may print "NOTICE"
159 print $message->log +0; # may print "3"
160 $message->log('ERRORS'); # sets a new level, returns the numeric value
161 $message->log(WARNING => "This message is too large.");
163 $folder ->log(NOTICE => "Cannot read from file $filename.");
164 $manager->log(DEBUG => "Hi there!", reverse sort @l);
165 Mail::Message->log(ERROR => 'Unknown');
167 $obj->logPriority(LEVEL)
169 Mail::Reporter->logPriority(LEVEL)
170 One error level (log or trace) has more than one representation: a
172 numeric value and one or more strings. For instance, 4, 'WARNING',
173 and 'WARNINGS' are all the same. You can specify any of these, and
174 in return you get a dualvar (see Scalar::Util method "dualvar")
175 back, which contains the number and the singular form.
176 The higher the number, the more important the message. Only
178 messages about "INTERNAL" problems are more important than "NONE".
179 example:
181 my $r = Mail::Reporter->logPriority('WARNINGS');
183 my $r = Mail::Reporter->logPriority('WARNING'); # same
184 my $r = Mail::Reporter->logPriority(4); # same, deprecated
185 print $r; # prints 'WARNING' (no S!)
186 print $r + 0; # prints 4
187 if($r < Mail::Reporter->logPriority('ERROR')) {..} # true
188 $obj->logSettings
190 Returns a list of "(key =" value)> pairs which can be used to
191 initiate a new object with the same log-settings as this one.
192 example:
194 $head->new($folder->logSettings);
196 $obj->notImplemented
198 A special case of log(), which logs a "INTERNAL"-error and then
199 croaks. This is used by extension writers.
200 $obj->report([LEVEL])
202 Get logged reports, as list of strings. If a LEVEL is specified,
203 the log for that level is returned.
204 In case no LEVEL is specified, you get all messages each as
206 reference to a tuple with level and message.
207 example:
209 my @warns = $message->report('WARNINGS');
211 # previous indirectly callable with
212 my @warns = $msg->warnings;
213 print $folder->report('ERRORS');
215 if($folder->report('DEBUG')) {...}
217 my @reports = $folder->report;
219 foreach (@reports) {
220 my ($level, $text) = @$_;
221 print "$level report: $text";
222 }
223 $obj->reportAll([LEVEL])
225 Report all messages which were produced by this object and all the
226 objects which are maintained by this object. This will return a
227 list of triplets, each containing a reference to the object which
228 caught the report, the level of the report, and the message.
229 example:
231 my $folder = Mail::Box::Manager->new->open(folder => 'inbox');
233 my @reports = $folder->reportAll;
234 foreach (@reports) {
235 my ($object, $level, $text) = @$_;
236 if($object->isa('Mail::Box')) {
238 print "Folder $object: $level: $message";
239 } elsif($object->isa('Mail::Message') {
240 print "Message ".$object->seqnr.": $level: $message";
241 }
242 }
243 $obj->trace([LEVEL])
245 Change the trace LEVEL of the object. When no arguments are
246 specified, the current level is returned only. It will be returned
247 in one scalar which contains both the number which is internally
248 used to represent the level, and the string which represents it.
249 See logPriority().
250 $obj->warnings
252 Equivalent to
253 $folder->report('WARNINGS')
255 Cleanup
257 $obj->DESTROY
258 Cleanup the object.
259 $obj->inGlobalDestruction
261 Returns whether the program is breaking down. This is used in
262 DESTROY(), where during global destructions references cannot be
263 used.
264 The "Mail::Reporter" class is the base for nearly all other objects.
266 It can store and report problems, and contains the general constructor
267 new().
268
270 Error: Package $package does not implement $method.
271 Fatal error: the specific package (or one of its superclasses) does
272 not implement this method where it should. This message means that
273 some other related classes do implement this method however the
274 class at hand does not. Probably you should investigate this and
275 probably inform the author of the package.
276
278 This module is part of Mail-Box distribution version 2.097, built on
279 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
280
282 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
283 ChangeLog.
284 This program is free software; you can redistribute it and/or modify it
286 under the same terms as Perl itself. See
287 http://www.perl.com/perl/misc/Artistic.html
288perl v5.12.3 2011-01-26 Mail::Reporter(3)