Debian Codegraph @

upstream/mageia-cauldron/man1/perltrap.1

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