Mail::Reporter(3pm)

1Mail::Reporter(3)     User Contributed Perl Documentation    Mail::Reporter(3)
2
3
4

NAME

6       Mail::Reporter - base-class and error reporter for Mail::Box
7

SYNOPSIS

9        $folder->log(WARNING => 'go away');
10        print $folder->trace;        # current level
11        $folder->trace('PROGRESS');  # set level
12        print $folder->errors;
13        print $folder->report('PROGRESS');
14

DESCRIPTION

16       The "Mail::Reporter" class is the base class for all classes, except
17       Mail::Message::Field::Fast because it would become slow...  This base
18       class is used during initiation of the objects, and for configuring and
19       logging error messages.
20

METHODS

22       The "Mail::Reporter" class is the base for nearly all other objects.
23       It can store and report problems, and contains the general constructor
24       new().
25
26       Constructors
27
28       Mail::Reporter->new(OPTIONS)
29
30           This error container is also the base constructor for all modules,
31           (as long as there is no need for an other base object)  The con‐
32           structor always accepts the following OPTIONS related to error
33           reports.
34
35            Option--Default
36            log     'WARNINGS'
37            trace   'WARNINGS'
38
39           . log LEVEL
40
41               Log messages which have a priority higher or equal to the spec‐
42               ified level are stored internally and can be retrieved later.
43               The global default for this option can be changed with default‐
44               Trace().
45
46               Known levels are "INTERNAL", "ERRORS", "WARNINGS", "PROGRESS",
47               "NOTICES" "DEBUG", and "NONE".  The "PROGRESS" level relates to
48               the reading and writing of folders.  "NONE" will cause only
49               "INTERNAL" errors to be logged.  By the way: "ERROR" is an
50               alias for "ERRORS", as "WARNING" is an alias for "WARNINGS",
51               and "NOTICE" for "NOTICES".
52
53           . trace LEVEL
54
55               Trace messages which have a level higher or equal to the speci‐
56               fied level are directly printed using warn.  The global default
57               for this option can be changed with defaultTrace().
58
59       Error handling
60
61       $obj->AUTOLOAD
62
63           By default, produce a nice warning if the sub-classes cannot
64           resolve a method.
65
66       $obj->addReport(OBJECT)
67
68           Add the report from other OBJECT to the report of this object. This
69           is useful when complex actions use temporary objects which are not
70           returned to the main application but where the main application
71           would like to know about any problems.
72
73       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
74
75       Mail::Reporter->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
76       CALLBACK])
77
78           Reports the default log and trace level which is used for object as
79           list of two elements.  When not explicitly set, both are set to
80           "WARNINGS".
81
82           This method has three different uses. When one argument is speci‐
83           fied, that LEVEL is set for both loglevel as tracelevel.
84
85           With two arguments, the second determines which configuration you
86           like.  If the second argument is a CODE reference, you install a
87           CALLBACK.  The loglevel will be set to NONE, and all warnings pro‐
88           duced in your program will get passed to the CALLBACK function.
89           That function will get the problem level, the object or class which
90           reports the problem, and the problem text passed as arguments.
91
92           In any case two values are returned: the first is the log level,
93           the second represents the trace level.  Both are special variables:
94           in numeric context they deliver a value (the internally used
95           value), and in string context the string name.  Be warned that the
96           string is always in singular form!
97
98           Example: setting loglevels
99
100            my ($loglevel, $tracelevel) = Mail::Reporter->defaultTrace;
101            Mail::Reporter->defaultTrace('NOTICES');
102
103            my ($l, $t) = Mail::Reporter->defaultTrace('WARNINGS', 'DEBUG');
104            print $l;     # prints "WARNING"  (no S!)
105            print $l+0;   # prints "4"
106            print "Auch" if $l >= $self->logPriority('ERROR');
107
108            Mail::Reporter->defaultTrace('NONE');  # silence all reports
109
110            $folder->defaultTrace('DEBUG');   # Still set as global default!
111            $folder->trace('DEBUG');          # local default
112
113           Example: installing a callback
114
115            Mail::Reporter->defaultTrace
116
117       $obj->errors
118
119           Equivalent to
120
121            $folder->report('ERRORS')
122
123       $obj->log([LEVEL [,STRINGS]])
124
125       Mail::Reporter->log([LEVEL [,STRINGS]])
126
127           As instance method this function has three different purposes.
128           Without any argument, it returns one scalar containing the number
129           which is internally used to represent the current log level, and
130           the textual representation of the string at the same time. See
131           Scalar::Util method "dualvar" for an explanation.
132
133           With one argument, a new level of logging detail is set (specify a
134           number of one of the predefined strings).  With more arguments, it
135           is a report which may need to be logged or traced.
136
137           As class method, only a message can be passed.  The global configu‐
138           ration value set with defaultTrace() is used to decide whether the
139           message is shown or ignored.
140
141           Each log-entry has a LEVEL and a text string which will be con‐
142           structed by joining the STRINGS.  If there is no newline, it will
143           be added.
144
145           Example:
146
147            print $message->log;      # may print "NOTICE"
148            print $message->log +0;   # may print "3"
149            $message->log('ERRORS');  # sets a new level, returns the numeric value
150
151            $message->log(WARNING => "This message is too large.");
152            $folder ->log(NOTICE  => "Cannot read from file $filename.");
153            $manager->log(DEBUG   => "Hi there!", reverse sort @l);
154
155            Mail::Message->log(ERROR => 'Unknown');
156
157       $obj->logPriority(LEVEL)
158
159       Mail::Reporter->logPriority(LEVEL)
160
161           One error level (log or trace) has more than one representation: a
162           numeric value and one or more strings.  For instance, 4, 'WARNING',
163           and 'WARNINGS' are all the same.  You can specify any of these, and
164           in return you get a dualvar (see Scalar::Util method "dualvar")
165           back, which contains the number and the singular form.
166
167           The higher the number, the more important the message.  Only mes‐
168           sages about "INTERNAL" problems are more important than "NONE".
169
170           Example:
171
172            my $r = Mail::Reporter->logPriority('WARNINGS');
173            my $r = Mail::Reporter->logPriority('WARNING');    # same
174            my $r = Mail::Reporter->logPriority(4);            # same, deprecated
175            print $r;      # prints 'WARNING'  (no S!)
176            print $r + 0;  # prints 4
177            if($r < Mail::Reporter->logPriority('ERROR')) {..} # true
178
179       $obj->logSettings
180
181           Returns a list of "(key =" value)> pairs which can be used to ini‐
182           tiate a new object with the same log-settings as this one.
183
184           Example:
185
186            $head->new($folder->logSettings);
187
188       $obj->notImplemented
189
190           A special case of log(), which logs a "INTERNAL"-error and then
191           croaks.  This is used by extension writers.
192
193       $obj->report([LEVEL])
194
195           Get logged reports, as list of strings.  If a LEVEL is specified,
196           the log for that level is returned.
197
198           In case no LEVEL is specified, you get all messages each as refer‐
199           ence to a tuple with level and message.
200
201           Example:
202
203            my @warns = $message->report('WARNINGS');
204              # previous indirectly callable with
205              my @warns = $msg->warnings;
206
207            print $folder->report('ERRORS');
208
209            if($folder->report('DEBUG')) {...}
210
211            my @reports = $folder->report;
212            foreach (@reports) {
213               my ($level, $text) = @$_;
214               print "$level report: $text";
215            }
216
217       $obj->reportAll([LEVEL])
218
219           Report all messages which were produced by this object and all the
220           objects which are maintained by this object.  This will return a
221           list of triplets, each containing a reference to the object which
222           caught the report, the level of the report, and the message.
223
224           Example:
225
226            my $folder = Mail::Box::Manager->new->open(folder => 'inbox');
227            my @reports = $folder->reportAll;
228            foreach (@reports) {
229               my ($object, $level, $text) = @$_;
230
231               if($object->isa('Mail::Box')) {
232                  print "Folder $object: $level: $message";
233               } elsif($object->isa('Mail::Message') {
234                  print "Message ".$object->seqnr.": $level: $message";
235               }
236            }
237
238       $obj->trace([LEVEL])
239
240           Change the trace LEVEL of the object. When no arguments are speci‐
241           fied, the current level is returned only.  It will be returned in
242           one scalar which contains both the number which is internally used
243           to represent the level, and the string which represents it.  See
244           logPriority().
245
246       $obj->warnings
247
248           Equivalent to
249
250            $folder->report('WARNINGS')
251
252       Cleanup
253
254       $obj->DESTROY
255
256           Cleanup the object.
257
258       $obj->inGlobalDestruction
259
260           Returns whether the program is breaking down.  This is used in
261           DESTROY(), where during global destructions references cannot be
262           used.
263

DIAGNOSTICS

265       Error: Package $package does not implement $method.
266
267       Fatal error: the specific package (or one of its superclasses) does not
268       implement this method where it should. This message means that some
269       other related classes do implement this method however the class at
270       hand does not.  Probably you should investigate this and probably
271       inform the author of the package.
272

LICENSE

278       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
279       ChangeLog.
280
281       This program is free software; you can redistribute it and/or modify it
282       under the same terms as Perl itself.  See
283       http://www.perl.com/perl/misc/Artistic.html
284
285
286
287perl v5.8.8                       2007-03-25                 Mail::Reporter(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

DIAGNOSTICS

SEE ALSO

LICENSE