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