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

INHERITANCE

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

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

DIAGNOSTICS

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

LICENSE

275       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
276       contributors see ChangeLog.
277
278       This program is free software; you can redistribute it and/or modify it
279       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
280
281
282
283perl v5.36.0                      2023-01-20                 Mail::Reporter(3)