smartmatch PATCH 1 of 2 for 5.14.1: perlop.pod

[p5pRT]

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

Searchable as RT90906$

[p5pRT]

From tchrist@perl.com

This is the first of two inextricably linked doc patches mostly
related to the smartmatch operator. This one is against perlop,
and the next is against perlsyn. They must be taken together, or
else you will not understand what is talked about where and why,
thinking things are missing when actually they are only swapped
between the two pages. Nothing will be lost and much will be gained.

The thrust of this patch is to move the description of the ~~
operator into perlop where it properly belongs; given and when
remain relegated to perlsyn. This is also (nearly) the first-ever
set of examples for the smartmatch operator. Staggerment.

The 65-column nroff manpage limit is severely troublesome. I
originally had the equivalent code on the same line, but that
made lines wrap. Assuming that this was still highly undesirable,
I made a compromise of putting the semi-equiv code on the next
line. If someone has a better idea for how to lay out the table,
I'm all ears.

--tom

[p5pRT]

From tchrist@perl.com

perlop-smartmatch.patch

[p5pRT]

From @chipdude

On Tue, May 17, 2011 at 1​:14 PM, tchrist1 <perlbug-followup@​perl.org> wrote​:

The thrust of this patch is to move the description of the ~~
operator into perlop where it properly belongs; given and when
remain relegated to perlsyn. This is also (nearly) the first-ever
set of examples for the smartmatch operator.  Staggerment.

Indeed, thank you. This is quite a chunk of text to digest.

The 65-column nroff manpage limit is severely troublesome.

Shirley, this is an obsolete requirement. Heck, my TRS-80 Model I
almost-toy could show 64 columns. In 1978.
Why not 100 at least, these days?

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From tchrist@perl.com

Here is a patch against the first patch,
fixing typos reported to me.

  perlop-smartmatch-patch-on-patch.patch

--tom

[p5pRT]

From tchrist@perl.com

perlop-smartmatch-patch-on-patch.patch

--- perlop.pod	2011-05-17 14:01:55.000000000 -0600
+++ new/perlop.pod	2011-05-18 07:36:52.000000000 -0600
@@ -498,7 +498,7 @@
 precedence, C<~~> returns 1 for true and C<""> for false.  It is often best
 read aloud as "in", "inside of", or "is contained in", because the left
 operand is often looked for I<inside> the right operand.  That makes the
-order of the operands to the smartmatch operand is often opposite that of
+order of the operands to the smartmatch operand often opposite to that of
 the regular match operator.  In other words, the "smaller" thing is usually
 placed in the left operand and the larger one in the right.
 
@@ -527,7 +527,7 @@
                    like: grep { /Regexp/ } ARRAY
     undef     ARRAY      undef in ARRAY                                    
                    like: grep { !defined } ARRAY
-    Any       ARRAY      smart match each ARRAY element[3]                   
+    Any       ARRAY      smartmatch each ARRAY element[3]                   
                    like: grep { Any ~~ $_ } ARRAY
 
   Right operand is a HASH:
@@ -591,7 +591,7 @@
 Empty hashes or arrays match. 
 
 =item 2.
-That is, each element smart-matches the element of the same index in the other array.[3]
+That is, each element smartmatches the element of the same index in the other array.[3]
 
 =item 3.
 If a circular reference is found, fall back to referential equality. 
@@ -607,7 +607,7 @@
 involving hashes only consider hash keys, never hash values.
 
 The "like" code entry is not always an exact rendition.  For example, the
-smart match operator short-circuits whenever possible, but C<grep> does
+smartmatch operator short-circuits whenever possible, but C<grep> does
 not.  Also, C<grep> in scalar context returns the number of matches, but
 C<~~> returns only true or false.
 
@@ -640,9 +640,9 @@
     say "some keys end in e" if /e$/ ~~  %hash;
     say "some keys end in e" if /e$/ ~~ \%hash;
 
-Two arrays smartmatch if each element in the first array smart
-matches (that is, is "in") the corresponding element in the
-second array, recursively.
+Two arrays smartmatch if each element in the first array smartmatches
+(that is, is "in") the corresponding element in the second array,
+recursively.
 
     use v5.10.1;
     my @little = qw(red blue green);
@@ -721,12 +721,12 @@
 
 =head3 Smartmatching of Objects
 
-To avoid relying on an object's underlying representation, if the smart
-match's right operand is an object that doesn't overload C<~~>, it raises the
-exception "C<Smart matching a non-overloaded object breaks encapsulation>".
-That's because one has no business digging around to see whether something
-is "in" an object.  These are all illegal on objects without a C<~~>
-overload:
+To avoid relying on an object's underlying representation, if the
+smartmatch's right operand is an object that doesn't overload C<~~>,
+it raises the exception "C<Smartmatching a non-overloaded object
+breaks encapsulation>". That's because one has no business digging
+around to see whether something is "in" an object. These are all
+illegal on objects without a C<~~> overload:
 
     %hash ~~ $object
        42 ~~ $object

[p5pRT]

From tchrist@perl.com

Chip Salzenberg <rev.chip@​gmail.com> wrote
  on Tue, 17 May 2011 18​:35​:04 PDT​:

The 65-column nroff manpage limit is severely troublesome.

Shirley, this is an obsolete requirement. Heck, my TRS-80 Model I
almost-toy could show 64 columns. In 1978.

Manpages *can* get linewrapped or snipped at 65 columns. Currently
they seem actually to work on at least one system, but I haven't
done any checking around.

Why not 100 at least, these days?

Well, 100 isn't actually enough. See below.

But I very much feel the table would be easier to read this way​:

  1 2 3 4 5 6 7 8 9 10 11 12 13
  1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789

  Left Right Description and pseudocode Like
  ==============================================================================================================================
  Any undef check whether Any is undefined !defined Any
  Any Object invoke ~~ overloading on Object, or die

  ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2] ARRAY1[0] ~~ ARRAY2[0] && ARRAY1[1] ~~ ARRAY2[1] && ...
  HASH ARRAY any ARRAY elements exist as HASH keys grep { exists HASH->{$_} } ARRAY
  Regexp ARRAY any ARRAY elements pattern match Regexp grep { /Regexp/ } ARRAY
  undef ARRAY undef in ARRAY grep { !defined } ARRAY
  Any ARRAY smart match each ARRAY element[3] grep { Any ~~ $_ } ARRAY

  HASH1 HASH2 all same keys in both HASHes keys HASH1 == grep { exists HASH2->{$_} } keys HASH1
  ARRAY HASH any ARRAY elements exist as HASH keys grep { exists HASH->{$_} } ARRAY
  Regexp HASH any HASH keys pattern match Regexp grep { /Regexp/ } keys HASH
  undef HASH always false (undef can't be a key) 0 == 1
  Any HASH HASH key existence exists HASH->{Any}

  ARRAY CODE sub returns true on all ARRAY elements[1] !grep { !CODE->($_) } ARRAY
  HASH CODE sub returns true on all HASH keys[1] !grep { !CODE->($_) } keys HASH
  Any CODE sub passed Any returns true CODE->(Any)

  ARRAY Regexp any ARRAY elements match Regexp grep { /Regexp/ } ARRAY
  HASH Regexp any HASH keys match Regexp grep { /Regexp/ } keys HASH
  Any Regexp pattern match Any =~ /Regexp/

  Object Any invoke ~~ overloading on Object, or fall back to...
  Any Num numeric equality Any == Num
  Num nummy[4] numeric equality Num == nummy
  undef Any check whether undefined !defined(Any)
  Any Any string equality Any eq Any

Than I would this​:

  1 2 3 4 5 6 7 8
  12345678901234567890123456789012345678901234567890123456789012345678901234567890

  Left Right Description and pseudocode
  ===============================================================
  Any undef check whether Any is undefined
  like​: !defined Any

  Any Object invoke ~~ overloading on Object, or die

  Right operand is an ARRAY​:

  Left Right Description and pseudocode
  ===============================================================
  ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
  like​: (ARRAY1[0] ~~ ARRAY2[0]) && (ARRAY1[1] ~~ ARRAY2[1]) && ...
  HASH ARRAY any ARRAY elements exist as HASH keys
  like​: grep { exists HASH->{$_} } ARRAY
  Regexp ARRAY any ARRAY elements pattern match Regexp
  like​: grep { /Regexp/ } ARRAY
  undef ARRAY undef in ARRAY
  like​: grep { !defined } ARRAY
  Any ARRAY smart match each ARRAY element[3]
  like​: grep { Any ~~ $_ } ARRAY

  Right operand is a HASH​:

  Left Right Description and pseudocode
  ===============================================================
  HASH1 HASH2 all same keys in both HASHes
  like​: keys HASH1 == grep { exists HASH2->{$_} } keys HASH1
  ARRAY HASH any ARRAY elements exist as HASH keys
  like​: grep { exists HASH->{$_} } ARRAY
  Regexp HASH any HASH keys pattern match Regexp
  like​: grep { /Regexp/ } keys HASH
  undef HASH always false (undef can't be a key)
  like​: 0 == 1
  Any HASH HASH key existence
  like​: exists HASH->{Any}

  Right operand is CODE​:

  Left Right Description and pseudocode
  ===============================================================
  ARRAY CODE sub returns true on all ARRAY elements[1]
  like​: !grep { !CODE->($_) } ARRAY
  HASH CODE sub returns true on all HASH keys[1]
  like​: !grep { !CODE->($_) } keys HASH
  Any CODE sub passed Any returns true
  like​: CODE->(Any)

  Right operand is a Regexp​:

  Left Right Description and pseudocode
  ===============================================================
  ARRAY Regexp any ARRAY elements match Regexp
  like​: grep { /Regexp/ } ARRAY
  HASH Regexp any HASH keys match Regexp
  like​: grep { /Regexp/ } keys HASH
  Any Regexp pattern match
  like​: Any =~ /Regexp/

  Other​:

  Left Right Description and pseudocode
  ===============================================================
  Object Any invoke ~~ overloading on Object, or fall back to...

  Any Num numeric equality
  like​: Any == Num
  Num nummy[4] numeric equality
  like​: Num == nummy
  undef Any check whether undefined
  like​: !defined(Any)
  Any Any string equality
  like​: Any eq Any

Suggestions?

--tom

[p5pRT]

From rra@stanford.edu

Tom Christiansen <tchrist@​perl.com> writes​:

Manpages *can* get linewrapped or snipped at 65 columns. Currently
they seem actually to work on at least one system, but I haven't
done any checking around.

Most of the man implementations I've seen recently have started wrapping
at the terminal width or at 80 columns, but older man implementations
definitely wrapped narrower. I would expect to see problems, if any, on
systems like IRIX, old Solaris, that sort of thing. I no longer have
readily available the wide variety of UNIX implementations I used to have
to check things like this.

But I very much feel the table would be easier to read this way​:

[...]

Than I would this​:

         1         2         3         4         5         6         7         8
12345678901234567890123456789012345678901234567890123456789012345678901234567890

Left      Right      Description and pseudocode
===============================================================
Any       undef      check whether Any is undefined
               like​: \!defined Any

I actually prefer the second one even with a wide window because my eyes
don't get lost during carriage return. But that may just be me.

One thing that's worth remembering when it comes to going to longer line
widths is that while most people have the screen real estate to do this
these days with average fonts, there are a fair number of people with
minor or moderate eye problems that make "average" fonts pretty
unappealing and annoying, or even unreadable. And the first example made
the "Like" column mostly unuseful if one can't widen the screen. (Forced
line wrapping on a narrow screen isn't *too* bad for text, but it makes
code almost impossible to follow, at least for me.)

--
Russ Allbery (rra@​stanford.edu) <http​://www.eyrie.org/~eagle/>

[p5pRT]

From peter@peknet.com

Russ Allbery wrote on 05/18/2011 12​:53 PM​:

Tom Christiansen <tchrist@​perl.com> writes​:

Manpages *can* get linewrapped or snipped at 65 columns. Currently
they seem actually to work on at least one system, but I haven't
done any checking around.

Most of the man implementations I've seen recently have started wrapping
at the terminal width or at 80 columns, but older man implementations
definitely wrapped narrower. I would expect to see problems, if any, on
systems like IRIX, old Solaris, that sort of thing. I no longer have
readily available the wide variety of UNIX implementations I used to have
to check things like this.

Having been, in years past, the person responsible for maintaining the
man page formatting tools for SGI and Cray systems, I vote for the
80-column-or-narrower widths. We did 72 columns iirc, on the Cray systems.

Russ's rationale below is the big reason.

But I very much feel the table would be easier to read this way​:

[...]

Than I would this​:

         1         2         3         4         5         6         7         8
12345678901234567890123456789012345678901234567890123456789012345678901234567890

Left      Right      Description and pseudocode
===============================================================
Any       undef      check whether Any is undefined
               like​: \!defined Any

I actually prefer the second one even with a wide window because my eyes
don't get lost during carriage return. But that may just be me.

One thing that's worth remembering when it comes to going to longer line
widths is that while most people have the screen real estate to do this
these days with average fonts, there are a fair number of people with
minor or moderate eye problems that make "average" fonts pretty
unappealing and annoying, or even unreadable. And the first example made
the "Like" column mostly unuseful if one can't widen the screen. (Forced
line wrapping on a narrow screen isn't *too* bad for text, but it makes
code almost impossible to follow, at least for me.)

+1 on behalf of those of us with aging eyes.

--
Peter Karman . http​://peknet.com/ . peter@​peknet.com

[p5pRT]

From @cpansprout

On Tue May 17 13​:14​:03 2011, tom christiansen wrote​:

This is the first of two inextricably linked doc patches mostly
related to the smartmatch operator. This one is against perlop,
and the next is against perlsyn. They must be taken together, or
else you will not understand what is talked about where and why,
thinking things are missing when actually they are only swapped
between the two pages. Nothing will be lost and much will be gained.

The thrust of this patch is to move the description of the ~~
operator into perlop where it properly belongs; given and when
remain relegated to perlsyn. This is also (nearly) the first-ever
set of examples for the smartmatch operator. Staggerment.

The 65-column nroff manpage limit is severely troublesome. I
originally had the equivalent code on the same line, but that
made lines wrap. Assuming that this was still highly undesirable,
I made a compromise of putting the semi-equiv code on the next
line. If someone has a better idea for how to lay out the table,
I'm all ears.

--tom

With all your doc patches, you seem to be working against yourself. :-)

patching file pod/perlop.pod
Hunk #4 FAILED at 168.
Hunk #7 succeeded at 253 (offset 6 lines).
Hunk #8 succeeded at 273 (offset 6 lines).
Hunk #9 succeeded at 327 (offset 6 lines).
Hunk #10 succeeded at 347 (offset 6 lines).
Hunk #11 succeeded at 364 (offset 6 lines).
Hunk #12 succeeded at 396 (offset 6 lines).
Hunk #13 succeeded at 455 (offset 6 lines).
Hunk #14 succeeded at 474 (offset 6 lines).
Hunk #15 succeeded at 777 (offset 6 lines).
Hunk #16 succeeded at 795 (offset 6 lines).
Hunk #17 FAILED at 831.
Hunk #18 succeeded at 880 (offset 8 lines).
Hunk #19 FAILED at 970.
Hunk #20 FAILED at 1005.
Hunk #21 FAILED at 1024.
Hunk #22 FAILED at 1087.
Hunk #23 FAILED at 1149.
Hunk #24 FAILED at 1156.
Hunk #25 FAILED at 1181.
Hunk #26 FAILED at 1191.
Hunk #27 FAILED at 1252.
Hunk #28 succeeded at 1355 (offset 19 lines).
Hunk #29 FAILED at 1474.
Hunk #30 succeeded at 1591 (offset 32 lines).
Hunk #31 succeeded at 1619 (offset 32 lines).
Hunk #32 succeeded at 1643 (offset 32 lines).
Hunk #33 FAILED at 1667.
Hunk #34 succeeded at 1726 (offset 32 lines).
Hunk #35 FAILED at 1735.
Hunk #36 FAILED at 1744.
Hunk #37 succeeded at 1769 (offset 34 lines).
Hunk #38 FAILED at 1793.
Hunk #39 FAILED at 1835.
Hunk #40 FAILED at 1844.
Hunk #41 succeeded at 1889 with fuzz 1 (offset 58 lines).
Hunk #42 FAILED at 1922.
Hunk #43 succeeded at 1942 (offset 64 lines).
Hunk #44 succeeded at 1952 (offset 64 lines).
Hunk #45 succeeded at 1961 (offset 64 lines).
Hunk #46 succeeded at 2006 (offset 67 lines).
Hunk #47 succeeded at 2059 (offset 67 lines).
Hunk #48 succeeded at 2070 (offset 67 lines).
Hunk #49 succeeded at 2139 (offset 67 lines).
Hunk #50 FAILED at 2204.
Hunk #51 FAILED at 2217.
Hunk #52 succeeded at 2238 (offset 71 lines).
Hunk #53 FAILED at 2262.
Hunk #54 FAILED at 2278.
Hunk #55 succeeded at 2501 (offset 82 lines).
Hunk #56 succeeded at 2532 (offset 82 lines).
Hunk #57 succeeded at 2802 (offset 82 lines).
Hunk #58 succeeded at 2838 (offset 82 lines).
Hunk #59 succeeded at 2899 (offset 82 lines).
Hunk #60 succeeded at 2942 (offset 82 lines).
Hunk #61 succeeded at 2958 (offset 82 lines).
Hunk #62 succeeded at 2995 (offset 82 lines).
Hunk #63 succeeded at 3032 (offset 82 lines).
Hunk #64 succeeded at 3106 (offset 83 lines).
Hunk #65 succeeded at 3159 (offset 94 lines).

[p5pRT]

From @cpansprout

On Sun May 22 13​:46​:06 2011, sprout wrote​:

On Tue May 17 13​:14​:03 2011, tom christiansen wrote​:

This is the first of two inextricably linked doc patches mostly
related to the smartmatch operator. This one is against perlop,
and the next is against perlsyn. They must be taken together, or
else you will not understand what is talked about where and why,
thinking things are missing when actually they are only swapped
between the two pages. Nothing will be lost and much will be gained.

The thrust of this patch is to move the description of the ~~
operator into perlop where it properly belongs; given and when
remain relegated to perlsyn. This is also (nearly) the first-ever
set of examples for the smartmatch operator. Staggerment.

The 65-column nroff manpage limit is severely troublesome. I
originally had the equivalent code on the same line, but that
made lines wrap. Assuming that this was still highly undesirable,
I made a compromise of putting the semi-equiv code on the next
line. If someone has a better idea for how to lay out the table,
I'm all ears.

--tom

With all your doc patches, you seem to be working against yourself. :-)

patching file pod/perlop.pod
Hunk #4 FAILED at 168.
...

I’ve applied the first patch as 1ca345e. Since I had to apply
it manually, I omitted most of the whitespace changes.

The second one I applied as 40bec8a.

Thank you.

P.S.​: Lots of whitespace changes and reflow make it hard to resolve
conflicts.

--

Father Chrysostomos

[p5pRT]

From @cpansprout

On Thu Jan 05 20​:30​:58 2012, sprout wrote​:

On Sun May 22 13​:46​:06 2011, sprout wrote​:

On Tue May 17 13​:14​:03 2011, tom christiansen wrote​:

This is the first of two inextricably linked doc patches mostly
related to the smartmatch operator. This one is against perlop,
and the next is against perlsyn. They must be taken together, or
else you will not understand what is talked about where and why,
thinking things are missing when actually they are only swapped
between the two pages. Nothing will be lost and much will be gained.

The thrust of this patch is to move the description of the ~~
operator into perlop where it properly belongs; given and when
remain relegated to perlsyn. This is also (nearly) the first-ever
set of examples for the smartmatch operator. Staggerment.

The 65-column nroff manpage limit is severely troublesome. I
originally had the equivalent code on the same line, but that
made lines wrap. Assuming that this was still highly undesirable,
I made a compromise of putting the semi-equiv code on the next
line. If someone has a better idea for how to lay out the table,
I'm all ears.

--tom

With all your doc patches, you seem to be working against yourself. :-)

patching file pod/perlop.pod
Hunk #4 FAILED at 168.
...

I’ve applied the first patch as 1ca345e. Since I had to apply
it manually, I omitted most of the whitespace changes.

The second one I applied as 40bec8a.

Thank you.

P.S.​: Lots of whitespace changes and reflow make it hard to resolve
conflicts.

I forgot to mention​: I adjusted the table a bit to fit nicely in an
80-column terminal. Some of us still insist on reading all our manpages
that way. (-​:

--

Father Chrysostomos

[p5pRT]

@cpansprout - Status changed from 'open' to 'resolved'