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 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
53       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
59       Extends "DESCRIPTION" in Log::Report::Dispatcher.
60

METHODS

62       Extends "METHODS" in Log::Report::Dispatcher.
63
64   Constructors
65       Extends "Constructors" in Log::Report::Dispatcher.
66
67       $obj->close()
68           Inherited, see "Constructors" in Log::Report::Dispatcher
69
70       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
82           accept => REASONS
83           charset => CHARSET
84           died => STRING
85             The exit string ($@) of the eval'ed block.
86
87           exceptions => ARRAY
88             ARRAY of Log::Report::Exception objects.
89
90           format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
91           hide => REASON|ARRAY|'ALL'|'NONE'
92             [1.09] see hide()
93
94           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
102   Accessors
103       Extends "Accessors" in Log::Report::Dispatcher.
104
105       $obj->die2reason()
106           Returns the value of new(on_die).
107
108       $obj->died( [STRING] )
109           The message which was reported by "eval", which is used internally
110           to catch problems in the try block.
111
112       $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
116       $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
122           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
126           Be warned: Using this method will reset the whole 'hide'
127           configuration: it's a set not an add.
128
129           example: change the setting of the running block
130
131             my $parent_try = dispatcher 'active-try';
132             parent_try->hide('NONE');
133
134       $obj->hides(REASON)
135       $obj->isDisabled()
136           Inherited, see "Accessors" in Log::Report::Dispatcher
137
138       $obj->mode()
139           Inherited, see "Accessors" in Log::Report::Dispatcher
140
141       $obj->name()
142           Inherited, see "Accessors" in Log::Report::Dispatcher
143
144       $obj->needs( [$reason] )
145           Inherited, see "Accessors" in Log::Report::Dispatcher
146
147       $obj->type()
148           Inherited, see "Accessors" in Log::Report::Dispatcher
149
150   Logging
151       Extends "Logging" in Log::Report::Dispatcher.
152
153       $obj->addSkipStack(@CODE)
154       Log::Report::Dispatcher::Try->addSkipStack(@CODE)
155           Inherited, see "Logging" in Log::Report::Dispatcher
156
157       $obj->collectLocation()
158       Log::Report::Dispatcher::Try->collectLocation()
159           Inherited, see "Logging" in Log::Report::Dispatcher
160
161       $obj->collectStack( [$maxdepth] )
162       Log::Report::Dispatcher::Try->collectStack( [$maxdepth] )
163           Inherited, see "Logging" in Log::Report::Dispatcher
164
165       $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
171           The $message is either a STRING or a Log::Report::Message.
172
173       $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
179       $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
185       $obj->skipStack()
186           Inherited, see "Logging" in Log::Report::Dispatcher
187
188       $obj->stackTraceLine(%options)
189       Log::Report::Dispatcher::Try->stackTraceLine(%options)
190           Inherited, see "Logging" in Log::Report::Dispatcher
191
192       $obj->translate(HASH-$of-%options, $reason, $message)
193           Inherited, see "Logging" in Log::Report::Dispatcher
194
195   Status
196       $obj->failed()
197           Returns true if the block was left with an fatal message.
198
199       $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
203           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
207       $obj->success()
208           Returns true if the block exited normally.
209
210       $obj->wasFatal(%options)
211           Returns the Log::Report::Exception which caused the "try" block to
212           die, otherwise an empty LIST (undef).
213
214            -Option--Default
215             class   undef
216
217           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

DETAILS

223       Extends "DETAILS" in Log::Report::Dispatcher.
224

OVERLOADING

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
231       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

SEE ALSO

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

LICENSE

240       Copyrights 2007-2019 by [Mark Overmeer <markov@cpan.org>]. For other
241       contributors see ChangeLog.
242
243       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/
245
246
247
248perl v5.30.1                      2019-11-08   Log::Report::Dispatcher::Try(3)
Impressum