1Syntax::Keyword::Try(3)User Contributed Perl DocumentatioSnyntax::Keyword::Try(3)
2
3
4

NAME

6       "Syntax::Keyword::Try" - a "try/catch/finally" syntax for perl
7

SYNOPSIS

9        use Syntax::Keyword::Try;
10
11        sub foo
12        {
13           try {
14              attempt_a_thing();
15              return "success";
16           }
17           catch {
18              warn "It failed - $@";
19              return "failure";
20           }
21        }
22

DESCRIPTION

24       This module provides a syntax plugin that implements exception-handling
25       semantics in a form familiar to users of other languages, being built
26       on a block labeled with the "try" keyword, followed by at least one of
27       a "catch" or "finally" block.
28
29       As well as providing a handy syntax for this useful behaviour, this
30       module also serves to contain a number of code examples for how to
31       implement parser plugins and manipulate optrees to provide new syntax
32       and behaviours for perl code.
33

KEYWORDS

35   try
36          try {
37             STATEMENTS...
38          }
39          ...
40
41       A "try" statement provides the main body of code that will be invoked,
42       and must be followed by either a "catch" statement, a "finally"
43       statement, or both.
44
45       Execution of the "try" statement itself begins from the block given to
46       the statement and continues until either it throws an exception, or
47       completes successfully by reaching the end of the block. What will
48       happen next depends on the presence of a "catch" or "finally" statement
49       immediately following it.
50
51       The body of a "try {}" block may contain a "return" expression. If
52       executed, such an expression will cause the entire containing function
53       to return with the value provided. This is different from a plain "eval
54       {}" block, in which circumstance only the "eval" itself would return,
55       not the entire function.
56
57       The body of a "try {}" block may contain loop control expressions
58       ("redo", "next", "last") which will have their usual effect on any
59       loops that the "try {}" block is contained by.
60
61       The parsing rules for the set of statements (the "try" block and its
62       associated "catch" and "finally") are such that they are parsed as a
63       self- contained statement. Because of this, there is no need to end
64       with a terminating semicolon.
65
66       Note (especially to users of Try::Tiny and similar) that the "try {}"
67       block itself does not necessarily stop exceptions thrown inside it from
68       propagating outside. It is the presence of a later "catch {}" block
69       which causes this to happen. A "try" with only a "finally" and no
70       "catch" will still propagate exceptions up to callers as normal.
71
72   catch
73          ...
74          catch {
75             STATEMENTS...
76          }
77
78       A "catch" statement provides a block of code to the preceding "try"
79       statement that will be invoked in the case that the main block of code
80       throws an exception. The "catch" block can inspect the raised exception
81       by looking in $@ in the usual way.
82
83       Presence of this "catch" statement causes any exception thrown by the
84       preceding "try" block to be non-fatal to the surrounding code. If the
85       "catch" block wishes to optionally handle some exceptions but not
86       others, it can re-raise it (or another exception) by calling "die" in
87       the usual manner.
88
89       As with "try", the body of a "catch {}" block may also contain a
90       "return" expression, which as before, has its usual meaning, causing
91       the entire containing function to return with the given value. The body
92       may also contain loop control expressions ("redo", "next" or "last")
93       which also have their usual effect.
94
95       If a "catch" statement is not given, then any exceptions raised by the
96       "try" block are raised to the caller in the usual way.
97
98   finally
99          ...
100          finally {
101             STATEMENTS...
102          }
103
104       A "finally" statement provides a block of code to the preceding "try"
105       statement (or "try/catch" pair) which is executed afterwards, both in
106       the case of a normal execution or a thrown exception. This code block
107       may be used to provide whatever clean-up operations might be required
108       by preceding code.
109
110       Because it is executed during a stack cleanup operation, a "finally {}"
111       block may not cause the containing function to return, or to alter the
112       return value of it. It also cannot see the containing function's @_
113       arguments array (though as it is block scoped within the function, it
114       will continue to share any normal lexical variables declared up until
115       that point). It is protected from disturbing the value of $@. If the
116       "finally {}" block code throws an exception, this will be printed as a
117       warning and discarded, leaving $@ containing the original exception, if
118       one existed.
119

VALUE SEMANTICS

121           Warning: the feature described in this section is experimental.
122           This experiment may be stablised in a later version, or may be
123           altered or removed without further notice. It is present here for
124           testing and evaluation purposes.
125
126           Additionally, on perl versions 5.18 and later, it will produce a
127           warning in the "experimental" category.
128
129       The syntax provided by this module may be used as a value-yielding
130       expression.  Because this syntax is new, experimental, and somewhat
131       surprising, it must be specifically requested by name "try_value":
132
133          use Syntax::Keyword::Try qw( try try_value );
134
135          my $result = try do { ... } catch { ... };
136
137       Also, on Perl versions 5.24 and later:
138
139          my $result = try do { ... } finally { ... };
140
141          my $result = try do { ... } catch { ... } finally { ... };
142
143       Specifically, note that the expression must be spelled as "try do { ...
144       }" so that the syntax is distinct from that used by control-flow
145       statements. The interposed "do" keyword reminds the reader, and
146       instructs the syntax parser, that this will be an expression, not a
147       statement. It is not necessary to similarly notate the "catch" or
148       "finally" blocks.
149
150       In this case, the syntax behaves syntactically like an expression, and
151       may appear anywhere a normal expression is allowed. It follows similar
152       semantics to the purely control-flow case; if the code in the "try"
153       block does not throw an exception, then the expression as a whole
154       yields whatever value the "try" expression did. If it fails, then the
155       "catch" block is executed and the expression yields its resulting value
156       instead. A "finally" block, if present, will be evaluated for side-
157       effects before the rest of the expression returns.
158
159       Remember that, as in the control-flow case, the "return" keyword will
160       cause the entire containing function to return, not just the "try"
161       block.
162

OTHER MODULES

164       There are already quite a number of modules on CPAN that provide a
165       "try/catch"-like syntax for Perl.
166
167       · Try
168
169       · TryCatch
170
171       · Try::Tiny
172
173       · Syntax::Feature::Try
174
175       They are compared here, by feature:
176
177   True syntax plugin
178       Like Try and Syntax::Feature::Try, this module is implemented as a true
179       syntax plugin, allowing it to provide new parsing rules not available
180       to simple functions. Most notably here it means that the resulting
181       combination does not need to end in a semicolon.
182
183       In comparison, Try::Tiny is plain perl and provides its functionality
184       using regular perl functions; as such its syntax requires the trailing
185       semicolon.
186
187       TryCatch is a hybrid that uses Devel::Declare to parse the syntax tree.
188
189   @_ in a try or catch block
190       Because the "try" and "catch" block code is contained in a true block
191       rather than an entire anonymous subroutine, invoking it does not
192       interfere with the @_ arguments array. Code inside these blocks can
193       interact with the containing function's array as before.
194
195       This feature is unique among these modules; none of the others listed
196       have this ability.
197
198   "return" in a try or catch block
199       Like TryCatch and Syntax::Feature::Try, the "return" statement has its
200       usual effect within a subroutine containing syntax provided by this
201       module.  Namely, it causes the containing "sub" itself to return.
202
203       In comparison, using Try or Try::Tiny mean that a "return" statement
204       will only exit from the "try" block.
205
206   "next"/"last"/"redo" in a try or catch block
207       The loop control keywords of "next", "last" and "redo" have their usual
208       effect on dynamically contained loops.
209
210       Syntax::Feature::Try documents that these do not work there. The other
211       modules make no statement either way.
212
213   Value Semantics
214       Like Try and Syntax::Feature::Try, the syntax provided by this module
215       only works as a syntax-level statement and not an expression when the
216       experimental "try_value" feature described above has not been enabled.
217       You cannot assign from the result of a "try" block. Additionally,
218       final-expression value semantics do not work, so it cannot be contained
219       by a "do" block to yield this value.
220
221       In comparison, the behaviour implemented by Try::Tiny can be used as a
222       valued expression, such as assigned to a variable or returned to the
223       caller of its containing function. Such ability is provided by this
224       module if the experimental "try_value" feature is enabled, though it
225       must be spelled differently as "try do { ... }".
226
227   "try" without "catch"
228       Like Syntax::Feature::Try, the syntax provided by this module allows a
229       "try" block to be followed by only a "finally" block, with no "catch".
230       In this case, exceptions thrown by code contained by the "try" are not
231       suppressed, instead they propagate as normal to callers. This matches
232       the behaviour familiar to Java or C++ programmers.
233
234       In comparison, the code provided by Try and Try::Tiny always suppress
235       exception propagation even without an actual "catch" block.
236
237       The TryCatch module does not allow a "try" block not followed by
238       "catch".
239
240   Typed "catch"
241       Like Try and Try::Tiny, this module makes no attempt to perform any
242       kind of typed dispatch to distinguish kinds of exception caught by
243       "catch" blocks.
244
245       TryCatch and Syntax::Feature::Try both attempt to provide a kind of
246       typed dispatch where different classes of exception are caught by
247       different blocks of code, or propagated up entirely to callers.
248
249       The author considers the lack of such ability in this module to be a
250       feature.  That kind of dispatch on type matching of a controlling
251       expression is too useful a behaviour to be constrained to exception
252       catching. If the language is to provide such a facility, it should be
253       more universally applicable as a stand-alone independent ability.
254

WITH OTHER MODULES

256   Future::AsyncAwait
257       As of "Future::AsyncAwait" version 0.10 and Syntax::Keyword::Try
258       version 0.07, cross-module integration tests assert that basic
259       "try/catch" blocks inside an "async sub" work correctly, including
260       those that attempt to "return" from inside "try".
261
262          use Future::AsyncAwait;
263          use Syntax::Keyword::Try;
264
265          async sub attempt
266          {
267             try {
268                await func();
269                return "success";
270             }
271             catch {
272                return "failed";
273             }
274          }
275

KNOWN BUGS

277   Thread-safety at load time cannot be assured before perl 5.16
278       On perl versions 5.16 and above this module is thread-safe.
279
280       On perl version 5.14 this module is thread-safe provided that it is
281       "use"d before any additional threads are created.
282
283       However, when using 5.14 there is a race condition if this module is
284       loaded late in the program startup, after additional threads have been
285       created. This leads to the potential for it to be started up multiple
286       times concurrently, which creates data races when modifying internal
287       structures and likely leads to a segmentation fault, either during load
288       or soon after when more code is compiled.
289
290       As a workaround, for any such program that creates multiple threads,
291       loads additional code (such as dynamically-discovered plugins), and has
292       to run on 5.14, it should make sure to
293
294          use Syntax::Keyword::Try;
295
296       early on in startup, before it spins out any additional threads.
297
298       (See also <https://rt.cpan.org/Public/Bug/Display.html?id=123547>)
299
300   $@ is not local'ised by "try do" before perl 5.24
301       On perl versions 5.24 and above, or when using only control-flow
302       statement syntax, $@ is always correctly "local"ised.
303
304       However, when using the experimental value-yielding expression version
305       "try do {...}" on perl versions 5.22 or older, the "local"isation of $@
306       does not correctly apply around the expression. After such an
307       expression, the value of $@ will leak out if a failure happened and the
308       "catch" block was invoked, overwriting any previous value that was
309       visible there.
310
311       (See also <https://rt.cpan.org/Public/Bug/Display.html?id=124366>)
312

ACKNOWLEDGEMENTS

314       With thanks to "Zefram", "ilmari" and others from "irc.perl.org/#p5p"
315       for assisting with trickier bits of XS logic.
316

AUTHOR

318       Paul Evans <leonerd@leonerd.org.uk>
319
320
321
322perl v5.30.1                      2020-01-30           Syntax::Keyword::Try(3)
Impressum