1Log::Report::DispatcherU:s:eTrryC(o3n)tributed Perl DocuLmoegn:t:aRteipoonrt::Dispatcher::Try(3)
2
3
4

NAME

6       Log::Report::Dispatcher::Try - capture all reports as exceptions
7

INHERITANCE

9        Log::Report::Dispatcher::Try
10          is a Log::Report::Dispatcher
11

SYNOPSIS

13        try { ... };       # mind the ';' !!
14        if($@) {           # signals something went wrong
15
16        if(try {...}) {    # block ended normally
17
18        my $x = try { read_temperature() };
19        my @x = try { read_lines_from_file() };
20
21        try { ... }        # no comma!!
22           mode => 'DEBUG', accept => 'ERROR-';
23
24        try sub { ... },   # with comma
25           mode => 'DEBUG', accept => 'ALL';
26
27        try \&myhandler, accept => 'ERROR-';
28        try { ... } hide => 'TRACE';
29
30        print ref $@;      # Log::Report::Dispatcher::Try
31
32        $@->reportFatal;   # re-dispatch result of try block
33        $@->reportAll;     # ... also warnings etc
34        if($@) {...}       # if errors
35        if($@->failed) {   # same       # }
36        if($@->success) {  # no errors  # }
37
38        try { # something causes an error report, which is caught
39              failure 'no network';
40            };
41        $@->reportFatal(to => 'syslog');  # overrule destination
42
43        print $@->exceptions; # no re-cast, just print
44

DESCRIPTION

46       The try works like Perl's build-in "eval()", but implements real
47       exception handling which Perl core lacks.
48
49       The Log::Report::try() function creates this "::Try" dispatcher object
50       with name 'try'.  After the "try()" is over, you can find the object in
51       $@.  The $@ as "::Try" object behaves exactly as the $@ produced by
52       "eval", but has many added features.
53
54       The "try()" function catches fatal errors happening inside the BLOCK
55       (CODE reference which is just following the function name) into the
56       "::Try" object $@.  The errors are not automatically progressed to
57       active dispatchers.  However, non-fatal exceptions (like info or
58       notice) are also collected (unless not accepted, see new(accept), but
59       also immediately passed to the active dispatchers (unless the reason is
60       hidden, see new(hide))
61
62       After the "try()" has run, you can introspect the collected exceptions.
63       Typically, you use wasFatal() to get the exception which terminated the
64       run of the BLOCK.
65
66       Extends "DESCRIPTION" in Log::Report::Dispatcher.
67

METHODS

69       Extends "METHODS" in Log::Report::Dispatcher.
70
71   Constructors
72       Extends "Constructors" in Log::Report::Dispatcher.
73
74       $obj->close()
75           Inherited, see "Constructors" in Log::Report::Dispatcher
76
77       Log::Report::Dispatcher::Try->new($type, $name, %options)
78            -Option       --Defined in             --Default
79             accept         Log::Report::Dispatcher  depend on mode
80             charset        Log::Report::Dispatcher  <undef>
81             died                                    undef
82             exceptions                              []
83             format_reason  Log::Report::Dispatcher  'LOWERCASE'
84             hide                                    'NONE'
85             locale         Log::Report::Dispatcher  <system locale>
86             mode           Log::Report::Dispatcher  'NORMAL'
87             on_die                                  'ERROR'
88
89           accept => REASONS
90           charset => CHARSET
91           died => STRING
92             The exit string ($@) of the eval'ed block.
93
94           exceptions => ARRAY
95             ARRAY of Log::Report::Exception objects.
96
97           format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
98           hide => REASONS|ARRAY|'ALL'|'NONE'
99             [1.09] see hide()
100
101           locale => LOCALE
102           mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
103           on_die => 'ERROR'|'PANIC'
104             When code which runs in this block exits with a die(), it will
105             get translated into a Log::Report::Exception using
106             Log::Report::Die::die_decode().  How serious are we about these
107             errors?
108
109   Accessors
110       Extends "Accessors" in Log::Report::Dispatcher.
111
112       $obj->die2reason()
113           Returns the value of new(on_die).
114
115       $obj->died( [STRING] )
116           The message which was reported by "eval", which is used internally
117           to catch problems in the try block.
118
119       $obj->exceptions()
120           Returns all collected "Log::Report::Exceptions".  The last of them
121           may be a fatal one.  The other are non-fatal.
122
123       $obj->hide(@reasons)
124           [1.09] By default, the try will only catch messages which stop the
125           execution of the block (errors etc, internally a 'die').  Other
126           messages are passed to the parent dispatchers.
127
128           This option gives the opportunity to stop, for instance, trace
129           messages.  Those messages are still collected inside the try object
130           (unless excluded by new(accept)), so may get passed-on later via
131           reportAll() if you like.
132
133           Be warned: Using this method will reset the whole 'hide'
134           configuration: it's a set not an add.
135
136           example: change the setting of the running block
137
138             my $parent_try = dispatcher 'active-try';
139             $parent_try->hide('ALL');
140
141       $obj->hides($reason)
142           Check whether the try stops message which were produced for
143           $reason.
144
145       $obj->isDisabled()
146           Inherited, see "Accessors" in Log::Report::Dispatcher
147
148       $obj->mode()
149           Inherited, see "Accessors" in Log::Report::Dispatcher
150
151       $obj->name()
152           Inherited, see "Accessors" in Log::Report::Dispatcher
153
154       $obj->needs( [$reason] )
155           Inherited, see "Accessors" in Log::Report::Dispatcher
156
157       $obj->type()
158           Inherited, see "Accessors" in Log::Report::Dispatcher
159
160   Logging
161       Extends "Logging" in Log::Report::Dispatcher.
162
163       $obj->addSkipStack(@CODE)
164       Log::Report::Dispatcher::Try->addSkipStack(@CODE)
165           Inherited, see "Logging" in Log::Report::Dispatcher
166
167       $obj->collectLocation()
168       Log::Report::Dispatcher::Try->collectLocation()
169           Inherited, see "Logging" in Log::Report::Dispatcher
170
171       $obj->collectStack( [$maxdepth] )
172       Log::Report::Dispatcher::Try->collectStack( [$maxdepth] )
173           Inherited, see "Logging" in Log::Report::Dispatcher
174
175       $obj->log($opts, $reason, $message)
176           Other dispatchers translate the message here, and make it leave the
177           program.  However, messages in a "try" block are only captured in
178           an intermediate layer: they may never be presented to an end-users.
179           And for sure, we do not know the language yet.
180
181           The $message is either a STRING or a Log::Report::Message.
182
183       $obj->reportAll(%options)
184           Re-cast the messages in all collect exceptions into the defined
185           dispatchers, which were disabled during the try block. The %options
186           will end-up as HASH of %options to Log::Report::report(); see
187           Log::Report::Exception::throw() which does the job.
188
189       $obj->reportFatal()
190           Re-cast only the fatal message to the defined dispatchers.  If the
191           block was left without problems, then nothing will be done.  The
192           %options will end-up as HASH of %options to Log::Report::report();
193           see Log::Report::Exception::throw() which does the job.
194
195       $obj->skipStack()
196           Inherited, see "Logging" in Log::Report::Dispatcher
197
198       $obj->stackTraceLine(%options)
199       Log::Report::Dispatcher::Try->stackTraceLine(%options)
200           Inherited, see "Logging" in Log::Report::Dispatcher
201
202       $obj->translate(HASH-$of-%options, $reason, $message)
203           Inherited, see "Logging" in Log::Report::Dispatcher
204
205   Status
206       $obj->failed()
207           Returns true if the block was left with an fatal message.
208
209       $obj->showStatus()
210           If this object is kept in $@, and someone uses this as string, we
211           want to show the fatal error message.
212
213           The message is not very informative for the good cause: we do not
214           want people to simply print the $@, but wish for a re-cast of the
215           message using reportAll() or reportFatal().
216
217       $obj->success()
218           Returns true if the block exited normally.
219
220       $obj->wasFatal(%options)
221           Returns the Log::Report::Exception which caused the "try" block to
222           die, otherwise an empty LIST (undef).
223
224            -Option--Default
225             class   undef
226
227           class => CLASS|REGEX
228             Only return the exception if it was fatal, and in the same time
229             in the specified CLASS (as string) or matches the REGEX.  See
230             Log::Report::Message::inClass()
231

DETAILS

233       Extends "DETAILS" in Log::Report::Dispatcher.
234

OVERLOADING

236       overload: boolean
237           Returns true if the previous try block did produce a terminal
238           error.  This "try" object is assigned to $@, and the usual perl
239           syntax is "if($@) {...error-handler...}".
240
241       overload: stringify
242           When $@ is used the traditional way, it is checked to have a string
243           content.  In this case, stringify into the fatal error or nothing.
244

SEE ALSO

246       This module is part of Log-Report distribution version 1.32, built on
247       January 26, 2021. Website: http://perl.overmeer.net/CPAN/
248

LICENSE

250       Copyrights 2007-2021 by [Mark Overmeer <markov@cpan.org>]. For other
251       contributors see ChangeLog.
252
253       This program is free software; you can redistribute it and/or modify it
254       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
255
256
257
258perl v5.32.1                      2021-01-26   Log::Report::Dispatcher::Try(3)
Impressum