@node perltrap, perlstyle, perlsec, Top
@unnumbered Perl traps for the unwary


@unnumberedsec NAME

perltrap - Perl traps for the unwary

@unnumberedsec DESCRIPTION

The biggest trap of all is forgetting to use the -w switch; see
@xref{perlrun,Perlrun},.  The second biggest trap is not making your entire program
runnable under @code{use strict}.

@unnumberedsubsec Awk Traps

Accustomed @strong{awk} users should take special note of the following:

@itemize @bullet
@item 
The English module, loaded via

@example
use English;
@end example

allows you to refer to special variables (like $RS) as 
though they were in @strong{awk}; see @xref{perlvar,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 @code{if}s and @code{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 
Associative array 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
yourself to an array.  And the split() operator has different
arguments.

@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 @xref{perlvar,Perlvar},.

@item 
$<@emph{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 $, and $\.  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 @strong{awk} is
basically incompatible with C.)

@item 
The concatenation operator is ".", not the null string.  (Using the
null string would render @code{/pat/ /pat/} unparsable, since the third slash
would be interpreted as a division operator--the tokener is in fact
slightly context sensitive for operators like "/", "?", and ">".
And in fact, "." itself can be the beginning of a number.)

@item 
The next, exit, and continue keywords work differently.

@item 
The following variables work differently:

@example
Awk	Perl
ARGC	$#ARGV or scalar @@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	$;
@end example

@item 
You cannot set $RS to a pattern, only a string.

@item 
When in doubt, run the @strong{awk} construct through a2p and see what it
gives you.

@end itemize
@unnumberedsubsec C Traps

Cerebral C programmers should take note of the following:

@itemize @bullet
@item 
Curly brackets are required on @code{if}@'s and @code{while}@'s.

@item 
You must use @code{elsif} rather than @code{else if}.

@item 
The @code{break} and continue keywords from C become in 
Perl last and next, respectively.
Unlike in C, these do @emph{NOT} work within a @code{do @{ @} while} construct.

@item 
There@'s no switch statement.  (But it@'s easy to build one on the fly.)

@item 
Variables begin with "$" or "@@" in Perl.

@item 
@code{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.

@item 
Comments begin with "#", not "/*".

@item 
You can@'t take the address of anything, although a similar operator
in Perl 5 is the backslash, which creates a reference.

@item 
@code{ARGV} must be capitalized.  @code{$ARGV[0]} is C@'s @code{argv[1]}, and @code{argv[0]}
ends up in $0.

@item 
System calls such as link(), unlink(), rename(), etc. return nonzero for
success, not 0.

@item 
Signal handlers deal with signal names, not numbers.  Use @code{kill -l}
to find their names on your system.

@end itemize
@unnumberedsubsec Sed Traps

Seasoned @strong{sed} programmers should take note of the following:

@itemize @bullet
@item 
Backreferences in substitutions use "$" rather than "\".

@item 
The pattern matching metacharacters "(", ")", and "|" do not have backslashes
in front.

@item 
The range operator is @code{...}, rather than comma.

@end itemize
@unnumberedsubsec Shell Traps

Sharp shell programmers should take note of the following:

@itemize @bullet
@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 @strong{csh}.

@item 
Shells (especially @strong{csh}) do several levels of substitution on each
command line.  Perl does substitution only in 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 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.

@end itemize
@unnumberedsubsec Perl Traps

Practicing Perl Programmers should take note of the following:

@itemize @bullet
@item 
Remember that many operations behave differently in a list
context than they do in a scalar one.  See @xref{perldata,Perldata}, for details.

@item 
Avoid barewords if you can, especially all lower-case ones.
You can@'t tell just by looking at it whether a bareword is 
a function or a string.  By using quotes on strings and 
parens on function calls, you won@'t ever get them confused.

@item 
You cannot discern from mere inspection which built-ins
are unary operators (like chop() and chdir()) 
and which are list operators (like print() and unlink()).
(User-defined subroutines can @strong{only} be list operators, never
unary ones.)  See @xref{perlop,Perlop},.

@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 only assigned to $_ if the
file read is the sole condition in a while loop:

@example
while (<FH>)      @{ @}
while ($_ = <FH>) @{ @}..
<FH>;  # data discarded!
@end example

@item 
Remember not to use "=" when you need "@code{=~}";
these two constructs are quite different:

@example
$x =  /foo/;
$x =~ /foo/;
@end example

@item 
The @code{do @{@}} construct isn@'t a real loop that you can use 
loop control on.

@item 
Use @code{my()} for local variables whenever you can get away with 
it (but see @xref{perlform,Perlform}, for where you can@'t).  
Using @code{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.

@end itemize
@unnumberedsubsec Perl4 to Perl5  Traps

Practicing Perl4 Programmers should take note of the following 
Perl4-to-Perl5 specific traps.

They@'re crudely ordered according to the following list:

@table @asis
@item Discontinuance, Deprecation, and BugFix traps
Anything that@'s been fixed as a perl4 bug, removed as a perl4 feature
or deprecated as a perl4 feature with the intent to encourage usage of
some other perl5 feature.

@item Parsing Traps
Traps that appear to stem from the new parser.

@item Numerical Traps
Traps having to do with numerical or mathematical operators.

@item General data type traps
Traps involving perl standard data types.

@item Context Traps - scalar, list contexts
Traps related to context within lists, scalar statements/declarations.

@item Precedence Traps
Traps related to the precedence of parsing, evaluation, and execution of
code.

@item General Regular Expression Traps using s///, etc.
Traps related to the use of pattern matching.

@item Subroutine, Signal, Sorting Traps
Traps related to the use of signals and signal handlers, general subroutines,
and sorting, along with sorting subroutines.

@item OS Traps
OS-specific traps.

@item DBM Traps
Traps specific to the use of @code{dbmopen()}, and specific dbm implementations.

@item Unclassified Traps
Everything else.

@end table
If you find an example of a conversion trap that is not listed here,
please submit it to Bill Middleton @file{wjm@@best.com} for inclusion.
Also note that at least some of these can be caught with -w.

@unnumberedsubsec Discontinuance, Deprecation, and BugFix traps

Anything that has been discontinued, deprecated, or fixed as
a bug from perl4.  

@itemize @bullet
@item Discontinuance 

Symbols starting with "_" are no longer forced into package main, except
for $_ itself (and @code{@@_}, etc.).

@example
package test;
$_legacy = 1;
@end example

@example
package main;
print "\$_legacy is ",$_legacy,"\n";
 
# perl4 prints: $_legacy is 1
# perl5 prints: $_legacy is
@end example

@item Deprecation 

Double-colon is now a valid package separator in a variable name.  Thus these
behave differently in perl4 vs. perl5, since the packages don@'t exist.

@example
$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
@end example

Given that @code{::} is now the preferred package delimiter, it is debatable
whether this should be classed as a bug or not.
(The older package delimiter, @' ,is used here)

@example
$x = 10 ;
print "x=$@{@'x@}\n" ;
 
# perl4 prints: x=10
# perl5 prints: Can@'t find string terminator "@'" anywhere before EOF
@end example

Also see precedence traps, for parsing $:. 

@item BugFix

The second and third arguments of @code{splice()} are now evaluated in scalar
context (as the Camel says) rather than list context.

@example
sub sub1@{return(0,2) @}          # return a 2-elem array
sub sub2@{ return(1,2,3)@}        # return a 3-elem array
@@a1 = ("a","b","c","d","e"); 
@@a2 = splice(@@a1,&sub1,&sub2);
print join(@' @',@@a2),"\n";
 
# perl4 prints: a b
# perl5 prints: c d e 
@end example

@item Discontinuance 

You can@'t do a goto into a block that is optimized away.  Darn.

@example
goto marker1;
@end example

@example
for(1)@{         
marker1:
    print "Here I is!\n";
@} 
 
# perl4 prints: Here I is!
# perl5 dumps core (SEGV)
@end example

@item Discontinuance 

It is no longer syntactically legal to use whitespace as the name
of a variable, or as a delimiter for any kind of quote construct.
Double darn. 

@example
$a = ("foo bar");
$b = q baz ;
print "a is $a, b is $b\n";
 
# perl4 prints: a is foo bar, b is baz
# perl5 errors: Bare word found where operator expected
@end example

@item Discontinuance

The archaic while/if BLOCK BLOCK syntax is no longer supported.

@example
if @{ 1 @} @{
    print "True!";
@}
else @{
    print "False!";
@}
 
# perl4 prints: True!
# perl5 errors: syntax error at test.pl line 1, near "if @{"
@end example

@item BugFix

The @code{**} operator now binds more tightly than unary minus.
It was documented to work this way before, but didn@'t.

@example
print -4**2,"\n";
 
# perl4 prints: 16
# perl5 prints: -16
@end example

@item Discontinuance 

The meaning of @code{foreach@{@}} has changed slightly when it is iterating over a
list which is not an array.  This used to assign the list to a
temporary array, but no longer does so (for efficiency).  This means
that you@'ll now be iterating over the actual values, not over copies of
the values.  Modifications to the loop variable can change the original
values.

@example
@@list = (@'ab@',@'abc@',@'bcd@',@'def@');
foreach $var (grep(/ab/,@@list))@{
    $var = 1;
@}
print (join(@':@',@@list));
 
# perl4 prints: ab:abc:bcd:def
# perl5 prints: 1:1:bcd:def
@end example

To retain Perl4 semantics you need to assign your list
explicitly to a temporary array and then iterate over that.  For 
example, you might need to change

@example
foreach $var (grep(/ab/,@@list))@{
@end example

to

@example
foreach $var (@@tmp = grep(/ab/,@@list))@{
@end example

Otherwise changing $var will clobber the values of @@list.  (This most often
happens when you use $_ for the loop variable, and call subroutines in
the loop that don@'t properly localize $_.)

@item Discontinuance

split with no arguments now behaves like @code{split @' @'} (which doesn@'t
return an initial null field if $_ starts with whitespace), it used to
behave like @code{split /\s+/} (which does).

@example
$_ = @' hi mom@';
print join(@':@', split);
@end example

@example
# perl4 prints: :hi:mom
# perl5 prints: hi:mom
@end example

@item Deprecation

Some error messages will be different.

@item Discontinuance 

Some bugs may have been inadvertently removed.  :-)

@end itemize
@unnumberedsubsec Parsing Traps

Perl4-to-Perl5 traps from having to do with parsing.

@itemize @bullet
@item Parsing

Note the space between . and =

@example
$string . = "more string";
print $string;
 
# perl4 prints: more string
# perl5 prints: syntax error at - line 1, near ". ="
@end example

@item Parsing

Better parsing in perl 5

@example
sub foo @{@}
&foo
print("hello, world\n");
 
# perl4 prints: hello, world
# perl5 prints: syntax error
@end example

@item Parsing

"if it looks like a function, it is a function" rule.

@example
print
  ($foo == 1) ? "is one\n" : "is zero\n";
 
  # perl4 prints: is zero
  # perl5 warns: "Useless use of a constant in void context" if using -w
@end example

@end itemize
@unnumberedsubsec Numerical Traps

Perl4-to-Perl5 traps having to do with numerical operators,
operands, or output from same.

@itemize @bullet
@item Numerical

Formatted output and significant digits

@example
print 7.373504 - 0, "\n";
printf "%20.18f\n", 7.373504 - 0; 
 
# Perl4 prints:
7.375039999999996141
7.37503999999999614
 
# Perl5 prints:
7.373504
7.37503999999999614
@end example

@item Numerical

This specific item has been deleted.  It demonstrated how the autoincrement
operator would not catch when a number went over the signed int limit.  Fixed
in 5.003_04.  But always be wary when using large ints.  If in doubt:

@example
use Math::BigInt;
@end example

@item Numerical  

Assignment of return values from numeric equality tests
does not work in perl5 when the test evaluates to false (0).
Logical tests now return an null, instead of 0
 
    $p = ($test == 1);
    print $p,"\n";
  
    # perl4 prints: 0
    # perl5 prints:

Also see the @samp{General Regular Expression Traps} in this node tests for another example 
of this new feature...

@end itemize
@unnumberedsubsec General data type traps

Perl4-to-Perl5 traps involving most data-types, and their usage
within certain expressions and/or context.

@itemize @bullet
@item (Arrays)

Negative array subscripts now count from the end of the array.

@example
@@a = (1, 2, 3, 4, 5);
print "The third element of the array is $a[3] also expressed as $a[-2] \n";
  
# perl4 prints: The third element of the array is 4 also expressed as
# perl5 prints: The third element of the array is 4 also expressed as 4
@end example

@item (Arrays)

Setting @code{$#array} lower now discards array elements, and makes them
impossible to recover.

@example
@@a = (a,b,c,d,e); 
print "Before: ",join(@'@',@@a);
$#a =1; 
print ", After: ",join(@'@',@@a);
$#a =3;
print ", Recovered: ",join(@'@',@@a),"\n";
  
# perl4 prints: Before: abcde, After: ab, Recovered: abcd
# perl5 prints: Before: abcde, After: ab, Recovered: ab
@end example

@item (Hashes)

Hashes get defined before use

@example
local($s,@@a,%h); 
die "scalar \$s defined" if defined($s);
die "array \@@a defined" if defined(@@a);
die "hash \%h defined" if defined(%h);
 
# perl4 prints:
# perl5 dies: hash %h defined
@end example

@item (Globs)

glob assignment from variable to variable will fail if the assigned
variable is localized subsequent to the assignment

@example
@@a = ("This is Perl 4");
*b = *a;
local(@@a);
print @@b,"\n";
 
# 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"
 
# perl4 prints: 1 2 4
# perl5 prints: Literal @@fred now requires backslash 
@end example

@item (Scalar String)

Changes in unary negation (of strings)
This change effects both the return value and what it
does to auto(magic)increment.

@example
$x = "aaa";
print ++$x," : ";
print -$x," : ";
print ++$x,"\n";
 
# perl4 prints: aab : -0 : 1
# perl5 prints: aab : -aab : aac
@end example

@item (Constants)

perl 4 lets you modify constants:

@example
$foo = "x";
&mod($foo);
for ($x = 0; $x < 3; $x++) @{
    &mod("a");
@}
sub mod @{
    print "before: $_[0]";
    $_[0] = "m";
    print "  after: $_[0]\n";
@}
 
# perl4:
# before: x  after: m
# before: a  after: m
# before: m  after: m
# before: m  after: m
 
# Perl5:
# before: x  after: m
# Modification of a read-only value attempted at foo.pl line 12.
# before: a
@end example

@item (Scalars)

The behavior is slightly different for:

@example
print "$x", defined $x
  
# perl 4: 1
# perl 5: <no output, $x is not called into existence>
@end example

@item (Variable Suicide)

Variable suicide behavior is more consistent under Perl 5.
Perl5 exhibits the same behavior for associative arrays and scalars,
that perl4 exhibits only for scalars.

@example
$aGlobal@{ "aKey" @} = "global value";
print "MAIN:", $aGlobal@{"aKey"@}, "\n";
$GlobalLevel = 0;
&test( *aGlobal );
@end example

@example
sub test @{
    local( *theArgument ) = @@_;
    local( %aNewLocal ); # perl 4 != 5.001l,m
    $aNewLocal@{"aKey"@} = "this should never appear";  
    print "SUB: ", $theArgument@{"aKey"@}, "\n";
    $aNewLocal@{"aKey"@} = "level $GlobalLevel";   # what should print
    $GlobalLevel++;
    if( $GlobalLevel<4 ) @{
        &test( *aNewLocal );
    @}
@}
 
# Perl4:
# MAIN:global value
# SUB: global value
# SUB: level 0
# SUB: level 1
# SUB: level 2
 
# Perl5:
# MAIN:global value
# SUB: global value
# SUB: this should never appear
# SUB: this should never appear
# SUB: this should never appear
@end example

@end itemize
@unnumberedsubsec Context Traps - scalar, list contexts

@itemize @bullet
@item (list context)

The elements of argument lists for formats are now evaluated in list
context.  This means you can interpolate list values now.

@example
@@fmt = ("foo","bar","baz");
format STDOUT=
@@<<<<< @@||||| @@>>>>>
@@fmt;
.
write;  
 
# perl4 errors:  Please use commas to separate fields in file
# perl5 prints: foo     bar      baz
@end example

@item (scalar context)

The @code{caller()} function now returns a false value in a scalar context 
if there is no caller.  This lets library files determine if they@'re 
being required.

@example
caller() ? (print "You rang?\n") : (print "Got a 0\n");
  
# perl4 errors: There is no caller
# perl5 prints: Got a 0
@end example

@item (scalar context)

The comma operator in a scalar context is now guaranteed to give a
scalar context to its arguments.

@example
@@y= (@'a@',@'b@',@'c@');
$x = (1, 2, @@y);
print "x = $x\n";
 
# Perl4 prints:  x = c   # Thinks list context interpolates list
# Perl5 prints:  x = 3   # Knows scalar uses length of list
@end example

@item (list, builtin)

@code{sprintf()} funkiness (array argument converted to scalar array count)
This test could be added to t/op/sprintf.t

@example
@@z = (@'%s%s@', @'foo@', @'bar@');
$x = sprintf(@@z);
if ($x eq @'foobar@') @{print "ok 2\n";@} else @{print "not ok 2 @'$x@'\n";@}
 
# perl4 prints: ok 2
# perl5 prints: not ok 2
@end example

@code{printf()} works fine, though:

@example
printf STDOUT (@@z);
print "\n"; 
 
# perl4 prints: foobar
# perl5 prints: foobar
@end example

Probably a bug.

@end itemize
@unnumberedsubsec Precedence Traps

Perl4-to-Perl5 traps involving precedence order.

@itemize @bullet
@item Precedence

LHS vs. RHS when both sides are getting an op.

@example
@@arr = ( @'left@', @'right@' );
$a@{shift @@arr@} = shift @@arr;
print join( @' @', keys %a );
@end example

@example
# perl4 prints: left
# perl5 prints: right
@end example

@item Precedence

These are now semantic errors because of precedence:

@example
@@list = (1,2,3,4,5);
%map = ("a",1,"b",2,"c",3,"d",4);
$n = shift @@list + 2;   # first item in list plus 2
print "n is $n, ";
$m = keys %map + 2;     # number of items in hash plus 2
print "m is $m\n";
 
# perl4 prints: n is 3, m is 6
# perl5 errors and fails to compile
@end example

@item Precedence

The precedence of assignment operators is now the same as the precedence
of assignment.  Perl 4 mistakenly gave them the precedence of the associated
operator.  So you now must parenthesize them in expressions like

@example
/foo/ ? ($a += 2) : ($a -= 2);

Otherwise
@end example

@example
/foo/ ? $a += 2 : $a -= 2
@end example

would be erroneously parsed as

@example
(/foo/ ? $a += 2 : $a) -= 2;
@end example

On the other hand,

@example
$a += /foo/ ? 1 : 2; 
@end example

now works as a C programmer would expect.

@item Precedence
@example
open FOO || die;
@end example


is now incorrect.  You need parens around the filehandle.
Otherwise, perl5 leaves the statement as it@'s default precedence:

@example
open(FOO || die);
 
# perl4 opens or dies
# perl5 errors: Precedence problem: open FOO should be open(FOO)
@end example

@item Precedence

perl4 gives the special variable, $: precedence, where perl5
treats @code{$::} as main package

@example
$a = "x"; print "$::a";
 
# perl 4 prints: -:a
# perl 5 prints: x
@end example

@item Precedence

concatenation precedence over filetest operator?  

@example
-e $foo .= "q" 
  
# perl4 prints: no output
# perl5 prints: Can@'t modify -e in concatenation
@end example

@item Precedence

Assignment to value takes precedence over assignment to key in
perl5 when using the shift operator on both sides.

@example
@@arr = ( @'left@', @'right@' );
$a@{shift @@arr@} = shift @@arr;
print join( @' @', keys %a );
@end example

@example
# perl4 prints: left
# perl5 prints: right
@end example

@end itemize
@unnumberedsubsec General Regular Expression Traps using s///, etc.

All types of RE traps.

@itemize @bullet
@item Regular Expression

@code{s@'$lhs@'$rhs@'} now does no interpolation on either side.  It used to
interpolate @code{$lhs} but not @code{$rhs}.  (And still does not match a literal 
@'$@' in string)

@example
$a=1;$b=2;
$string = @'1 2 $a $b@';
$string =~ s@'$a@'$b@';
print $string,"\n";
 
# perl4 prints: $b 2 $a $b
# perl5 prints: 1 2 $a $b
@end example

@item Regular Expression

@code{m//g} now attaches its state to the searched string rather than the
regular expression.  (Once the scope of a block is left for the sub, the
state of the searched string is lost)

@example
$_ = "ababab";
while(m/ab/g)@{
    &doit("blah");
@}
sub doit@{local($_) = shift; print "Got $_ "@}
 
# perl4 prints: blah blah blah
# perl5 prints: infinite loop blah...
@end example

@item Regular Expression

If no parentheses are used in a match, Perl4 sets $+ to
the whole match, just like $&. Perl5 does not.

@example
"abcdef" =~ /b.*e/;
print "\$+ = $+\n";
 
# perl4 prints: bcde
# perl5 prints:
@end example

@item Regular Expression

substitution now returns the null string if it fails

@example
$string = "test";
$value = ($string =~ s/foo//);
print $value, "\n";
 
# perl4 prints: 0
# perl5 prints:
@end example

Also see @samp{Numerical Traps} in this node for another example of this new feature.

@item Regular Expression

@code{s@`lhs@`rhs@`} (using backticks) is now a normal substitution, with no 
backtick expansion

@example
$string = "";
$string =~ s@`^@`hostname@`;
print $string, "\n";
 
# perl4 prints: <the local hostname>
# perl5 prints: hostname
@end example

@item Regular Expression

Stricter parsing of variables used in regular expressions

@example
s/^([^$grpc]*$grpc[$opt$plus$rep]?)//o;
 
# perl4: compiles w/o error
# perl5: with Scalar found where operator expected ..., near "$opt$plus"
@end example

an added component of this example, apparently from the same script, is
the actual value of the s@'d string after the substitution.
@code{[$opt]} is a character class in perl4 and an array subscript in perl5

@example
$grpc = @'a@'; 
$opt  = @'r@';
$_ = @'bar@';
s/^([^$grpc]*$grpc[$opt]?)/foo/;
print ;
 
# perl4 prints: foo
# perl5 prints: foobar
@end example

@item Regular Expression

Under perl5, @code{m?x?} matches only once, like @code{?x?}. Under perl4, it matched
repeatedly, like @code{/x/} or @code{m!x!}.

@example
$test = "once";
sub match @{ $test =~ m?once?; @}
&match();
if( &match() ) @{
    # m?x? matches more then once
    print "perl4\n";
@} else @{ 
    # m?x? matches only once
    print "perl5\n"; 
@}
 
# perl4 prints: perl4
# perl5 prints: perl5
@end example

@end itemize
@unnumberedsubsec Subroutine, Signal, Sorting Traps

The general group of Perl4-to-Perl5 traps having to do with
Signals, Sorting, and their related subroutines, as well as
general subroutine traps.  Includes some OS-Specific traps.

@itemize @bullet
@item (Signals)

Barewords that used to look like strings to Perl will now look like subroutine
calls if a subroutine by that name is defined before the compiler sees them.

@example
sub SeeYa @{ warn"Hasta la vista, baby!" @}
$SIG@{@'TERM@'@} = SeeYa;
print "SIGTERM is now $SIG@{@'TERM@'@}\n";
 
# perl4 prints: SIGTERM is main@'SeeYa
# perl5 prints: SIGTERM is now main::1
@end example

Use -w to catch this one

@item (Sort Subroutine)

reverse is no longer allowed as the name of a sort subroutine.

@example
sub reverse@{ print "yup "; $a <=> $b @}
print sort reverse a,b,c;  
 
# perl4 prints: yup yup yup yup abc
# perl5 prints: abc 
@end example

@item warn() won@'t let you specify a filehandle.

Although it _always_ printed to STDERR, warn() would let you specify a
filehandle in perl4.  With perl5 it does not.

@example
warn STDERR "Foo!";
@end example

@example
# perl4 prints: Foo!
# perl5 prints: String found where operator expected 
@end example

@end itemize
@unnumberedsubsec OS Traps

@itemize @bullet
@item (SysV)

Under HPUX, and some other SysV OS@'s, one had to reset any signal handler, 
within  the signal handler function, each time a signal was handled with 
perl4.  With perl5, the reset is now done correctly.  Any code relying 
on the handler _not_ being reset will have to be reworked.

5.002 and beyond uses sigaction() under SysV

@example
sub gotit @{
    print "Got @@_... "; 
@}  
$SIG@{@'INT@'@} = @'gotit@';
   
$| = 1;
$pid = fork;
if ($pid) @{
    kill(@'INT@', $pid);
    sleep(1);
    kill(@'INT@', $pid);
@} else @{ 
    while (1) @{sleep(10);@}
@} 
 
# perl4 (HPUX) prints: Got INT...
# perl5 (HPUX) prints: Got INT... Got INT...
@end example

@item (SysV)

Under SysV OS@'s, seek() on a file opened to append @code{>>} now does 
the right thing w.r.t. the fopen() man page. e.g. - When a file is opened
for append,  it  is  impossible to overwrite information already in
the file.

@example
open(TEST,">>seek.test");
$start = tell TEST ;  
foreach(1 .. 9)@{
    print TEST "$_ ";
@}
$end = tell TEST ;
seek(TEST,$start,0);
print TEST "18 characters here";
 
# perl4 (solaris) seek.test has: 18 characters here
# perl5 (solaris) seek.test has: 1 2 3 4 5 6 7 8 9 18 characters here
@end example

@end itemize
@unnumberedsubsec Interpolation Traps

Perl4-to-Perl5 traps having to do with how things get interpolated
within certain expressions, statements, contexts, or whatever.

@itemize @bullet
@item Interpolation

@@ now always interpolates an array in double-quotish strings.

@example
print "To: someone@@somewhere.com\n"; 
 
# perl4 prints: To:someone@@somewhere.com
# perl5 errors : Literal @@somewhere now requires backslash
@end example

@item Interpolation

Double-quoted strings may no longer end with an unescaped $ or @@.

@example
$foo = "foo$";
$bar = "bar@@";
print "foo is $foo, bar is $bar\n";
 
# perl4 prints: foo is foo$, bar is bar@@
# perl5 errors: Final $ should be \$ or $name
@end example

Note: perl5 DOES NOT error on the terminating @@ in $bar

@item Interpolation

Perl now sometimes evaluates arbitrary expressions inside braces that occur
within double quotes (usually when the opening brace is preceded by @code{$}
or @code{@@}).

@example
@@www = "buz";
$foo = "foo";
$bar = "bar";
sub foo @{ return "bar" @};
print "|@@@{w.w.w@}|$@{main@'foo@}|";
@end example

@example
# perl4 prints: |@@@{w.w.w@}|foo|
# perl5 prints: |buz|bar|
@end example

Note that you can @code{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 @code{$x}.  $$ by itself still
works fine, however.

@example
print "this is $$x\n";
@end example

@example
# perl4 prints: this is XXXx   (XXX is the current pid)
# perl5 prints: this is
@end example

@item Interpolation

Creation of hashes on the fly with @code{eval "EXPR"} now requires either both 
@code{$}@'s to be protected in the specification of the hash name, or both curlies 
to be protected.  If both curlies are protected, the result will be compatible
with perl4 and perl5.  This is a very common practice, and should be changed
to use the block form of @code{eval@{@}}  if possible.

@example
$hashname = "foobar";
$key = "baz";
$value = 1234;
eval "\$$hashname@{@'$key@'@} = q|$value|";
(defined($foobar@{@'baz@'@})) ?  (print "Yup") : (print "Nope");
@end example

@example
# perl4 prints: Yup
# perl5 prints: Nope
@end example

Changing

@example
eval "\$$hashname@{@'$key@'@} = q|$value|";
@end example

to

@example
eval "\$\$hashname@{@'$key@'@} = q|$value|";
@end example

causes the following result:

@example
# perl4 prints: Nope
# perl5 prints: Yup
@end example

or, changing to

@example
eval "\$$hashname\@{@'$key@'\@} = q|$value|";
@end example

causes the following result:

@example
# perl4 prints: Yup
# perl5 prints: Yup
# and is compatible for both versions
@end example

@item Interpolation

perl4 programs which unconsciously rely on the bugs in earlier perl versions.

@example
perl -e @'$bar=q/not/; print "This is $foo@{$bar@} perl5"@'
 
# perl4 prints: This is not perl5
# perl5 prints: This is perl5
@end example

@item Interpolation

You also have to be careful about array references.  

@example
print "$foo@{"
@end example

@example
perl 4 prints: @{
perl 5 prints: syntax error
@end example

@item Interpolation

Similarly, watch out for:

@example
$foo = "array";
print "\$$foo@{bar@}\n";
  
# perl4 prints: $array@{bar@}
# perl5 prints: $
@end example

Perl 5 is looking for @code{$array@{bar@}} which doesn@'t exist, but perl 4 is
happy just to expand $foo to "array" by itself.  Watch out for this
especially in eval@'s.

@item Interpolation

@code{qq()} string passed to eval

@example
eval qq(
    foreach \$y (keys %\$x\) @{
        \$count++;
    @}
);
  
# perl4 runs this ok
# perl5 prints: Can@'t find string terminator ")" 
@end example

@end itemize
@unnumberedsubsec DBM Traps

General DBM traps.

@itemize @bullet
@item DBM

Existing dbm databases created under perl4 (or any other dbm/ndbm tool)
may cause the same script, run under perl5, to fail.  The build of perl5
must have been linked with the same dbm/ndbm as the default for @code{dbmopen()}
to function properly without tie@'ing to an extension dbm implementation.

@example
dbmopen (%dbm, "file", undef);
print "ok\n";
@end example

@example
# perl4 prints: ok
# perl5 prints: ok (IFF linked with -ldbm or -lndbm)
@end example

@item DBM

Existing dbm databases created under perl4 (or any other dbm/ndbm tool)
may cause the same script, run under perl5, to fail.  The error generated
when exceeding the limit on the key/value size will cause perl5 to exit
immediately.

@example
dbmopen(DB, "testdb",0600) || die "couldn@'t open db! $!";
$DB@{@'trap@'@} = "x" x 1024;  # value too large for most dbm/ndbm
print "YUP\n";
@end example

@example
# perl4 prints:
dbm store returned -1, errno 28, key "trap" at - line 3.
YUP
@end example

@example
# perl5 prints:
dbm store returned -1, errno 28, key "trap" at - line 3.
@end example

@end itemize
@unnumberedsubsec Unclassified Traps

Everything else.

@itemize @bullet
@item Unclassified

require/do trap using returned value

If the file doit.pl has:

@example
sub foo @{
    $rc = do "./do.pl";
    return 8;
@} 
print &foo, "\n";
@end example

And the do.pl file has the following single line:

@example
return 3;
@end example

Running doit.pl gives the following:

@example
# perl 4 prints: 3 (aborts the subroutine early)
# perl 5 prints: 8 
@end example

Same behavior if you replace do with require.

@end itemize
As always, if any of these are ever officially declared as bugs, 
they@'ll be fixed and removed.

