Debian Codegraph @

upstream/debian-unstable/man3/TAP::Parser::SourceHandler::Perl.3perl

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