Bug in perlop man page (=~ return value)

[p5pRT]

Migrated from rt.perl.org#2280 (status was 'resolved')

Searchable as RT2280$

[p5pRT]

From kompas@ceti.pl

I have answered on pl.comp.lang.perl with one of my favorite one-liners (how to sort list of \name\ lines by names​: print sort { ( $a =~ />(.*)\</ )[0] cmp ( $b =~ />(.*)\</ )[0] } \<>; - not very efficient but fits in one line :-) )

then friend of mine pointed to me\, that perlop lies about =~'s return value​:

  Binary "=~" binds a scalar expression to a pattern match.   [...]   or transliterated instead of the default $_. The return   value indicates the success of the operation.   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Which is true only in scalar context - in list context it returns the same value as patter match operator itself (well\, I didn't check for operators others than m// but I hope perl is consistent at last here :-) ).

I hope someone will fix perlop manpage in next revision (althought it is very intuitive and I guess much people are using this not knowing it is actually "undocumented feature" :-) ).

Greetings

-- Piotr Piątkowski\, Kraków perl -le 's**02).4&9%4^[./4(%2^0%2\,^([#+%2&**y%& -;^[%"`-{ a%%s%%$_%ee'

[p5pRT]

From [Unknown Contact. See original ticket]

On Tue\, 7 Mar 2000\, Piotr Piatkowski wrote​:

I have answered on pl.comp.lang.perl with one of my favorite one-liners (how to sort list of \name\ lines by names​: print sort { ( $a =~ />(.*)\</ )[0] cmp ( $b =~ />(.*)\</ )[0] } \<>; - not very efficient but fits in one line :-) )

then friend of mine pointed to me\, that perlop lies about =~'s return value​:

  just because you don't understand perlop (or someone)\,   doesn't mean they are lying to you!

   Binary "=~" binds a scalar expression to a pattern match\.
   \[\.\.\.\]
   or transliterated instead of the default $\_\.  The return
   value indicates the success of the operation\.
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  Remember there is more that one way to indicate success\,   and the number of elements in the array returns also indicate   success

Which is true only in scalar context - in list context it returns the same value as patter match operator itself

the section on =~ is just part of what you should read if you are going to do matches\, read on to the section that starts​:

  m/PATTERN/cgimosx

  /PATTERN/cgimosx   Searches a string for a pattern match\, and in   scalar context returns true if it succeeds\, false   if it fails. .....

  If the `/g' option is not used\, `m//' in list con-   text returns a list consisting of the subexpres-   sions matched by the parentheses in the pattern\,   i.e.\, (`$1'\, `$2'\, `$3'...). (Note that here `$1'   etc. are also set\, and that this differs from Perl   4's behavior.) When there are no parentheses in   the pattern\, the return value is the list `(1)'   for success. With or without parentheses\, an   empty list is returned upon failure.

  Examples​:   ......

  if (($F1\, $F2\, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))

  This last example splits $foo into the first two   words and the remainder of the line\, and assigns   those three fields to $F1\, $F2\, and $Etc. The   conditional is true if any variables were   assigned\, i.e.\, if the pattern matched.

[p5pRT]

From @tamias

On Tue\, Mar 07\, 2000 at 09​:42​:58PM -0800\, David Dyck wrote​:

On Tue\, 7 Mar 2000\, Piotr Piatkowski wrote​:

I have answered on pl.comp.lang.perl with one of my favorite one-liners (how to sort list of \name\ lines by names​: print sort { ( $a =~ />(.*)\</ )[0] cmp ( $b =~ />(.*)\</ )[0] } \<>; - not very efficient but fits in one line :-) )

then friend of mine pointed to me\, that perlop lies about =~'s return value​:

just because you don't understand perlop (or someone)\, doesn't mean they are lying to you!

Just because perlop is lying doesn't mean someone misunderstands it. ;)

   Binary "=~" binds a scalar expression to a pattern match\.
   \[\.\.\.\]
   or transliterated instead of the default $\_\.  The return
   value indicates the success of the operation\.
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remember there is more that one way to indicate success\, and the number of elements in the array returns also indicate success

Regardless\, the original poster is correct. The documentation =~ should specify that it returns the same results as the operator which it is binding. To say that it simply "indicates the success of the operation" is misleading.

Which is true only in scalar context - in list context it returns the same value as patter match operator itself

the section on =~ is just part of what you should read if you are going to do matches\, read on to the section that starts​:

The documentation for =~ should direct the reader to that section.

Ronald

[p5pRT]

From [Unknown Contact. See original ticket]

On Wed\, 8 Mar 2000\, Ronald J Kimball wrote​:

   Binary "=~" binds a scalar expression to a pattern match\.
   \[\.\.\.\]
   or transliterated instead of the default $\_\.  The return
   value indicates the success of the operation\.
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remember there is more that one way to indicate success\, and the number of elements in the array returns also indicate success

Regardless\, the original poster is correct. The documentation =~ should specify that it returns the same results as the operator which it is binding. To say that it simply "indicates the success of the operation" is misleading.

Yes\, that's exactly what I meant. I was using bind operator in list context for years\, and found this so intuitive I had never checked this in documentation. So did majority of perl developers I guess.

But nevertheless\, perlop manpage is a little misleading here\, and IMHO it should be extended - reference to pattern matching documentation should be sufficient. Maybe I shouldn't say that man perlop lied - let's say it doesn't say the whole truth :-)

BTW\, forgive me my English\, it's not my primary language so I'm writing this with my dictionary handy :-)

-- Piotr Piątkowski\, Kraków perl -le 's**02).4&9%4^[./4(%2^0%2\,^([#+%2&**y%& -;^[%"`-{ a%%s%%$_%ee'

[p5pRT]

From [Unknown Contact. See original ticket]

Looks like no-one else is gonna do it...

---

*** perlop.pod.orig Wed Mar 8 09​:22​:04 2000 --- perlop.pod Wed Mar 8 09​:26​:52 2000 *************** *** 167\,182 ****  
  =head2 Binding Operators  
! Binary "=~" binds a scalar expression to a pattern match. Certain operations ! search or modify the string $_ by default. This operator makes that kind ! of operation work on some other string. The right argument is a search ! pattern\, substitution\, or transliteration. The left argument is what is ! supposed to be searched\, substituted\, or transliterated instead of the default ! $_. The return value indicates the success of the operation. If the ! right argument is an expression rather than a search pattern\, ! substitution\, or transliteration\, it is interpreted as a search pattern at run ! time. This can be less efficient than an explicit search\, because the ! pattern must be compiled every time the expression is evaluated.  
  Binary "!~" is just like "=~" except the return value is negated in   the logical sense. --- 167\,184 ----  
  =head2 Binding Operators  
! Binary "=~" binds a scalar expression to a pattern match. Certain ! operations search or modify the string $_ by default. This operator ! makes that kind of operation work on some other string. The right ! argument is a search pattern\, substitution\, or transliteration. The ! left argument is what is supposed to be searched\, substituted\, or ! transliterated instead of the default $_. The return value is the value ! returned by the corresponding operator​: C\\, C\ or C\ (see L\\, ! L\ or L\). If the right argument is an expression rather than a ! search pattern\, substitution\, or transliteration\, it is interpreted as a ! search pattern at run time. This can be less efficient than an explicit ! search\, because the pattern must be compiled every time the expression ! is evaluated.  
  Binary "!~" is just like "=~" except the return value is negated in   the logical sense.

[p5pRT]

From [Unknown Contact. See original ticket]

On Wed\, 8 Mar 2000\, Piotr Piatkowski wrote​:

On Wed\, 8 Mar 2000\, Ronald J Kimball wrote​:

   Binary "=~" binds a scalar expression to a pattern match\.
   \[\.\.\.\]
   or transliterated instead of the default $\_\.  The return
   value indicates the success of the operation\.
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remember there is more that one way to indicate success\, and the number of elements in the array returns also indicate success

Regardless\, the original poster is correct. The documentation =~ should specify that it returns the same results as the operator which it is binding. To say that it simply "indicates the success of the operation" is misleading.

Yes\, that's exactly what I meant. I was using bind operator in list context for years\, and found this so intuitive I had never checked this in documentation. So did majority of perl developers I guess.

But nevertheless\, perlop manpage is a little misleading here\, and IMHO it should be extended - reference to pattern matching documentation should be sufficient. Maybe I shouldn't say that man perlop lied - let's say it doesn't say the whole truth :-)

BTW\, forgive me my English\, it's not my primary language so I'm writing this with my dictionary handy :-)

The please forgive my initial reply too\, as I did not realize that you were just trying to improve the documentation.

Did you find the patch that Martyn Pearce \martyn@&#8203;inpharmatica\.co\.uk posted an improvement?

! The return value indicates the success of the operation.
--- 167\,184 ---- ! The return value is the value ! returned by the corresponding operator​: C\\, C\ or C\ (see L\\, ! L\ or L\).

Piotr Pi±tkowski\, Kraków perl -le 's**02).4&9%4^[./4(%2^0%2\,^([#+%2&**y%& -;^[%"`-{ a%%s%%$_%ee'

I liked your yaph signature

I kept on looking for the semicolons as I didn't trust what I was reading.

dd​:dcd$ perl -MO=Deparse\,-q -le 's**02).4&9%4^[./4(%2^0%2\,^([#+%2&**y%& -;^[%>

s[]\<02).4&9%4^[./4(%2^0%2\,^([#+%2&> * tr/ -;[^/`-e"g-{a / % s//$_;/ee;

One could stick a virus in there easily :-)

[p5pRT]

From [Unknown Contact. See original ticket]

On Wed\, 8 Mar 2000\, David Dyck wrote​:

The please forgive my initial reply too\, as I did not realize that you were just trying to improve the documentation.

Did you find the patch that Martyn Pearce \martyn@&#8203;inpharmatica\.co\.uk posted an improvement?

Yes\, thank you.

perl -le 's**02).4&9%4^[./4(%2^0%2\,^([#+%2&**y%& -;^[%"`-{ a%%s%%$_%ee'

I liked your yaph signature [...] One could stick a virus in there easily :-)

Yeah\, I was trying to make sig which\, when run\, would append to ~/.sig or ~/.signature file\, but I'm too busy to finish this...

-- Piotr Piątkowski\, Kraków perl -le 's**02).4&9%4^[./4(%2^0%2\,^([#+%2&**y%& -;^[%"`-{ a%%s%%$_%ee'