This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
YA resync with mainstem, including VMS patches from others
[perl5.git] / pod / perltrap.pod
index 9382789..c59ecc4 100644 (file)
@@ -22,7 +22,7 @@ The English module, loaded via
     use English;
 
 allows you to refer to special variables (like C<$/>) with names (like
-C<$RS>), as though they were in B<awk>; see L<perlvar> for details.
+$RS), as though they were in B<awk>; see L<perlvar> for details.
 
 =item *
 
@@ -35,7 +35,7 @@ Curly brackets are required on C<if>s and C<while>s.
 
 =item *
 
-Variables begin with "$" or "@" in Perl.
+Variables begin with "$", "@" or "%" in Perl.
 
 =item *
 
@@ -69,7 +69,7 @@ executed.)  See L<perlvar>.
 
 =item *
 
-$E<lt>I<digit>E<gt> does not refer to fields--it refers to substrings matched
+$<I<digit>> does not refer to fields--it refers to substrings matched
 by the last match pattern.
 
 =item *
@@ -103,7 +103,7 @@ basically incompatible with C.)
 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 "E<gt>".
+slightly context sensitive for operators like "/", "?", and ">".
 And in fact, "." itself can be the beginning of a number.)
 
 =item *
@@ -160,7 +160,7 @@ You must use C<elsif> rather than C<else if>.
 
 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.
+Unlike in C, these do I<not> work within a C<do { } while> construct.
 
 =item *
 
@@ -168,13 +168,7 @@ There's no switch statement.  (But it's easy to build one on the fly.)
 
 =item *
 
-Variables begin with "$" or "@" in Perl.
-
-=item *
-
-C<printf()> does not implement the "*" format for interpolating
-field widths, but it's trivial to use interpolation of double-quoted
-strings to achieve the same effect.
+Variables begin with "$", "@" or "%" in Perl.
 
 =item *
 
@@ -295,7 +289,7 @@ you might expect to do not.
 
 =item *
 
-The E<lt>FHE<gt> construct is not the name of the filehandle, it is a readline
+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:
 
@@ -305,7 +299,7 @@ file read is the sole condition in a while loop:
 
 =item *
 
-Remember not to use "C<=>" when you need "C<=~>";
+Remember not to use C<=> when you need C<=~>;
 these two constructs are quite different:
 
     $x =  /foo/;
@@ -392,8 +386,9 @@ Everything else.
 =back
 
 If you find an example of a conversion trap that is not listed here,
-please submit it to Bill Middleton <F<wjm@best.com>> for inclusion.
-Also note that at least some of these can be caught with B<-w>.
+please submit it to <F<perlbug@perl.org>> for inclusion.
+Also note that at least some of these can be caught with the
+C<use warnings> pragma or the B<-w> switch.
 
 =head2 Discontinuance, Deprecation, and BugFix traps
 
@@ -424,7 +419,7 @@ behave differently in perl4 vs. perl5, because the packages don't exist.
     $a=1;$b=2;$c=3;$var=4;
     print "$a::$b::$c ";
     print "$var::abc::xyz\n";
+
     # perl4 prints: 1::2::3 4::abc::xyz
     # perl5 prints: 3
 
@@ -451,8 +446,8 @@ Also see precedence traps, for parsing C<$:>.
 The second and third arguments of C<splice()> are now evaluated in scalar
 context (as the Camel says) rather than list context.
 
-    sub sub1{return(0,2) }          # return a 2-elem array
-    sub sub2{ return(1,2,3)}        # return a 3-elem array
+    sub sub1{return(0,2) }          # return a 2-element list
+    sub sub2{ return(1,2,3)}        # return a 3-element list
     @a1 = ("a","b","c","d","e");
     @a2 = splice(@a1,&sub1,&sub2);
     print join(' ',@a2),"\n";
@@ -585,30 +580,18 @@ number of elements in the resulting list.
     # perl4 prints: second new
     # perl5 prints: 3
 
-=item * Discontinuance
-
-In Perl 4 (and versions of Perl 5 before 5.004), C<'\r'> characters in
-Perl code were silently allowed, although they could cause (mysterious!)
-failures in certain constructs, particularly here documents.  Now,
-C<'\r'> characters cause an immediate fatal error.  (Note: In this
-example, the notation B<\015> represents the incorrect line
-ending. Depending upon your text viewer, it will look different.)
-
-    print "foo";\015
-    print "bar";
-
-    # perl4     prints: foobar
-    # perl5.003 prints: foobar
-    # perl5.004 dies: Illegal character \015 (carriage return)
-
-See L<perldiag> for full details.
-
 =item * Deprecation
 
 Some error messages will be different.
 
 =item * Discontinuance
 
+In Perl 4, if in list context the delimiters to the first argument of
+C<split()> were C<??>, the result would be placed in C<@_> as well as
+being returned.   Perl 5 has more respect for your subroutine arguments.
+
+=item * Discontinuance
+
 Some bugs may have been inadvertently removed.  :-)
 
 =back
@@ -650,6 +633,23 @@ Better parsing in perl 5
     # perl4 prints: is zero
     # perl5 warns: "Useless use of a constant in void context" if using -w
 
+=item * Parsing
+
+String interpolation of the C<$#array> construct differs when braces
+are to used around the name.
+
+    @ = (1..3);
+    print "${#a}";
+
+    # perl4 prints: 2
+    # perl5 fails with syntax error
+
+    @ = (1..3);
+    print "$#{a}";
+
+    # perl4 prints: {a}
+    # perl5 prints: 2
+
 =back
 
 =head2 Numerical Traps
@@ -698,6 +698,30 @@ Logical tests now return an null, instead of 0
 Also see L<"General Regular Expression Traps using s///, etc.">
 for another example of this new feature...
 
+=item * Bitwise string ops
+
+When bitwise operators which can operate upon either numbers or
+strings (C<& | ^ ~>) are given only strings as arguments, perl4 would
+treat the operands as bitstrings so long as the program contained a call
+to the C<vec()> function. perl5 treats the string operands as bitstrings.
+(See L<perlop/Bitwise String Operators> for more details.)
+
+    $fred = "10";
+    $barney = "12";
+    $betty = $fred & $barney;
+    print "$betty\n";
+    # Uncomment the next line to change perl4's behavior
+    # ($dummy) = vec("dummy", 0, 0);
+
+    # Perl4 prints:
+    8
+
+    # Perl5 prints:
+    10
+
+    # If vec() is used anywhere in the program, both print:
+    10
+
 =back
 
 =head2 General data type traps
@@ -744,6 +768,9 @@ Hashes get defined before use
     # perl4 prints:
     # perl5 dies: hash %h defined
 
+Perl will now generate a warning when it sees defined(@a) and
+defined(%h).
+
 =item * (Globs)
 
 glob assignment from variable to variable will fail if the assigned
@@ -757,15 +784,11 @@ variable is localized subsequent to the assignment
     # perl4 prints: This is Perl 4
     # perl5 prints:
 
-    # Another example
-
-    *fred = *barney; # fred is aliased to barney
-    @barney = (1, 2, 4);
-    # @fred;
-    print "@fred";  # should print "1, 2, 4"
+=item * (Globs)
 
-    # perl4 prints: 1 2 4
-    # perl5 prints: In string, @fred now must be written as \@fred
+Assigning C<undef> to a glob has no effect in Perl 5.   In Perl 4
+it undefines the associated scalar (but may have other side effects
+including SEGVs).
 
 =item * (Scalar String)
 
@@ -925,6 +948,10 @@ Probably a bug.
 
 Perl4-to-Perl5 traps involving precedence order.
 
+Perl 4 has almost the same precedence rules as Perl 5 for the operators
+that they both have.  Perl 4 however, seems to have had some
+inconsistencies that made the behavior differ from what was documented.
+
 =over 5
 
 =item * Precedence
@@ -1000,13 +1027,34 @@ treats C<$::> as main C<package>
 
 =item * Precedence
 
-concatenation precedence over filetest operator?
+perl4 had buggy precedence for the file test operators vis-a-vis
+the assignment operators.  Thus, although the precedence table
+for perl4 leads one to believe C<-e $foo .= "q"> should parse as
+C<((-e $foo) .= "q")>, it actually parses as C<(-e ($foo .= "q"))>.
+In perl5, the precedence is as documented.
 
     -e $foo .= "q"
 
     # perl4 prints: no output
     # perl5 prints: Can't modify -e in concatenation
 
+=item * Precedence
+
+In perl4, keys(), each() and values() were special high-precedence operators
+that operated on a single hash, but in perl5, they are regular named unary
+operators.  As documented, named unary operators have lower precedence
+than the arithmetic and concatenation operators C<+ - .>, but the perl4
+variants of these operators actually bind tighter than C<+ - .>.
+Thus, for:
+
+    %foo = 1..10;
+    print keys %foo - 1
+
+    # perl4 prints: 4
+    # perl5 prints: Type of arg 1 to keys must be hash (not subtraction)
+
+The perl4 behavior was probably more useful, if less consistent.
+
 =back
 
 =head2 General Regular Expression Traps using s///, etc.
@@ -1018,7 +1066,7 @@ All types of RE traps.
 =item * Regular Expression
 
 C<s'$lhs'$rhs'> now does no interpolation on either side.  It used to
-interpolate C<$lhs> but not C<$rhs>.  (And still does not match a literal
+interpolate $lhs but not $rhs.  (And still does not match a literal
 '$' in string)
 
     $a=1;$b=2;
@@ -1057,7 +1105,7 @@ the very first time in any such closure.  For instance, if you say
     }
 
 build_match() will always return a sub which matches the contents of
-C<$left> and C<$right> as they were the I<first> time that build_match()
+$left and $right as they were the I<first> time that build_match()
 was called, not as they are in the current call.
 
 This is probably a bug, and may change in future versions of Perl.
@@ -1140,26 +1188,6 @@ repeatedly, like C</x/> or C<m!x!>.
     # perl5 prints: perl5
 
 
-=item * Regular Expression
-
-Under perl4 and upto version 5.003, a failed C<m//g> match used to
-reset the internal iterator, so that subsequent C<m//g> match attempts
-began from the beginning of the string.  In perl version 5.004 and later,
-failed C<m//g> matches do not reset the iterator position (which can be
-found using the C<pos()> function--see L<perlfunc/pos>).
-
-    $test = "foop";
-    for (1..3) {
-        print $1 while ($test =~ /(o)/g);
-        # pos $test = 0;     # to get old behavior
-    }
-
-    # perl4     prints: oooooo
-    # perl5.004 prints: oo
-
-You may always reset the iterator yourself as shown in the commented line
-to get the old behavior.
-
 =back
 
 =head2 Subroutine, Signal, Sorting Traps
@@ -1239,7 +1267,7 @@ Since version 5.002, Perl uses sigaction() under SysV.
 
 =item * (SysV)
 
-Under SysV OSes, C<seek()> on a file opened to append C<E<gt>E<gt>> now does
+Under SysV OSes, C<seek()> on a file opened to append C<<< >> >>> now does
 the right thing w.r.t. the fopen() manpage. e.g., - When a file is opened
 for append,  it  is  impossible to overwrite information already in
 the file.
@@ -1274,7 +1302,8 @@ within certain expressions, statements, contexts, or whatever.
     print "To: someone@somewhere.com\n";
 
     # perl4 prints: To:someone@somewhere.com
-    # perl5 errors : In string, @somewhere now must be written as \@somewhere
+    # perl < 5.6.1, error : In string, @somewhere now must be written as \@somewhere
+    # perl >= 5.6.1, warning : Possible unintended interpolation of @somewhere in string
 
 =item * Interpolation
 
@@ -1309,7 +1338,7 @@ Note that you can C<use strict;> to ward off such trappiness under perl5.
 =item * Interpolation
 
 The construct "this is $$x" used to interpolate the pid at that
-point, but now apparently tries to dereference C<$x>.  C<$$> by itself still
+point, but now apparently tries to dereference $x.  C<$$> by itself still
 works fine, however.
 
     print "this is $$x\n";
@@ -1451,9 +1480,7 @@ Everything else.
 
 =over 5
 
-=item * Unclassified
-
-C<require>/C<do> trap using returned value
+=item * C<require>/C<do> trap using returned value
 
 If the file doit.pl has:
 
@@ -1474,6 +1501,14 @@ Running doit.pl gives the following:
 
 Same behavior if you replace C<do> with C<require>.
 
+=item * C<split> on empty string with LIMIT specified
+
+       $string = '';
+    @list = split(/foo/, $string, 2)
+
+Perl4 returns a one element list containing the empty string but Perl5
+returns an empty list.
+
 =back
 
 As always, if any of these are ever officially declared as bugs,