Initial Commit

database/perl/lib/pods/perltrap.pod

@@ -0,0 +1,447 @@
+=head1 NAME
+
+perltrap - Perl traps for the unwary
+
+=head1 DESCRIPTION
+
+The biggest trap of all is forgetting to C<use warnings> or use the B<-w>
+switch; see L<warnings> and L<perlrun/-w>. The second biggest trap is not
+making your entire program runnable under C<use strict>.  The third biggest
+trap is not reading the list of changes in this version of Perl; see
+L<perldelta>.
+
+=head2 Awk Traps
+
+Accustomed B<awk> users should take special note of the following:
+
+=over 4
+
+=item *
+
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with C<-n> or C<-p>.
+
+=item *
+
+The English module, loaded via
+
+    use English;
+
+allows you to refer to special variables (like C<$/>) with names (like
+$RS), as though they were in B<awk>; see L<perlvar> for details.
+
+=item *
+
+Semicolons are required after all simple statements in Perl (except
+at the end of a block).  Newline is not a statement delimiter.
+
+=item *
+
+Curly brackets are required on C<if>s and C<while>s.
+
+=item *
+
+Variables begin with "$", "@" or "%" in Perl.
+
+=item *
+
+Arrays index from 0.  Likewise string positions in substr() and
+index().
+
+=item *
+
+You have to decide whether your array has numeric or string indices.
+
+=item *
+
+Hash values do not spring into existence upon mere reference.
+
+=item *
+
+You have to decide whether you want to use string or numeric
+comparisons.
+
+=item *
+
+Reading an input line does not split it for you.  You get to split it
+to an array yourself.  And the split() operator has different
+arguments than B<awk>'s.
+
+=item *
+
+The current input line is normally in $_, not $0.  It generally does
+not have the newline stripped.  ($0 is the name of the program
+executed.)  See L<perlvar>.
+
+=item *
+
+$<I<digit>> does not refer to fields--it refers to substrings matched
+by the last match pattern.
+
+=item *
+
+The print() statement does not add field and record separators unless
+you set C<$,> and C<$\>.  You can set $OFS and $ORS if you're using
+the English module.
+
+=item *
+
+You must open your files before you print to them.
+
+=item *
+
+The range operator is "..", not comma.  The comma operator works as in
+C.
+
+=item *
+
+The match operator is "=~", not "~".  ("~" is the one's complement
+operator, as in C.)
+
+=item *
+
+The exponentiation operator is "**", not "^".  "^" is the XOR
+operator, as in C.  (You know, one could get the feeling that B<awk> is
+basically incompatible with C.)
+
+=item *
+
+The concatenation operator is ".", not the null string.  (Using the
+null string would render C</pat/ /pat/> unparsable, because the third slash
+would be interpreted as a division operator--the tokenizer is in fact
+slightly context sensitive for operators like "/", "?", and ">".
+And in fact, "." itself can be the beginning of a number.)
+
+=item *
+
+The C<next>, C<exit>, and C<continue> keywords work differently.
+
+=item *
+
+
+The following variables work differently:
+
+      Awk	Perl
+      ARGC	scalar @ARGV (compare with $#ARGV)
+      ARGV[0]	$0
+      FILENAME	$ARGV
+      FNR	$. - something
+      FS	(whatever you like)
+      NF	$#Fld, or some such
+      NR	$.
+      OFMT	$#
+      OFS	$,
+      ORS	$\
+      RLENGTH	length($&)
+      RS	$/
+      RSTART	length($`)
+      SUBSEP	$;
+
+=item *
+
+You cannot set $RS to a pattern, only a string.
+
+=item *
+
+When in doubt, run the B<awk> construct through B<a2p> and see what it
+gives you.
+
+=back
+
+=head2 C/C++ Traps
+
+Cerebral C and C++ programmers should take note of the following:
+
+=over 4
+
+=item *
+
+Curly brackets are required on C<if>'s and C<while>'s.
+
+=item *
+
+You must use C<elsif> rather than C<else if>.
+
+=item *
+
+The C<break> and C<continue> keywords from C become in Perl C<last>
+and C<next>, respectively.  Unlike in C, these do I<not> work within a
+C<do { } while> construct.  See L<perlsyn/"Loop Control">.
+
+=item *
+
+The switch statement is called C<given>/C<when> and only available in
+perl 5.10 or newer.  See L<perlsyn/"Switch Statements">.
+
+=item *
+
+Variables begin with "$", "@" or "%" in Perl.
+
+=item *
+
+Comments begin with "#", not "/*" or "//".  Perl may interpret C/C++
+comments as division operators, unterminated regular expressions or
+the defined-or operator.
+
+=item *
+
+You can't take the address of anything, although a similar operator
+in Perl is the backslash, which creates a reference.
+
+=item *
+
+C<ARGV> must be capitalized.  C<$ARGV[0]> is C's C<argv[1]>, and C<argv[0]>
+ends up in C<$0>.
+
+=item *
+
+System calls such as link(), unlink(), rename(), etc. return nonzero for
+success, not 0. (system(), however, returns zero for success.)
+
+=item *
+
+Signal handlers deal with signal names, not numbers.  Use C<kill -l>
+to find their names on your system.
+
+=back
+
+=head2 JavaScript Traps
+
+Judicious JavaScript programmers should take note of the following:
+
+=over 4
+
+=item *
+
+In Perl, binary C<+> is always addition.  C<$string1 + $string2> converts
+both strings to numbers and then adds them.  To concatenate two strings,
+use the C<.> operator.
+
+=item *
+
+The C<+> unary operator doesn't do anything in Perl.  It exists to avoid
+syntactic ambiguities.
+
+=item *
+
+Unlike C<for...in>, Perl's C<for> (also spelled C<foreach>) does not allow
+the left-hand side to be an arbitrary expression.  It must be a variable:
+
+   for my $variable (keys %hash) {
+	...
+   }
+
+Furthermore, don't forget the C<keys> in there, as
+C<foreach my $kv (%hash) {}> iterates over the keys and values, and is
+generally not useful ($kv would be a key, then a value, and so on).
+
+=item *
+
+To iterate over the indices of an array, use C<foreach my $i (0 .. $#array)
+{}>.  C<foreach my $v (@array) {}> iterates over the values.
+
+=item *
+
+Perl requires braces following C<if>, C<while>, C<foreach>, etc.
+
+=item *
+
+In Perl, C<else if> is spelled C<elsif>.
+
+=item *
+
+C<? :> has higher precedence than assignment.  In JavaScript, one can
+write:
+
+    condition ? do_something() : variable = 3
+
+and the variable is only assigned if the condition is false.  In Perl, you
+need parentheses:
+
+    $condition ? do_something() : ($variable = 3);
+
+Or just use C<if>.
+
+=item *
+
+Perl requires semicolons to separate statements.
+
+=item *
+
+Variables declared with C<my> only affect code I<after> the declaration.
+You cannot write C<$x = 1; my $x;> and expect the first assignment to
+affect the same variable.  It will instead assign to an C<$x> declared
+previously in an outer scope, or to a global variable.
+
+Note also that the variable is not visible until the following
+I<statement>.  This means that in C<my $x = 1 + $x> the second $x refers
+to one declared previously.
+
+=item *
+
+C<my> variables are scoped to the current block, not to the current
+function.  If you write C<{my $x;} $x;>, the second C<$x> does not refer to
+the one declared inside the block.
+
+=item *
+
+An object's members cannot be made accessible as variables.  The closest
+Perl equivalent to C<with(object) { method() }> is C<for>, which can alias
+C<$_> to the object:
+
+    for ($object) {
+	$_->method;
+    }
+
+=item *
+
+The object or class on which a method is called is passed as one of the
+method's arguments, not as a separate C<this> value.
+
+=back
+
+=head2 Sed Traps
+
+Seasoned B<sed> programmers should take note of the following:
+
+=over 4
+
+=item *
+
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with C<-n> or C<-p>.
+
+=item *
+
+Backreferences in substitutions use "$" rather than "\".
+
+=item *
+
+The pattern matching metacharacters "(", ")", and "|" do not have backslashes
+in front.
+
+=item *
+
+The range operator is C<...>, rather than comma.
+
+=back
+
+=head2 Shell Traps
+
+Sharp shell programmers should take note of the following:
+
+=over 4
+
+=item *
+
+The backtick operator does variable interpolation without regard to
+the presence of single quotes in the command.
+
+=item *
+
+The backtick operator does no translation of the return value, unlike B<csh>.
+
+=item *
+
+Shells (especially B<csh>) do several levels of substitution on each
+command line.  Perl does substitution in only certain constructs
+such as double quotes, backticks, angle brackets, and search patterns.
+
+=item *
+
+Shells interpret scripts a little bit at a time.  Perl compiles the
+entire program before executing it (except for C<BEGIN> blocks, which
+execute at compile time).
+
+=item *
+
+The arguments are available via @ARGV, not $1, $2, etc.
+
+=item *
+
+The environment is not automatically made available as separate scalar
+variables.
+
+=item *
+
+The shell's C<test> uses "=", "!=", "<" etc for string comparisons and "-eq",
+"-ne", "-lt" etc for numeric comparisons. This is the reverse of Perl, which
+uses C<eq>, C<ne>, C<lt> for string comparisons, and C<==>, C<!=> C<< < >> etc
+for numeric comparisons.
+
+=back
+
+=head2 Perl Traps
+
+Practicing Perl Programmers should take note of the following:
+
+=over 4
+
+=item *
+
+Remember that many operations behave differently in a list
+context than they do in a scalar one.  See L<perldata> for details.
+
+=item *
+
+Avoid barewords if you can, especially all lowercase ones.
+You can't tell by just looking at it whether a bareword is
+a function or a string.  By using quotes on strings and
+parentheses on function calls, you won't ever get them confused.
+
+=item *
+
+You cannot discern from mere inspection which builtins
+are unary operators (like chop() and chdir())
+and which are list operators (like print() and unlink()).
+(Unless prototyped, user-defined subroutines can B<only> be list
+operators, never unary ones.)  See L<perlop> and L<perlsub>.
+
+=item *
+
+People have a hard time remembering that some functions
+default to $_, or @ARGV, or whatever, but that others which
+you might expect to do not.
+
+=item *
+
+The <FH> construct is not the name of the filehandle, it is a readline
+operation on that handle.  The data read is assigned to $_ only if the
+file read is the sole condition in a while loop:
+
+    while (<FH>)      { }
+    while (defined($_ = <FH>)) { }..
+    <FH>;  # data discarded!
+
+=item *
+
+Remember not to use C<=> when you need C<=~>;
+these two constructs are quite different:
+
+    $x =  /foo/;
+    $x =~ /foo/;
+
+=item *
+
+The C<do {}> construct isn't a real loop that you can use
+loop control on.
+
+=item *
+
+Use C<my()> for local variables whenever you can get away with
+it (but see L<perlform> for where you can't).
+Using C<local()> actually gives a local value to a global
+variable, which leaves you open to unforeseen side-effects
+of dynamic scoping.
+
+=item *
+
+If you localize an exported variable in a module, its exported value will
+not change.  The local name becomes an alias to a new value but the
+external name is still an alias for the original.
+
+=back
+
+As always, if any of these are ever officially declared as bugs,
+they'll be fixed and removed.
+