This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perltrap: #109408
[perl5.git] / pod / perltrap.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perltrap - Perl traps for the unwary
4
5=head1 DESCRIPTION
6
9fda99eb
DC
7The biggest trap of all is forgetting to C<use warnings> or use the B<-w>
8switch; see L<perllexwarn> and L<perlrun>. The second biggest trap is not
9making your entire program runnable under C<use strict>. The third biggest
10trap is not reading the list of changes in this version of Perl; see
11L<perldelta>.
a0d0e21e
LW
12
13=head2 Awk Traps
14
15Accustomed B<awk> users should take special note of the following:
16
17=over 4
18
19=item *
20
6014d0cb
MS
21A Perl program executes only once, not once for each input line. You can
22do an implicit loop with C<-n> or C<-p>.
23
24=item *
25
a0d0e21e
LW
26The English module, loaded via
27
28 use English;
29
54310121 30allows you to refer to special variables (like C<$/>) with names (like
19799a22 31$RS), as though they were in B<awk>; see L<perlvar> for details.
a0d0e21e
LW
32
33=item *
34
35Semicolons are required after all simple statements in Perl (except
36at the end of a block). Newline is not a statement delimiter.
37
38=item *
39
40Curly brackets are required on C<if>s and C<while>s.
41
42=item *
43
5db417f7 44Variables begin with "$", "@" or "%" in Perl.
a0d0e21e
LW
45
46=item *
47
48Arrays index from 0. Likewise string positions in substr() and
49index().
50
51=item *
52
53You have to decide whether your array has numeric or string indices.
54
55=item *
56
aa689395 57Hash values do not spring into existence upon mere reference.
a0d0e21e
LW
58
59=item *
60
61You have to decide whether you want to use string or numeric
62comparisons.
63
64=item *
65
66Reading an input line does not split it for you. You get to split it
54310121
PP
67to an array yourself. And the split() operator has different
68arguments than B<awk>'s.
a0d0e21e
LW
69
70=item *
71
72The current input line is normally in $_, not $0. It generally does
73not have the newline stripped. ($0 is the name of the program
74executed.) See L<perlvar>.
75
76=item *
77
c47ff5f1 78$<I<digit>> does not refer to fields--it refers to substrings matched
8b0a4b75 79by the last match pattern.
a0d0e21e
LW
80
81=item *
82
83The print() statement does not add field and record separators unless
8b0a4b75 84you set C<$,> and C<$\>. You can set $OFS and $ORS if you're using
a0d0e21e
LW
85the English module.
86
87=item *
88
89You must open your files before you print to them.
90
91=item *
92
93The range operator is "..", not comma. The comma operator works as in
94C.
95
96=item *
97
98The match operator is "=~", not "~". ("~" is the one's complement
99operator, as in C.)
100
101=item *
102
103The exponentiation operator is "**", not "^". "^" is the XOR
104operator, as in C. (You know, one could get the feeling that B<awk> is
105basically incompatible with C.)
106
107=item *
108
109The concatenation operator is ".", not the null string. (Using the
5f05dabc
PP
110null string would render C</pat/ /pat/> unparsable, because the third slash
111would be interpreted as a division operator--the tokenizer is in fact
c47ff5f1 112slightly context sensitive for operators like "/", "?", and ">".
a0d0e21e
LW
113And in fact, "." itself can be the beginning of a number.)
114
115=item *
116
117The C<next>, C<exit>, and C<continue> keywords work differently.
118
119=item *
120
121
122The following variables work differently:
123
124 Awk Perl
9fda99eb 125 ARGC scalar @ARGV (compare with $#ARGV)
a0d0e21e
LW
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
142You cannot set $RS to a pattern, only a string.
143
144=item *
145
146When in doubt, run the B<awk> construct through B<a2p> and see what it
147gives you.
148
149=back
150
6ec4bd10 151=head2 C/C++ Traps
a0d0e21e 152
6ec4bd10 153Cerebral C and C++ programmers should take note of the following:
a0d0e21e
LW
154
155=over 4
156
157=item *
158
159Curly brackets are required on C<if>'s and C<while>'s.
160
161=item *
162
163You must use C<elsif> rather than C<else if>.
164
165=item *
166
6ec4bd10
MS
167The C<break> and C<continue> keywords from C become in Perl C<last>
168and C<next>, respectively. Unlike in C, these do I<not> work within a
169C<do { } while> construct. See L<perlsyn/"Loop Control">.
a0d0e21e
LW
170
171=item *
172
cabc01fc 173The switch statement is called C<given/when> and only available in
48238296 174perl 5.10 or newer. See L<perlsyn/"Switch Statements">.
a0d0e21e
LW
175
176=item *
177
5db417f7 178Variables begin with "$", "@" or "%" in Perl.
a0d0e21e
LW
179
180=item *
181
6014d0cb
MS
182Comments begin with "#", not "/*" or "//". Perl may interpret C/C++
183comments as division operators, unterminated regular expressions or
184the defined-or operator.
a0d0e21e
LW
185
186=item *
187
188You can't take the address of anything, although a similar operator
5f05dabc 189in Perl is the backslash, which creates a reference.
a0d0e21e
LW
190
191=item *
192
4633a7c4
LW
193C<ARGV> must be capitalized. C<$ARGV[0]> is C's C<argv[1]>, and C<argv[0]>
194ends up in C<$0>.
a0d0e21e
LW
195
196=item *
197
198System calls such as link(), unlink(), rename(), etc. return nonzero for
9fda99eb 199success, not 0. (system(), however, returns zero for success.)
a0d0e21e
LW
200
201=item *
202
203Signal handlers deal with signal names, not numbers. Use C<kill -l>
204to find their names on your system.
205
206=back
207
208=head2 Sed Traps
209
210Seasoned B<sed> programmers should take note of the following:
211
212=over 4
213
214=item *
215
6014d0cb
MS
216A Perl program executes only once, not once for each input line. You can
217do an implicit loop with C<-n> or C<-p>.
218
219=item *
220
a0d0e21e
LW
221Backreferences in substitutions use "$" rather than "\".
222
223=item *
224
225The pattern matching metacharacters "(", ")", and "|" do not have backslashes
226in front.
227
228=item *
229
230The range operator is C<...>, rather than comma.
231
232=back
233
234=head2 Shell Traps
235
236Sharp shell programmers should take note of the following:
237
238=over 4
239
240=item *
241
54310121 242The backtick operator does variable interpolation without regard to
a0d0e21e
LW
243the presence of single quotes in the command.
244
245=item *
246
54310121 247The backtick operator does no translation of the return value, unlike B<csh>.
a0d0e21e
LW
248
249=item *
250
251Shells (especially B<csh>) do several levels of substitution on each
5f05dabc 252command line. Perl does substitution in only certain constructs
54310121 253such as double quotes, backticks, angle brackets, and search patterns.
a0d0e21e
LW
254
255=item *
256
257Shells interpret scripts a little bit at a time. Perl compiles the
258entire program before executing it (except for C<BEGIN> blocks, which
259execute at compile time).
260
261=item *
262
263The arguments are available via @ARGV, not $1, $2, etc.
264
265=item *
266
267The environment is not automatically made available as separate scalar
268variables.
269
8886331d
NC
270=item *
271
272The shell's C<test> uses "=", "!=", "<" etc for string comparisons and "-eq",
273"-ne", "-lt" etc for numeric comparisons. This is the reverse of Perl, which
274uses C<eq>, C<ne>, C<lt> for string comparisons, and C<==>, C<!=> C<< < >> etc
275for numeric comparisons.
276
a0d0e21e
LW
277=back
278
279=head2 Perl Traps
280
281Practicing Perl Programmers should take note of the following:
282
283=over 4
284
285=item *
286
287Remember that many operations behave differently in a list
288context than they do in a scalar one. See L<perldata> for details.
289
290=item *
291
68dc0745 292Avoid barewords if you can, especially all lowercase ones.
54310121
PP
293You can't tell by just looking at it whether a bareword is
294a function or a string. By using quotes on strings and
5f05dabc 295parentheses on function calls, you won't ever get them confused.
a0d0e21e
LW
296
297=item *
298
54310121
PP
299You cannot discern from mere inspection which builtins
300are unary operators (like chop() and chdir())
a0d0e21e 301and which are list operators (like print() and unlink()).
9fda99eb
DC
302(Unless prototyped, user-defined subroutines can B<only> be list
303operators, never unary ones.) See L<perlop> and L<perlsub>.
a0d0e21e
LW
304
305=item *
306
748a9306 307People have a hard time remembering that some functions
a0d0e21e 308default to $_, or @ARGV, or whatever, but that others which
54310121 309you might expect to do not.
a0d0e21e 310
6dbacca0 311=item *
a0d0e21e 312
c47ff5f1 313The <FH> construct is not the name of the filehandle, it is a readline
5f05dabc 314operation on that handle. The data read is assigned to $_ only if the
748a9306
LW
315file read is the sole condition in a while loop:
316
317 while (<FH>) { }
54310121 318 while (defined($_ = <FH>)) { }..
748a9306
LW
319 <FH>; # data discarded!
320
6dbacca0 321=item *
748a9306 322
19799a22 323Remember not to use C<=> when you need C<=~>;
a0d0e21e
LW
324these two constructs are quite different:
325
326 $x = /foo/;
327 $x =~ /foo/;
328
329=item *
330
54310121 331The C<do {}> construct isn't a real loop that you can use
a0d0e21e
LW
332loop control on.
333
334=item *
335
54310121
PP
336Use C<my()> for local variables whenever you can get away with
337it (but see L<perlform> for where you can't).
338Using C<local()> actually gives a local value to a global
a0d0e21e
LW
339variable, which leaves you open to unforeseen side-effects
340of dynamic scoping.
341
c07a80fd
PP
342=item *
343
344If you localize an exported variable in a module, its exported value will
345not change. The local name becomes an alias to a new value but the
346external name is still an alias for the original.
347
a0d0e21e
LW
348=back
349
54310121 350As always, if any of these are ever officially declared as bugs,
6dbacca0
PP
351they'll be fixed and removed.
352