1Log::Report::DispatcherU:s:eTrryC(o3n)tributed Perl DocuLmoegn:t:aRteipoonrt::Dispatcher::Try(3)
2
6 Log::Report::Dispatcher::Try - capture all reports as exceptions
7
9 Log::Report::Dispatcher::Try
10 is a Log::Report::Dispatcher
11
13 try { ... }; # mind the ';' !!
14 if($@) { # signals something went wrong
15 if(try {...}) { # block ended normally
17 my $x = try { read_temperature() };
19 my @x = try { read_lines_from_file() };
20 try { ... } # no comma!!
22 mode => 'DEBUG', accept => 'ERROR-';
23 try sub { ... }, # with comma
25 mode => 'DEBUG', accept => 'ALL';
26 try \&myhandler, accept => 'ERROR-';
28 try { ... } hide => 'TRACE';
29 print ref $@; # Log::Report::Dispatcher::Try
31 $@->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 try { # something causes an error report, which is caught
39 failure 'no network';
40 };
41 $@->reportFatal(to => 'syslog'); # overrule destination
42 print $@->exceptions; # no re-cast, just print
44
46 The try works like Perl's build-in "eval()", but implements real
47 exception handling which Perl core lacks.
48 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 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 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 Extends "DESCRIPTION" in Log::Report::Dispatcher.
67
69 Extends "METHODS" in Log::Report::Dispatcher.
70 Constructors
72 Extends "Constructors" in Log::Report::Dispatcher.
73 $obj->close()
75 Inherited, see "Constructors" in Log::Report::Dispatcher
76 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 accept => REASONS
90 charset => CHARSET
91 died => STRING
92 The exit string ($@) of the eval'ed block.
93 exceptions => ARRAY
95 ARRAY of Log::Report::Exception objects.
96 format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
98 hide => REASONS|ARRAY|'ALL'|'NONE'
99 [1.09] see hide()
100 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 Accessors
110 Extends "Accessors" in Log::Report::Dispatcher.
111 $obj->die2reason()
113 Returns the value of new(on_die).
114 $obj->died( [STRING] )
116 The message which was reported by "eval", which is used internally
117 to catch problems in the try block.
118 $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 $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 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 Be warned: Using this method will reset the whole 'hide'
134 configuration: it's a set not an add.
135 example: change the setting of the running block
137 my $parent_try = dispatcher 'active-try';
139 $parent_try->hide('ALL');
140 $obj->hides($reason)
142 Check whether the try stops message which were produced for
143 $reason.
144 $obj->isDisabled()
146 Inherited, see "Accessors" in Log::Report::Dispatcher
147 $obj->mode()
149 Inherited, see "Accessors" in Log::Report::Dispatcher
150 $obj->name()
152 Inherited, see "Accessors" in Log::Report::Dispatcher
153 $obj->needs( [$reason] )
155 Inherited, see "Accessors" in Log::Report::Dispatcher
156 $obj->type()
158 Inherited, see "Accessors" in Log::Report::Dispatcher
159 Logging
161 Extends "Logging" in Log::Report::Dispatcher.
162 $obj->addSkipStack(@CODE)
164 Log::Report::Dispatcher::Try->addSkipStack(@CODE)
165 Inherited, see "Logging" in Log::Report::Dispatcher
166 $obj->collectLocation()
168 Log::Report::Dispatcher::Try->collectLocation()
169 Inherited, see "Logging" in Log::Report::Dispatcher
170 $obj->collectStack( [$maxdepth] )
172 Log::Report::Dispatcher::Try->collectStack( [$maxdepth] )
173 Inherited, see "Logging" in Log::Report::Dispatcher
174 $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 The $message is either a STRING or a Log::Report::Message.
182 $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 $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 $obj->skipStack()
196 Inherited, see "Logging" in Log::Report::Dispatcher
197 $obj->stackTraceLine(%options)
199 Log::Report::Dispatcher::Try->stackTraceLine(%options)
200 Inherited, see "Logging" in Log::Report::Dispatcher
201 $obj->translate(HASH-$of-%options, $reason, $message)
203 Inherited, see "Logging" in Log::Report::Dispatcher
204 Status
206 $obj->failed()
207 Returns true if the block was left with an fatal message.
208 $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 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 $obj->success()
218 Returns true if the block exited normally.
219 $obj->wasFatal(%options)
221 Returns the Log::Report::Exception which caused the "try" block to
222 die, otherwise an empty LIST (undef).
223 -Option--Default
225 class undef
226 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
233 Extends "DETAILS" in Log::Report::Dispatcher.
234
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 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
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
250 Copyrights 2007-2021 by [Mark Overmeer <markov@cpan.org>]. For other
251 contributors see ChangeLog.
252 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/
255perl v5.32.1 2021-01-26 Log::Report::Dispatcher::Try(3)