diff --git a/doc/Language/exceptions.pod6 b/doc/Language/exceptions.pod6 index 043ea2b64..0795b3887 100644 --- a/doc/Language/exceptions.pod6 +++ b/doc/Language/exceptions.pod6 @@ -47,7 +47,8 @@ problem. =head1 Catching exceptions -It's possible to handle exceptional circumstances by supplying a C block: +It's possible to handle exceptional circumstances by supplying a +C block: die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy")); @@ -57,18 +58,22 @@ It's possible to handle exceptional circumstances by supplying a C block: # OUTPUT: «some kind of IO exception was caught!» -Here, we are saying that if any exception of type C occurs, then the -message C will be sent to I, -which is what C<$*ERR.say> does, getting displayed on whatever constitutes the -standard error device in that moment, which will probably be the console by -default. +Here, we are saying that if any exception of type C occurs, then +the message C will be sent to +I, which is what C<$*ERR.say> does, getting displayed on +whatever constitutes the standard error device in that moment, which +will probably be the console by default. -A X|CATCH> block uses smartmatching similar to how C -smartmatches on options, thus it's possible to catch and handle various -categories of exceptions inside a C block. +Note that the match target is a role. To allow user defined exceptions +to match in the same manner, they must implement the given role. Just +existing in the same namespace will make them look alike but won't match +in a C block. -To handle all exceptions, use a C statement. This example prints out -almost the same information as the normal backtrace printer. +A C block places any exception thrown in its topic variable +(C<$_>), thus it's possible to catch and handle various categories of +exceptions inside a C block. To handle all exceptions, use a +C statement. This example prints out almost the same +information as the normal backtrace printer: CATCH { default { @@ -81,9 +86,18 @@ almost the same information as the normal backtrace printer. } } -Note that the match target is a role. To allow user defined exceptions to match -in the same manner, they must implement the given role. Just existing in the -same namespace will look alike but won't match in a C block. +While this is a very common pattern, it is not strictly necessary to use +C or C in a C block. This is done to prevent the +control flow from reaching the end of the block where, unless the +exception has been L, the exception +will continue to be thrown. Allowing this can be used for logging +purposes, for instance: + +=for code :skip-test +# In the outermost block of a script... +my IO::Handle:D $log = open sprintf('logs/%d-%d.txt', $*INIT-INSTANT, $*PID), :a; +CATCH { $log.printf: "[%d] Died with %s: %s$?NL", now, .^name, .message } +END { $log.close } =head2 Exception handlers and enclosing blocks