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 or object ($@) of the eval'ed block, in its
93 unprocessed state.
94 exceptions => ARRAY
96 ARRAY of Log::Report::Exception objects.
97 format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
99 hide => REASONS|ARRAY|'ALL'|'NONE'
100 [1.09] see hide()
101 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 Accessors
111 Extends "Accessors" in Log::Report::Dispatcher.
112 $obj->die2reason()
114 Returns the value of new(on_die).
115 $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 $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 $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 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 Be warned: Using this method will reset the whole 'hide'
136 configuration: it's a set not an add.
137 example: change the setting of the running block
139 my $parent_try = dispatcher 'active-try';
141 $parent_try->hide('ALL');
142 $obj->hides($reason)
144 Check whether the try stops message which were produced for
145 $reason.
146 $obj->isDisabled()
148 Inherited, see "Accessors" in Log::Report::Dispatcher
149 $obj->mode()
151 Inherited, see "Accessors" in Log::Report::Dispatcher
152 $obj->name()
154 Inherited, see "Accessors" in Log::Report::Dispatcher
155 $obj->needs( [$reason] )
157 Inherited, see "Accessors" in Log::Report::Dispatcher
158 $obj->type()
160 Inherited, see "Accessors" in Log::Report::Dispatcher
161 Logging
163 Extends "Logging" in Log::Report::Dispatcher.
164 $obj->addSkipStack(@CODE)
166 Log::Report::Dispatcher::Try->addSkipStack(@CODE)
167 Inherited, see "Logging" in Log::Report::Dispatcher
168 $obj->collectLocation()
170 Log::Report::Dispatcher::Try->collectLocation()
171 Inherited, see "Logging" in Log::Report::Dispatcher
172 $obj->collectStack( [$maxdepth] )
174 Log::Report::Dispatcher::Try->collectStack( [$maxdepth] )
175 Inherited, see "Logging" in Log::Report::Dispatcher
176 $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 The $message is either a STRING or a Log::Report::Message.
184 $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 $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 $obj->skipStack()
198 Inherited, see "Logging" in Log::Report::Dispatcher
199 $obj->stackTraceLine(%options)
201 Log::Report::Dispatcher::Try->stackTraceLine(%options)
202 Inherited, see "Logging" in Log::Report::Dispatcher
203 $obj->translate(HASH-$of-%options, $reason, $message)
205 Inherited, see "Logging" in Log::Report::Dispatcher
206 Status
208 $obj->failed()
209 Returns true if the block was left with an fatal message.
210 $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 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 $obj->success()
220 Returns true if the block exited normally.
221 $obj->wasFatal(%options)
223 Returns the Log::Report::Exception which caused the "try" block to
224 die, otherwise an empty LIST (undef).
225 -Option--Default
227 class undef
228 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
235 Extends "DETAILS" in Log::Report::Dispatcher.
236
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 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
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
252 Copyrights 2007-2023 by [Mark Overmeer <markov@cpan.org>]. For other
253 contributors see ChangeLog.
254 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/
257perl v5.36.1 2023-10-27 Log::Report::Dispatcher::Try(3)