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

DETAILS

235       Extends "DETAILS" in Log::Report::Dispatcher.
236

OVERLOADING

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

SEE ALSO

248       This module is part of Log-Report distribution version 1.36, built on
249       October 27, 2023. Website: http://perl.overmeer.net/CPAN/
250

LICENSE

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