Debian Codegraph @

upstream/debian-unstable/man1/perltrap.1

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 "PERLTRAP 1"
58 .TH PERLTRAP 1 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 perltrap \- Perl traps for the unwary
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 The biggest trap of all is forgetting to \f(CW\*(C`use warnings\*(C'\fR or use the \fB\-w\fR
68 switch; see warnings and "\-w" in perlrun. The second biggest trap is not
69 making your entire program runnable under \f(CW\*(C`use strict\*(C'\fR. The third biggest
70 trap is not reading the list of changes in this version of Perl; see
71 perldelta.
72 .SS "Awk Traps"
73 .IX Subsection "Awk Traps"
74 Accustomed \fBawk\fR users should take special note of the following:
75 .IP \(bu 4
76 A Perl program executes only once, not once for each input line. You can
77 do an implicit loop with \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR.
78 .IP \(bu 4
79 The English module, loaded via
80 .Sp
81 .Vb 1
82 \& use English;
83 .Ve
84 .Sp
85 allows you to refer to special variables (like \f(CW$/\fR) with names (like
86 \&\f(CW$RS\fR), as though they were in \fBawk\fR; see perlvar for details.
87 .IP \(bu 4
88 Semicolons are required after all simple statements in Perl (except
89 at the end of a block). Newline is not a statement delimiter.
90 .IP \(bu 4
91 Curly brackets are required on \f(CW\*(C`if\*(C'\fRs and \f(CW\*(C`while\*(C'\fRs.
92 .IP \(bu 4
93 Variables begin with "$", "@" or "%" in Perl.
94 .IP \(bu 4
95 Arrays index from 0. Likewise string positions in \fBsubstr()\fR and
96 \&\fBindex()\fR.
97 .IP \(bu 4
98 You have to decide whether your array has numeric or string indices.
99 .IP \(bu 4
100 Hash values do not spring into existence upon mere reference.
101 .IP \(bu 4
102 You have to decide whether you want to use string or numeric
103 comparisons.
104 .IP \(bu 4
105 Reading an input line does not split it for you. You get to split it
106 to an array yourself. And the \fBsplit()\fR operator has different
107 arguments than \fBawk\fR's.
108 .IP \(bu 4
109 The current input line is normally in \f(CW$_\fR, not \f(CW$0\fR. It generally does
110 not have the newline stripped. ($0 is the name of the program
111 executed.) See perlvar.
112 .IP \(bu 4
113 $<\fIdigit\fR> does not refer to fields\-\-it refers to substrings matched
114 by the last match pattern.
115 .IP \(bu 4
116 The \fBprint()\fR statement does not add field and record separators unless
117 you set \f(CW$,\fR and \f(CW\*(C`$\e\*(C'\fR. You can set \f(CW$OFS\fR and \f(CW$ORS\fR if you're using
118 the English module.
119 .IP \(bu 4
120 You must open your files before you print to them.
121 .IP \(bu 4
122 The range operator is "..", not comma. The comma operator works as in
123 C.
124 .IP \(bu 4
125 The match operator is "=~", not "~". ("~" is the one's complement
126 operator, as in C.)
127 .IP \(bu 4
128 The exponentiation operator is "**", not "^". "^" is the XOR
129 operator, as in C. (You know, one could get the feeling that \fBawk\fR is
130 basically incompatible with C.)
131 .IP \(bu 4
132 The concatenation operator is ".", not the null string. (Using the
133 null string would render \f(CW\*(C`/pat/ /pat/\*(C'\fR unparsable, because the third slash
134 would be interpreted as a division operator\-\-the tokenizer is in fact
135 slightly context sensitive for operators like "/", "?", and ">".
136 And in fact, "." itself can be the beginning of a number.)
137 .IP \(bu 4
138 The \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, and \f(CW\*(C`continue\*(C'\fR keywords work differently.
139 .IP \(bu 4
140 The following variables work differently:
141 .Sp
142 .Vb 10
143 \& Awk Perl
144 \& ARGC scalar @ARGV (compare with $#ARGV)
145 \& ARGV[0] $0
146 \& FILENAME $ARGV
147 \& FNR $. \- something
148 \& FS (whatever you like)
149 \& NF $#Fld, or some such
150 \& NR $.
151 \& OFMT $#
152 \& OFS $,
153 \& ORS $\e
154 \& RLENGTH length($&)
155 \& RS $/
156 \& RSTART length($\`)
157 \& SUBSEP $;
158 .Ve
159 .IP \(bu 4
160 You cannot set \f(CW$RS\fR to a pattern, only a string.
161 .IP \(bu 4
162 When in doubt, run the \fBawk\fR construct through \fBa2p\fR and see what it
163 gives you.
164 .SS "C/C++ Traps"
165 .IX Subsection "C/C++ Traps"
166 Cerebral C and C++ programmers should take note of the following:
167 .IP \(bu 4
168 Curly brackets are required on \f(CW\*(C`if\*(C'\fR's and \f(CW\*(C`while\*(C'\fR's.
169 .IP \(bu 4
170 You must use \f(CW\*(C`elsif\*(C'\fR rather than \f(CW\*(C`else if\*(C'\fR.
171 .IP \(bu 4
172 The \f(CW\*(C`break\*(C'\fR and \f(CW\*(C`continue\*(C'\fR keywords from C become in Perl \f(CW\*(C`last\*(C'\fR
173 and \f(CW\*(C`next\*(C'\fR, respectively. Unlike in C, these do \fInot\fR work within a
174 \&\f(CW\*(C`do { } while\*(C'\fR construct. See "Loop Control" in perlsyn.
175 .IP \(bu 4
176 The switch statement is called \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR and only available in
177 perl 5.10 or newer. See "Switch Statements" in perlsyn.
178 .IP \(bu 4
179 Variables begin with "$", "@" or "%" in Perl.
180 .IP \(bu 4
181 Comments begin with "#", not "/*" or "//". Perl may interpret C/C++
182 comments as division operators, unterminated regular expressions or
183 the defined-or operator.
184 .IP \(bu 4
185 You can't take the address of anything, although a similar operator
186 in Perl is the backslash, which creates a reference.
187 .IP \(bu 4
188 \&\f(CW\*(C`ARGV\*(C'\fR must be capitalized. \f(CW$ARGV[0]\fR is C's \f(CW\*(C`argv[1]\*(C'\fR, and \f(CW\*(C`argv[0]\*(C'\fR
189 ends up in \f(CW$0\fR.
190 .IP \(bu 4
191 System calls such as \fBlink()\fR, \fBunlink()\fR, \fBrename()\fR, etc. return nonzero for
192 success, not 0. (\fBsystem()\fR, however, returns zero for success.)
193 .IP \(bu 4
194 Signal handlers deal with signal names, not numbers. Use \f(CW\*(C`kill \-l\*(C'\fR
195 to find their names on your system.
196 .SS "JavaScript Traps"
197 .IX Subsection "JavaScript Traps"
198 Judicious JavaScript programmers should take note of the following:
199 .IP \(bu 4
200 In Perl, binary \f(CW\*(C`+\*(C'\fR is always addition. \f(CW\*(C`$string1 + $string2\*(C'\fR converts
201 both strings to numbers and then adds them. To concatenate two strings,
202 use the \f(CW\*(C`.\*(C'\fR operator.
203 .IP \(bu 4
204 The \f(CW\*(C`+\*(C'\fR unary operator doesn't do anything in Perl. It exists to avoid
205 syntactic ambiguities.
206 .IP \(bu 4
207 Unlike \f(CW\*(C`for...in\*(C'\fR, Perl's \f(CW\*(C`for\*(C'\fR (also spelled \f(CW\*(C`foreach\*(C'\fR) does not allow
208 the left-hand side to be an arbitrary expression. It must be a variable:
209 .Sp
210 .Vb 3
211 \& for my $variable (keys %hash) {
212 \& ...
213 \& }
214 .Ve
215 .Sp
216 Furthermore, don't forget the \f(CW\*(C`keys\*(C'\fR in there, as
217 \&\f(CW\*(C`foreach my $kv (%hash) {}\*(C'\fR iterates over the keys and values, and is
218 generally not useful ($kv would be a key, then a value, and so on).
219 .IP \(bu 4
220 To iterate over the indices of an array, use \f(CW\*(C`foreach my $i (0 .. $#array)
221 {}\*(C'\fR. \f(CW\*(C`foreach my $v (@array) {}\*(C'\fR iterates over the values.
222 .IP \(bu 4
223 Perl requires braces following \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`while\*(C'\fR, \f(CW\*(C`foreach\*(C'\fR, etc.
224 .IP \(bu 4
225 In Perl, \f(CW\*(C`else if\*(C'\fR is spelled \f(CW\*(C`elsif\*(C'\fR.
226 .IP \(bu 4
227 \&\f(CW\*(C`? :\*(C'\fR has higher precedence than assignment. In JavaScript, one can
228 write:
229 .Sp
230 .Vb 1
231 \& condition ? do_something() : variable = 3
232 .Ve
233 .Sp
234 and the variable is only assigned if the condition is false. In Perl, you
235 need parentheses:
236 .Sp
237 .Vb 1
238 \& $condition ? do_something() : ($variable = 3);
239 .Ve
240 .Sp
241 Or just use \f(CW\*(C`if\*(C'\fR.
242 .IP \(bu 4
243 Perl requires semicolons to separate statements.
244 .IP \(bu 4
245 Variables declared with \f(CW\*(C`my\*(C'\fR only affect code \fIafter\fR the declaration.
246 You cannot write \f(CW\*(C`$x = 1; my $x;\*(C'\fR and expect the first assignment to
247 affect the same variable. It will instead assign to an \f(CW$x\fR declared
248 previously in an outer scope, or to a global variable.
249 .Sp
250 Note also that the variable is not visible until the following
251 \&\fIstatement\fR. This means that in \f(CW\*(C`my $x = 1 + $x\*(C'\fR the second \f(CW$x\fR refers
252 to one declared previously.
253 .IP \(bu 4
254 \&\f(CW\*(C`my\*(C'\fR variables are scoped to the current block, not to the current
255 function. If you write \f(CW\*(C`{my $x;} $x;\*(C'\fR, the second \f(CW$x\fR does not refer to
256 the one declared inside the block.
257 .IP \(bu 4
258 An object's members cannot be made accessible as variables. The closest
259 Perl equivalent to \f(CW\*(C`with(object) { method() }\*(C'\fR is \f(CW\*(C`for\*(C'\fR, which can alias
260 \&\f(CW$_\fR to the object:
261 .Sp
262 .Vb 3
263 \& for ($object) {
264 \& $_\->method;
265 \& }
266 .Ve
267 .IP \(bu 4
268 The object or class on which a method is called is passed as one of the
269 method's arguments, not as a separate \f(CW\*(C`this\*(C'\fR value.
270 .SS "Sed Traps"
271 .IX Subsection "Sed Traps"
272 Seasoned \fBsed\fR programmers should take note of the following:
273 .IP \(bu 4
274 A Perl program executes only once, not once for each input line. You can
275 do an implicit loop with \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR.
276 .IP \(bu 4
277 Backreferences in substitutions use "$" rather than "\e".
278 .IP \(bu 4
279 The pattern matching metacharacters "(", ")", and "|" do not have backslashes
280 in front.
281 .IP \(bu 4
282 The range operator is \f(CW\*(C`...\*(C'\fR, rather than comma.
283 .SS "Shell Traps"
284 .IX Subsection "Shell Traps"
285 Sharp shell programmers should take note of the following:
286 .IP \(bu 4
287 The backtick operator does variable interpolation without regard to
288 the presence of single quotes in the command.
289 .IP \(bu 4
290 The backtick operator does no translation of the return value, unlike \fBcsh\fR.
291 .IP \(bu 4
292 Shells (especially \fBcsh\fR) do several levels of substitution on each
293 command line. Perl does substitution in only certain constructs
294 such as double quotes, backticks, angle brackets, and search patterns.
295 .IP \(bu 4
296 Shells interpret scripts a little bit at a time. Perl compiles the
297 entire program before executing it (except for \f(CW\*(C`BEGIN\*(C'\fR blocks, which
298 execute at compile time).
299 .IP \(bu 4
300 The arguments are available via \f(CW@ARGV\fR, not \f(CW$1\fR, \f(CW$2\fR, etc.
301 .IP \(bu 4
302 The environment is not automatically made available as separate scalar
303 variables.
304 .IP \(bu 4
305 The shell's \f(CW\*(C`test\*(C'\fR uses "=", "!=", "<" etc for string comparisons and "\-eq",
306 "\-ne", "\-lt" etc for numeric comparisons. This is the reverse of Perl, which
307 uses \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR, \f(CW\*(C`lt\*(C'\fR for string comparisons, and \f(CW\*(C`==\*(C'\fR, \f(CW\*(C`!=\*(C'\fR \f(CW\*(C`<\*(C'\fR etc
308 for numeric comparisons.
309 .SS "Perl Traps"
310 .IX Subsection "Perl Traps"
311 Practicing Perl Programmers should take note of the following:
312 .IP \(bu 4
313 Remember that many operations behave differently in a list
314 context than they do in a scalar one. See perldata for details.
315 .IP \(bu 4
316 Avoid barewords if you can, especially all lowercase ones.
317 You can't tell by just looking at it whether a bareword is
318 a function or a string. By using quotes on strings and
319 parentheses on function calls, you won't ever get them confused.
320 .IP \(bu 4
321 You cannot discern from mere inspection which builtins
322 are unary operators (like \fBchop()\fR and \fBchdir()\fR)
323 and which are list operators (like \fBprint()\fR and \fBunlink()\fR).
324 (Unless prototyped, user-defined subroutines can \fBonly\fR be list
325 operators, never unary ones.) See perlop and perlsub.
326 .IP \(bu 4
327 People have a hard time remembering that some functions
328 default to \f(CW$_\fR, or \f(CW@ARGV\fR, or whatever, but that others which
329 you might expect to do not.
330 .IP \(bu 4
331 The <FH> construct is not the name of the filehandle, it is a readline
332 operation on that handle. The data read is assigned to \f(CW$_\fR only if the
333 file read is the sole condition in a while loop:
334 .Sp
335 .Vb 3
336 \& while (<FH>) { }
337 \& while (defined($_ = <FH>)) { }..
338 \& <FH>; # data discarded!
339 .Ve
340 .IP \(bu 4
341 Remember not to use \f(CW\*(C`=\*(C'\fR when you need \f(CW\*(C`=~\*(C'\fR;
342 these two constructs are quite different:
343 .Sp
344 .Vb 2
345 \& $x = /foo/;
346 \& $x =~ /foo/;
347 .Ve
348 .IP \(bu 4
349 The \f(CW\*(C`do {}\*(C'\fR construct isn't a real loop that you can use
350 loop control on.
351 .IP \(bu 4
352 Use \f(CWmy()\fR for local variables whenever you can get away with
353 it (but see perlform for where you can't).
354 Using \f(CWlocal()\fR actually gives a local value to a global
355 variable, which leaves you open to unforeseen side-effects
356 of dynamic scoping.
357 .IP \(bu 4
358 If you localize an exported variable in a module, its exported value will
359 not change. The local name becomes an alias to a new value but the
360 external name is still an alias for the original.
361 .PP
362 As always, if any of these are ever officially declared as bugs,
363 they'll be fixed and removed.