Re: [PATCH lots of pod/] s/chop/chomp/g

       Message-Id: <20010203224638.E10493@blackrider.aocn.com>

p4raw-id: //depot/perl@8689

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index a62d8d1..c142367 100644 (file)
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -3567,8 +3567,7 @@ bad switch on your behalf.)
 
 (W newline) A file operation was attempted on a filename, and that
 operation failed, PROBABLY because the filename contained a newline,
-PROBABLY because you forgot to chop() or chomp() it off.  See
-L<perlfunc/chomp>.
+PROBABLY because you forgot to chomp() it off.  See L<perlfunc/chomp>.
 
 =item Unsupported directory function "%s" called
 

diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod
index d806ed6..1df3b6a 100644 (file)
--- a/pod/perlfaq8.pod
+++ b/pod/perlfaq8.pod
@@ -321,7 +321,7 @@ go bump in the night, finally came up with this:
        # been opened on a pipe...
        system("/bin/stty $stty");
        $_ = <MODEM_IN>;
-       chop;
+       chomp;
        if ( !m/^Connected/ ) {
            print STDERR "$0: cu printed `$_' instead of `Connected'\n";
        }

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index ca14939..c75818e 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -301,7 +301,7 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 Example:
 
     while (<>) {
-       chop;
+       chomp;
        next unless -f $_;      # ignore specials
        #...
     }
@@ -630,23 +630,11 @@ characters removed is returned.
 =item chop
 
 Chops off the last character of a string and returns the character
-chopped.  It's used primarily to remove the newline from the end of an
-input record, but is much more efficient than C<s/\n//> because it neither
+chopped.  It is much more efficient than C<s/.$//s> because it neither
 scans nor copies the string.  If VARIABLE is omitted, chops C<$_>.
-Example:
-
-    while (<>) {
-       chop;   # avoid \n on last field
-       @array = split(/:/);
-       #...
-    }
-
 If VARIABLE is a hash, it chops the hash's values, but not its keys.
 
-You can actually chop anything that's an lvalue, including an assignment:
-
-    chop($cwd = `pwd`);
-    chop($answer = <STDIN>);
+You can actually chop anything that's an lvalue, including an assignment.
 
 If you chop a list, each element is chopped.  Only the value of the
 last C<chop> is returned.
@@ -4443,13 +4431,12 @@ Example:
 
     open(PASSWD, '/etc/passwd');
     while (<PASSWD>) {
-       ($login, $passwd, $uid, $gid,
+        chomp;
+        ($login, $passwd, $uid, $gid,
          $gcos, $home, $shell) = split(/:/);
        #...
     }
 
-(Note that $shell above will still have a newline on it.  See L</chop>,
-L</chomp>, and L</join>.)
 
 =item sprintf FORMAT, LIST
 

diff --git a/pod/perlop.pod b/pod/perlop.pod
index ebe52c5..464ba99 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -1746,7 +1746,7 @@ is roughly equivalent to:
 
     open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
     while (<FOO>) {
-       chop;
+       chomp;
        chmod 0644, $_;
     }
 

diff --git a/pod/perlport.pod b/pod/perlport.pod
index 1078e58..08a1704 100644 (file)
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -94,6 +94,26 @@ from) C<\015\012>, depending on whether you're reading or writing.
 Unix does the same thing on ttys in canonical mode.  C<\015\012>
 is commonly referred to as CRLF.
 
+A common cause of unportable programs is the misuse of chop() to trim
+newlines:
+
+    # XXX UNPORTABLE!
+    while(<FILE>) {
+        chop;
+        @array = split(/:/);
+        #...
+    }
+
+You can get away with this on Unix and MacOS (they have a single
+character end-of-line), but the same program will break under DOSish
+perls because you're only chop()ing half the end-of-line.  Instead,
+chomp() should be used to trim newlines.  The Dunce::Files module can
+help audit your code for misuses of chop().
+
+When dealing with binary files (or text files in binary mode) be sure
+to explicitly set $/ to the appropriate value for your file format
+before using chomp().
+
 Because of the "text" mode translation, DOSish perls have limitations
 in using C<seek> and C<tell> on a file accessed in "text" mode.
 Stick to C<seek>-ing to locations you got from C<tell> (and no

diff --git a/pod/perlutil.pod b/pod/perlutil.pod
index 7b56a17..be7a345 100644 (file)
--- a/pod/perlutil.pod
+++ b/pod/perlutil.pod
@@ -97,7 +97,7 @@ Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run
 on C<s/foo/bar> will produce a Perl program based around this:
 
     while (<>) {
-        chop;
+        chomp;
         s/foo/bar/g;
         print if $printit;
     }