File Coverage

blib/lib/Feature/Compat/Try.pm
Criterion Covered Total %
statement 15 15 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 20 20 100.0


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2021 -- leonerd@leonerd.org.uk
5              
6             package Feature::Compat::Try 0.04;
7              
8 8     8   500476 use v5.14;
  8         93  
9 8     8   46 use warnings;
  8         15  
  8         217  
10 8     8   45 use feature ();
  8         16  
  8         356  
11              
12 8     8   82 use constant HAVE_FEATURE_TRY => defined $feature::feature{try};
  8         34  
  8         1809  
13              
14             =head1 NAME
15              
16             C - make C syntax available
17              
18             =head1 SYNOPSIS
19              
20             use Feature::Compat::Try;
21              
22             sub foo
23             {
24             try {
25             attempt_a_thing();
26             return "success";
27             }
28             catch ($e) {
29             warn "It failed - $e";
30             return "failure";
31             }
32             }
33              
34             =head1 DESCRIPTION
35              
36             This module is written in preparation for when perl will gain true native
37             syntax support for C control flow.
38              
39             Perl added such syntax in the development version 5.33.7, which is enabled
40             by
41              
42             use feature 'try';
43              
44             On that version of perl or later, this module simply enables the core feature
45             equivalent to using it directly. On such perls, this module will install with
46             no non-core dependencies, and requires no C compiler.
47              
48             On older versions of perl before such syntax is available, it is currently
49             provided instead using the L module, imported with a
50             special set of options to configure it to recognise exactly and only the same
51             syntax as the core perl feature, thus ensuring that any code using it will
52             still continue to function on that newer perl.
53              
54             =cut
55              
56             =head1 KEYWORDS
57              
58             =head2 try
59              
60             try {
61             STATEMENTS...
62             }
63             ...
64              
65             A C statement provides the main body of code that will be invoked, and
66             must be followed by a C statement.
67              
68             Execution of the C statement itself begins from the block given to the
69             statement and continues until either it throws an exception, or completes
70             successfully by reaching the end of the block.
71              
72             The body of a C block may contain a C expression. If executed,
73             such an expression will cause the entire containing function to return with
74             the value provided. This is different from a plain C block, in which
75             circumstance only the C itself would return, not the entire function.
76              
77             The body of a C block may contain loop control expressions (C,
78             C, C) which will have their usual effect on any loops that the
79             C block is contained by.
80              
81             The parsing rules for the set of statements (the C block and its
82             associated C) are such that they are parsed as a self-contained
83             statement. Because of this, there is no need to end with a terminating
84             semicolon.
85              
86             Even though it parses as a statement and not an expression, a C block can
87             still yield a value if it appears as the final statement in its containing
88             C or C block. For example:
89              
90             my $result = do {
91             try { attempt_func() }
92             catch ($e) { "Fallback Value" }
93             };
94              
95             =head2 catch
96              
97             ...
98             catch ($var) {
99             STATEMENTS...
100             }
101              
102             A C statement provides a block of code to the preceding C
103             statement that will be invoked in the case that the main block of code throws
104             an exception. A new lexical variable is created to store the exception in.
105              
106             Presence of this C statement causes any exception thrown by the
107             preceding C block to be non-fatal to the surrounding code. If the
108             C block wishes to optionally handle some exceptions but not others, it
109             can re-raise it (or another exception) by calling C in the usual manner.
110              
111             As with C, the body of a C block may also contain a C
112             expression, which as before, has its usual meaning, causing the entire
113             containing function to return with the given value. The body may also contain
114             loop control expressions (C, C or C) which also have their
115             usual effect.
116              
117             =cut
118              
119             sub import
120             {
121 8     8   53 if( HAVE_FEATURE_TRY ) {
122             feature->import(qw( try ));
123             require warnings;
124             warnings->unimport(qw( experimental::try ));
125             }
126             else {
127 8         4443 require Syntax::Keyword::Try;
128 8         8341 Syntax::Keyword::Try->VERSION( '0.22' );
129 8         38 Syntax::Keyword::Try->import(qw( try -no_finally -require_var ));
130             }
131             }
132              
133             =head1 COMPATIBILITY NOTES
134              
135             This module may use either L or the perl core C
136             feature to implement its syntax. While the two behave very similarly, and both
137             conform to the description given above, the following differences should be
138             noted.
139              
140             =over 4
141              
142             =item * Visibility to C
143              
144             The C module implements C blocks by using C
145             frames. As a result, they are visible to the C function and hence to
146             things like C when viewed as stack traces.
147              
148             By comparison, core's C creates a new kind of context stack
149             entry that is ignored by C and hence these blocks do not show up in
150             stack traces.
151              
152             This should not matter to most use-cases - e.g. even C will be
153             fine here. But if you are using C with calculated indexes to inspect
154             the state of callers to your code and there may be C frames in the way,
155             you will need to somehow account for the difference in stack height.
156              
157             =back
158              
159             =cut
160              
161             =head1 AUTHOR
162              
163             Paul Evans
164              
165             =cut
166              
167             0x55AA;