Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Tools::Exception.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Tools::Exception 3pm"
61 .TH Test2::Tools::Exception 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Tools::Exception \- Test2 based tools for checking exceptions
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This is the Test2 implementation of code used to test exceptions. This is
71 similar to Test::Fatal, but it intentionally does much less.
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& use Test2::Tools::Exception qw/dies lives/;
76 \&
77 \& like(
78 \& dies { die \*(Aqxxx\*(Aq },
79 \& qr/xxx/,
80 \& "Got exception"
81 \& );
82 \&
83 \& ok(lives { ... }, "did not die") or note($@);
84 .Ve
85 .SH EXPORTS
86 .IX Header "EXPORTS"
87 All subs are exported by default.
88 .ie n .IP "$e = dies { ... }" 4
89 .el .IP "\f(CW$e\fR = dies { ... }" 4
90 .IX Item "$e = dies { ... }"
91 This will trap any exception the codeblock throws. If no exception is thrown
92 the sub will return undef. If an exception is thrown it will be returned. This
93 function preserves \f(CW$@\fR, it will not be altered from its value before the sub
94 is called.
95 .ie n .IP "$bool = lives { ... }" 4
96 .el .IP "\f(CW$bool\fR = lives { ... }" 4
97 .IX Item "$bool = lives { ... }"
98 This will trap any exception thrown in the codeblock. It will return true when
99 there is no exception, and false when there is. \f(CW$@\fR is preserved from before
100 the sub is called when there is no exception. When an exception is trapped
101 \&\f(CW$@\fR will have the exception so that you can look at it.
102 .ie n .IP "$bool = try_ok { ... }" 4
103 .el .IP "\f(CW$bool\fR = try_ok { ... }" 4
104 .IX Item "$bool = try_ok { ... }"
105 .PD 0
106 .ie n .IP "$bool = try_ok { ... } ""Test Description""" 4
107 .el .IP "\f(CW$bool\fR = try_ok { ... } ""Test Description""" 4
108 .IX Item "$bool = try_ok { ... } ""Test Description"""
109 .PD
110 This will run the code block trapping any exception. If there is no exception a
111 passing event will be issued. If the test fails a failing event will be issued,
112 and the exception will be reported as diagnostics.
113 .Sp
114 \&\fBNote:\fR This function does not preserve \f(CW$@\fR on failure, it will be set to
115 the exception the codeblock throws, this is by design so that you can obtain
116 the exception if desired.
117 .SH "DIFFERENCES FROM TEST::FATAL"
118 .IX Header "DIFFERENCES FROM TEST::FATAL"
119 Test::Fatal sets \f(CW$Test::Builder::Level\fR such that failing tests inside the
120 exception block will report to the line where \f(CWexception()\fR is called. I
121 disagree with this, and think the actual line of the failing test is
122 more important. Ultimately, though Test::Fatal cannot be changed, people
123 probably already depend on that behavior.
124 .SH SOURCE
125 .IX Header "SOURCE"
126 The source code repository for Test2\-Suite can be found at
127 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
128 .SH MAINTAINERS
129 .IX Header "MAINTAINERS"
130 .IP "Chad Granum <[email protected]>" 4
131 .IX Item "Chad Granum <[email protected]>"
132 .SH AUTHORS
133 .IX Header "AUTHORS"
134 .IP "Chad Granum <[email protected]>" 4
135 .IX Item "Chad Granum <[email protected]>"
136 .SH COPYRIGHT
137 .IX Header "COPYRIGHT"
138 Copyright Chad Granum <[email protected]>.
139 .PP
140 This program is free software; you can redistribute it and/or
141 modify it under the same terms as Perl itself.
142 .PP
143 See \fIhttp://dev.perl.org/licenses/\fR