1Feature::Compat::Try(3)User Contributed Perl DocumentatioFneature::Compat::Try(3)
2
6 "Feature::Compat::Try" - make "try/catch" syntax available
7
9 use Feature::Compat::Try;
10 sub foo
12 {
13 try {
14 attempt_a_thing();
15 return "success";
16 }
17 catch ($e) {
18 warn "It failed - $e";
19 return "failure";
20 }
21 }
22
24 This module makes syntax support for "try/catch" control flow easily
25 available.
26 Perl added such syntax at version 5.34.0, and extended it to support
28 optional "finally" blocks at 5.35.9, which is enabled by
29 use feature 'try';
31 On that version of perl or later, this module simply enables the core
33 feature equivalent to using it directly. On such perls, this module
34 will install with no non-core dependencies, and requires no C compiler.
35 On older versions of perl before such syntax is available, it is
37 currently provided instead using the Syntax::Keyword::Try module,
38 imported with a special set of options to configure it to recognise
39 exactly and only the same syntax as the core perl feature, thus
40 ensuring that any code using it will still continue to function on that
41 newer perl.
42
44 try
45 try {
46 STATEMENTS...
47 }
48 ...
49 A "try" statement provides the main body of code that will be invoked,
51 and must be followed by a "catch" statement. It may optionally be
52 followed by a "finally" statement.
53 Execution of the "try" statement itself begins from the block given to
55 the statement and continues until either it throws an exception, or
56 completes successfully by reaching the end of the block.
57 The body of a "try {}" block may contain a "return" expression. If
59 executed, such an expression will cause the entire containing function
60 to return with the value provided. This is different from a plain "eval
61 {}" block, in which circumstance only the "eval" itself would return,
62 not the entire function.
63 The body of a "try {}" block may contain loop control expressions
65 ("redo", "next", "last") which will have their usual effect on any
66 loops that the "try {}" block is contained by.
67 The parsing rules for the set of statements (the "try" block and its
69 associated "catch") are such that they are parsed as a self-contained
70 statement. Because of this, there is no need to end with a terminating
71 semicolon.
72 Even though it parses as a statement and not an expression, a "try"
74 block can still yield a value if it appears as the final statement in
75 its containing "sub" or "do" block. For example:
76 my $result = do {
78 try { attempt_func() }
79 catch ($e) { "Fallback Value" }
80 };
81 catch
83 ...
84 catch ($var) {
85 STATEMENTS...
86 }
87 A "catch" statement provides a block of code to the preceding "try"
89 statement that will be invoked in the case that the main block of code
90 throws an exception. A new lexical variable is created to store the
91 exception in.
92 Presence of this "catch" statement causes any exception thrown by the
94 preceding "try" block to be non-fatal to the surrounding code. If the
95 "catch" block wishes to optionally handle some exceptions but not
96 others, it can re-raise it (or another exception) by calling "die" in
97 the usual manner.
98 As with "try", the body of a "catch {}" block may also contain a
100 "return" expression, which as before, has its usual meaning, causing
101 the entire containing function to return with the given value. The body
102 may also contain loop control expressions ("redo", "next" or "last")
103 which also have their usual effect.
104 finally
106 ...
107 finally {
108 STATEMENTS...
109 }
110 A "finally" statement provides an optional block of code to the
112 preceding "try"/"catch" pair which is executed afterwards, both in the
113 case of a normal execution or a thrown exception. This code block may
114 be used to provide whatever clean-up operations might be required by
115 preceding code.
116 Because it is executed during a stack cleanup operation, a "finally {}"
118 block may not cause the containing function to return, or to alter the
119 return value of it. It also cannot see the containing function's @_
120 arguments array (though as it is block scoped within the function, it
121 will continue to share any normal lexical variables declared up until
122 that point). It is protected from disturbing the value of $@. If the
123 "finally {}" block code throws an exception, this will be printed as a
124 warning and discarded, leaving $@ containing the original exception, if
125 one existed.
126
128 This module may use either Syntax::Keyword::Try or the perl core "try"
129 feature to implement its syntax. While the two behave very similarly,
130 and both conform to the description given above, the following
131 differences should be noted.
132 • Visibility to caller()
134 The "Syntax::Keyword::Try" module implements "try" blocks by using
136 "eval" frames. As a result, they are visible to the caller()
137 function and hence to things like "Carp::longmess" when viewed as
138 stack traces.
139 By comparison, core's "feature 'try'" creates a new kind of context
141 stack entry that is ignored by caller() and hence these blocks do
142 not show up in stack traces.
143 This should not matter to most use-cases - e.g. even "Carp::croak"
145 will be fine here. But if you are using caller() with calculated
146 indexes to inspect the state of callers to your code and there may
147 be "try" frames in the way, you will need to somehow account for
148 the difference in stack height.
149 • "B::Deparse"
151 The core "feature 'try'" is implemented by emitting real opcodes
153 that represent its behaviour, which is recognised by the version of
154 B::Deparse that ships with core perl. As a result, any code using
155 this implementation will deparse currently with tools like "perl
156 -MO=Deparse ...", or others related to it such as coverage
157 checkers.
158 By comparison, since "Syntax::Keyword::Try" uses "OP_CUSTOM" it is
160 not recognised by "B::Deparse" and so attempts to deparse this will
161 result in error messages like
162 unexpected OP_CUSTOM (catch) at ...
164 This is rather unavoidable due to the way that "B::Deparse" is
166 implemented and does not easily support custom operators.
167 See also <https://rt.cpan.org/Ticket/Display.html?id=134812>.
169
171 Paul Evans <leonerd@leonerd.org.uk>
172perl v5.36.0 2023-01-20 Feature::Compat::Try(3)