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 Log::Report::try() catches errors in the block (CODE reference)
47 which is just following the function name. All dispatchers are
48 temporarily disabled by "try", and messages which are reported are
49 collected within a temporary dispatcher named "try". When the CODE has
50 run, that "try" dispatcher is returned in $@, and all original
51 dispatchers reinstated.
52 Then, after the "try" has finished, the routine which used the "try"
54 should decide what to do with the collected reports. These reports are
55 collected as Log::Report::Exception objects. They can be ignored, or
56 thrown to a higher level try... causing an exit of the program if there
57 is none.
58 Extends "DESCRIPTION" in Log::Report::Dispatcher.
60
62 Extends "METHODS" in Log::Report::Dispatcher.
63 Constructors
65 Extends "Constructors" in Log::Report::Dispatcher.
66 $obj->close()
68 Inherited, see "Constructors" in Log::Report::Dispatcher
69 Log::Report::Dispatcher::Try->new($type, $name, %options)
71 -Option --Defined in --Default
72 accept Log::Report::Dispatcher depend on mode
73 charset Log::Report::Dispatcher <undef>
74 died undef
75 exceptions []
76 format_reason Log::Report::Dispatcher 'LOWERCASE'
77 hide 'NONE'
78 locale Log::Report::Dispatcher <system locale>
79 mode Log::Report::Dispatcher 'NORMAL'
80 on_die 'ERROR'
81 accept => REASONS
83 charset => CHARSET
84 died => STRING
85 The exit string ($@) of the eval'ed block.
86 exceptions => ARRAY
88 ARRAY of Log::Report::Exception objects.
89 format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
91 hide => REASON|ARRAY|'ALL'|'NONE'
92 [1.09] see hide()
93 locale => LOCALE
95 mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
96 on_die => 'ERROR'|'PANIC'
97 When code which runs in this block exits with a die(), it will
98 get translated into a Log::Report::Exception using
99 Log::Report::Die::die_decode(). How serious are we about these
100 errors?
101 Accessors
103 Extends "Accessors" in Log::Report::Dispatcher.
104 $obj->die2reason()
106 Returns the value of new(on_die).
107 $obj->died( [STRING] )
109 The message which was reported by "eval", which is used internally
110 to catch problems in the try block.
111 $obj->exceptions()
113 Returns all collected "Log::Report::Exceptions". The last of them
114 may be a fatal one. The other are non-fatal.
115 $obj->hide(REASON|REASONS|ARRAY|'ALL'|'NONE')
117 [1.09] By default, the try will only catch messages which stop the
118 execution of the block (errors etc, internally a 'die'). Other
119 messages are passed to parent try blocks, if none than to the
120 dispatchers.
121 This option gives the opportunity to block, for instance, trace
123 messages. Those messages are still collected inside the try
124 object, so may get passed-on later via reportAll() if you like.
125 Be warned: Using this method will reset the whole 'hide'
127 configuration: it's a set not an add.
128 example: change the setting of the running block
130 my $parent_try = dispatcher 'active-try';
132 parent_try->hide('NONE');
133 $obj->hides(REASON)
135 $obj->isDisabled()
136 Inherited, see "Accessors" in Log::Report::Dispatcher
137 $obj->mode()
139 Inherited, see "Accessors" in Log::Report::Dispatcher
140 $obj->name()
142 Inherited, see "Accessors" in Log::Report::Dispatcher
143 $obj->needs( [$reason] )
145 Inherited, see "Accessors" in Log::Report::Dispatcher
146 $obj->type()
148 Inherited, see "Accessors" in Log::Report::Dispatcher
149 Logging
151 Extends "Logging" in Log::Report::Dispatcher.
152 $obj->addSkipStack(@CODE)
154 Log::Report::Dispatcher::Try->addSkipStack(@CODE)
155 Inherited, see "Logging" in Log::Report::Dispatcher
156 $obj->collectLocation()
158 Log::Report::Dispatcher::Try->collectLocation()
159 Inherited, see "Logging" in Log::Report::Dispatcher
160 $obj->collectStack( [$maxdepth] )
162 Log::Report::Dispatcher::Try->collectStack( [$maxdepth] )
163 Inherited, see "Logging" in Log::Report::Dispatcher
164 $obj->log($opts, $reason, $message)
166 Other dispatchers translate the message here, and make it leave the
167 program. However, messages in a "try" block are only captured in
168 an intermediate layer: they may never be presented to an end-users.
169 And for sure, we do not know the language yet.
170 The $message is either a STRING or a Log::Report::Message.
172 $obj->reportAll(%options)
174 Re-cast the messages in all collect exceptions into the defined
175 dispatchers, which were disabled during the try block. The %options
176 will end-up as HASH of %options to Log::Report::report(); see
177 Log::Report::Exception::throw() which does the job.
178 $obj->reportFatal()
180 Re-cast only the fatal message to the defined dispatchers. If the
181 block was left without problems, then nothing will be done. The
182 %options will end-up as HASH of %options to Log::Report::report();
183 see Log::Report::Exception::throw() which does the job.
184 $obj->skipStack()
186 Inherited, see "Logging" in Log::Report::Dispatcher
187 $obj->stackTraceLine(%options)
189 Log::Report::Dispatcher::Try->stackTraceLine(%options)
190 Inherited, see "Logging" in Log::Report::Dispatcher
191 $obj->translate(HASH-$of-%options, $reason, $message)
193 Inherited, see "Logging" in Log::Report::Dispatcher
194 Status
196 $obj->failed()
197 Returns true if the block was left with an fatal message.
198 $obj->showStatus()
200 If this object is kept in $@, and someone uses this as string, we
201 want to show the fatal error message.
202 The message is not very informative for the good cause: we do not
204 want people to simply print the $@, but wish for a re-cast of the
205 message using reportAll() or reportFatal().
206 $obj->success()
208 Returns true if the block exited normally.
209 $obj->wasFatal(%options)
211 Returns the Log::Report::Exception which caused the "try" block to
212 die, otherwise an empty LIST (undef).
213 -Option--Default
215 class undef
216 class => CLASS|REGEX
218 Only return the exception if it was fatal, and in the same time
219 in the specified CLASS (as string) or matches the REGEX. See
220 Log::Report::Message::inClass()
221
223 Extends "DETAILS" in Log::Report::Dispatcher.
224
226 overload: boolean
227 Returns true if the previous try block did produce a terminal
228 error. This "try" object is assigned to $@, and the usual perl
229 syntax is "if($@) {...error-handler...}".
230 overload: stringify
232 When $@ is used the traditional way, it is checked to have a string
233 content. In this case, stringify into the fatal error or nothing.
234
236 This module is part of Log-Report distribution version 1.29, built on
237 November 08, 2019. Website: http://perl.overmeer.net/CPAN/
238
240 Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other
241 contributors see ChangeLog.
242 This program is free software; you can redistribute it and/or modify it
244 under the same terms as Perl itself. See http://dev.perl.org/licenses/
245perl v5.30.1 2019-11-08 Log::Report::Dispatcher::Try(3)