Debian Codegraph @

upstream/mageia-cauldron/man3pm/TAP::Parser::SourceHandler::Perl.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 "TAP::Parser::SourceHandler::Perl 3pm"
61 .TH TAP::Parser::SourceHandler::Perl 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 TAP::Parser::SourceHandler::Perl \- Stream TAP from a Perl executable
68 .SH VERSION
69 .IX Header "VERSION"
70 Version 3.50
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 2
74 \& use TAP::Parser::Source;
75 \& use TAP::Parser::SourceHandler::Perl;
76 \&
77 \& my $source = TAP::Parser::Source\->new\->raw( \e\*(Aqscript.pl\*(Aq );
78 \& $source\->assemble_meta;
79 \&
80 \& my $class = \*(AqTAP::Parser::SourceHandler::Perl\*(Aq;
81 \& my $vote = $class\->can_handle( $source );
82 \& my $iter = $class\->make_iterator( $source );
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 This is a \fIPerl\fR TAP::Parser::SourceHandler \- it has 2 jobs:
87 .PP
88 1. Figure out if the TAP::Parser::Source it\*(Aqs given is actually a Perl
89 script ("can_handle").
90 .PP
91 2. Creates an iterator for Perl sources ("make_iterator").
92 .PP
93 Unless you\*(Aqre writing a plugin or subclassing TAP::Parser, you probably
94 won\*(Aqt need to use this module directly.
95 .SH METHODS
96 .IX Header "METHODS"
97 .SS "Class Methods"
98 .IX Subsection "Class Methods"
99 \fR\f(CI\*(C`can_handle\*(C'\fR\fI\fR
100 .IX Subsection "can_handle"
101 .PP
102 .Vb 1
103 \& my $vote = $class\->can_handle( $source );
104 .Ve
105 .PP
106 Only votes if \f(CW$source\fR looks like a file. Casts the following votes:
107 .PP
108 .Vb 6
109 \& 0.9 if it has a shebang ala "#!...perl"
110 \& 0.3 if it has any shebang
111 \& 0.8 if it\*(Aqs a .t file
112 \& 0.9 if it\*(Aqs a .pl file
113 \& 0.75 if it\*(Aqs in a \*(Aqt\*(Aq directory
114 \& 0.25 by default (backwards compat)
115 .Ve
116 .PP
117 \fR\f(CI\*(C`make_iterator\*(C'\fR\fI\fR
118 .IX Subsection "make_iterator"
119 .PP
120 .Vb 1
121 \& my $iterator = $class\->make_iterator( $source );
122 .Ve
123 .PP
124 Constructs & returns a new TAP::Parser::Iterator::Process for the source.
125 Assumes \f(CW\*(C`$source\->raw\*(C'\fR contains a reference to the perl script. \f(CW\*(C`croak\*(C'\fRs
126 if the file could not be found.
127 .PP
128 The command to run is built as follows:
129 .PP
130 .Vb 1
131 \& $perl @switches $perl_script @test_args
132 .Ve
133 .PP
134 The perl command to use is determined by "get_perl". The command generated
135 is guaranteed to preserve:
136 .PP
137 .Vb 3
138 \& PERL5LIB
139 \& PERL5OPT
140 \& Taint Mode, if set in the script\*(Aqs shebang
141 .Ve
142 .PP
143 \&\fINote:\fR the command generated will \fInot\fR respect any shebang line defined in
144 your Perl script. This is only a problem if you have compiled a custom version
145 of Perl or if you want to use a specific version of Perl for one test and a
146 different version for another, for example:
147 .PP
148 .Vb 2
149 \& #!/path/to/a/custom_perl \-\-some \-\-args
150 \& #!/usr/local/perl\-5.6/bin/perl \-w
151 .Ve
152 .PP
153 Currently you need to write a plugin to get around this.
154 .PP
155 \fR\f(CI\*(C`get_taint\*(C'\fR\fI\fR
156 .IX Subsection "get_taint"
157 .PP
158 Decode any taint switches from a Perl shebang line.
159 .PP
160 .Vb 2
161 \& # $taint will be \*(Aqt\*(Aq
162 \& my $taint = TAP::Parser::SourceHandler::Perl\->get_taint( \*(Aq#!/usr/bin/perl \-t\*(Aq );
163 \&
164 \& # $untaint will be undefined
165 \& my $untaint = TAP::Parser::SourceHandler::Perl\->get_taint( \*(Aq#!/usr/bin/perl\*(Aq );
166 .Ve
167 .PP
168 \fR\f(CI\*(C`get_perl\*(C'\fR\fI\fR
169 .IX Subsection "get_perl"
170 .PP
171 Gets the version of Perl currently running the test suite.
172 .SH SUBCLASSING
173 .IX Header "SUBCLASSING"
174 Please see "SUBCLASSING" in TAP::Parser for a subclassing overview.
175 .SS Example
176 .IX Subsection "Example"
177 .Vb 1
178 \& package MyPerlSourceHandler;
179 \&
180 \& use strict;
181 \&
182 \& use TAP::Parser::SourceHandler::Perl;
183 \&
184 \& use base \*(AqTAP::Parser::SourceHandler::Perl\*(Aq;
185 \&
186 \& # use the version of perl from the shebang line in the test file
187 \& sub get_perl {
188 \& my $self = shift;
189 \& if (my $shebang = $self\->shebang( $self\->{file} )) {
190 \& $shebang =~ /^#!(.*\ebperl.*?)(?:(?:\es)|(?:$))/;
191 \& return $1 if $1;
192 \& }
193 \& return $self\->SUPER::get_perl(@_);
194 \& }
195 .Ve
196 .SH "SEE ALSO"
197 .IX Header "SEE ALSO"
198 TAP::Object,
199 TAP::Parser,
200 TAP::Parser::IteratorFactory,
201 TAP::Parser::SourceHandler,
202 TAP::Parser::SourceHandler::Executable,
203 TAP::Parser::SourceHandler::File,
204 TAP::Parser::SourceHandler::Handle,
205 TAP::Parser::SourceHandler::RawTAP