[PATCH] Start converting pod/*.pod away from mentioning $a and $b in code excerpts.

[p5pRT]

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

Searchable as RT123081$

[p5pRT]

From @shlomif

The following patches against blead\, start to convert the code examples in pod/*.pod from using $a and $b which are special variables.

Regards\,

  Shlomi Fish

--

---

Shlomi Fish http​://www.shlomifish.org/ “So\, who the hell is Qoheleth?” - http​://shlom.in/qoheleth

* rindolf demands equal rights for years\, minutes\, hours and days to also get   YAAKOV’S GREAT HUGE LOVE.   — http​://www.shlomifish.org/humour/fortunes/sharp-perl.html

Please reply to list if it's a mailing list post - http​://shlom.in/reply .

[p5pRT]

From @shlomif

0003-a-b-deprecation-in-perlop.pod.patch

```diff From 1ca253617817d0904b4302f4387e52b0b6f61bcb Mon Sep 17 00:00:00 2001 From: Shlomi Fish Date: Wed, 29 Oct 2014 11:43:19 +0200 Subject: [PATCH 3/3] $a,$b deprecation in perlop.pod. --- pod/perlop.pod | 98 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/pod/perlop.pod b/pod/perlop.pod index a454dae..67b3fb5 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -6,15 +6,15 @@ perlop - Perl operators and precedence =head1 DESCRIPTION In Perl, the operator determines what operation is performed, -independent of the type of the operands. For example C<$a + $b> -is always a numeric addition, and if C<$a> or C<$b> do not contain +independent of the type of the operands. For example C<$x + $y> +is always a numeric addition, and if C<$x> or C<$y> do not contain numbers, an attempt is made to convert them to numbers first. This is in contrast to many other dynamic languages, where the operation is determined by the type of the first argument. It also means that Perl has two versions of some operators, one for numeric -and one for string comparison. For example C<$a == $b> compares -two numbers for equality, and C<$a eq $b> compares two strings. +and one for string comparison. For example C<$x == $y> compares +two numbers for equality, and C<$x eq $y> compares two strings. There are a few exceptions though: C can be either string repetition or list repetition, depending on the type of the left @@ -297,21 +297,21 @@ X X Binary "%" is the modulo operator, which computes the division remainder of its first argument with respect to its second argument. Given integer -operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is -C<$a> minus the largest multiple of C<$b> less than or equal to -C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the -smallest multiple of C<$b> that is not less than C<$a> (that is, the +operands C<$m> and C<$n>: If C<$n> is positive, then C<$m % $n> is +C<$m> minus the largest multiple of C<$n> less than or equal to +C<$m>. If C<$n> is negative, then C<$m % $n> is C<$m> minus the +smallest multiple of C<$n> that is not less than C<$m> (that is, the result will be less than or equal to zero). If the operands -C<$a> and C<$b> are floating point values and the absolute value of -C<$b> (that is C) is less than C<(UV_MAX + 1)>, only -the integer portion of C<$a> and C<$b> will be used in the operation +C<$m> and C<$n> are floating point values and the absolute value of +C<$n> (that is C) is less than C<(UV_MAX + 1)>, only +the integer portion of C<$m> and C<$n> will be used in the operation (Note: here C means the maximum of the unsigned integer type). -If the absolute value of the right operand (C) is greater than +If the absolute value of the right operand (C) is greater than or equal to C<(UV_MAX + 1)>, "%" computes the floating-point remainder -C<$r> in the equation C<($r = $a - $i*$b)> where C<$i> is a certain +C<$r> in the equation C<($r = $m - $i*$n)> where C<$i> is a certain integer that makes C<$r> have the same sign as the right operand -C<$b> (B as the left operand C<$a> like C function C) -and the absolute value less than that of C<$b>. +C<$n> (B as the left operand C<$m> like C function C) +and the absolute value less than that of C<$n>. Note that when C is in scope, "%" gives you direct access to the modulo operator as implemented by your C compiler. This operator is not as well defined for negative operands, but it will @@ -482,10 +482,10 @@ returns true, as does NaN != anything else. If your platform doesn't support NaNs then NaN is just a string with numeric value 0. X<< <=> >> X - $ perl -le '$a = "NaN"; print "No NaN support here" if $a == $a' - $ perl -le '$a = "NaN"; print "NaN support here" if $a != $a' + $ perl -le '$x = "NaN"; print "No NaN support here" if $x == $x' + $ perl -le '$x = "NaN"; print "NaN support here" if $x != $x' -(Note that the L, L, and L pragmas all +(Note that the L, L, and L pragmas all support "NaN".) Binary "eq" returns true if the left argument is stringwise equal to @@ -867,7 +867,7 @@ this is the same result as C<< defined(EXPR1) ? EXPR1 : EXPR2 >> (except that the ternary-operator form can be used as a lvalue, while C<< EXPR1 // EXPR2 >> cannot). This is very useful for providing default values for variables. If you actually want to test if -at least one of C<$a> and C<$b> is defined, use C. +at least one of C<$x> and C<$y> is defined, use C. The C<||>, C and C<&&> operators return the last value evaluated (unlike C's C<||> and C<&&>, which return 0 or 1). Thus, a reasonably @@ -1080,31 +1080,31 @@ is returned. For example: Scalar or list context propagates downward into the 2nd or 3rd argument, whichever is selected. - $a = $ok ? $b : $c; # get a scalar - @a = $ok ? @b : @c; # get an array - $a = $ok ? @b : @c; # oops, that's just a count! + $x = $ok ? $y : $z; # get a scalar + @x = $ok ? @y : @z; # get an array + $x = $ok ? @y : @z; # oops, that's just a count! The operator may be assigned to if both the 2nd and 3rd arguments are legal lvalues (meaning that you can assign to them): - ($a_or_b ? $a : $b) = $c; + ($x_or_y ? $x : $y) = $z; Because this operator produces an assignable result, using assignments without parentheses will get you in trouble. For example, this: - $a % 2 ? $a += 10 : $a += 2 + $x % 2 ? $x += 10 : $x += 2 Really means this: - (($a % 2) ? ($a += 10) : $a) += 2 + (($x % 2) ? ($x += 10) : $x) += 2 Rather than this: - ($a % 2) ? ($a += 10) : ($a += 2) + ($x % 2) ? ($x += 10) : ($x += 2) That should probably be written more simply as: - $a += ($a % 2) ? 10 : 2; + $x += ($x % 2) ? 10 : 2; =head2 Assignment Operators X X X<=> X<**=> X<+=> X<*=> X<&=> @@ -1115,11 +1115,11 @@ X<%=> X<^=> X Assignment operators work as in C. That is, - $a += 2; + $x += 2; is equivalent to - $a = $a + 2; + $x = $x + 2; although without duplicating any side effects that dereferencing the lvalue might trigger, such as from tie(). Other assignment operators work similarly. @@ -1151,12 +1151,12 @@ Although as of 5.14, that can be also be accomplished this way: Likewise, - ($a += 2) *= 3; + ($x += 2) *= 3; is equivalent to - $a += 2; - $a *= 3; + $x += 2; + $x *= 3; Similarly, a list assignment in list context produces the list of lvalues assigned to, and a list assignment in scalar context returns @@ -1265,9 +1265,9 @@ only if the left expression is false. Due to its precedence, you must be careful to avoid using it as replacement for the C<||> operator. It usually works out better for flow control than in assignments: - $a = $b or $c; # bug: this is wrong - ($a = $b) or $c; # really means this - $a = $b || $c; # better written this way + $x = $y or $z; # bug: this is wrong + ($x = $y) or $z; # really means this + $x = $y || $z; # better written this way However, when it's a list-context assignment and you're trying to use C<||> for control flow, you probably need "or" so that the assignment @@ -1344,7 +1344,7 @@ is the same as Note, however, that this does not always work for quoting Perl code: - $s = q{ if($a eq "}") ... }; # WRONG + $s = q{ if($x eq "}") ... }; # WRONG is a syntax error. The C module (standard as of v5.8, and from CPAN before then) is able to do this properly. @@ -1803,7 +1803,7 @@ empty pattern (which will always match). Note that it's possible to confuse Perl into thinking C (the empty regex) is really C (the defined-or operator). Perl is usually pretty good about this, but some pathological cases might trigger this, such as -C<$a///> (is that C<($a) / (//)> or C<$a // />?) and C +C<$x///> (is that C<($x) / (//)> or C<$x // />?) and C (C or C?). In all of these examples, Perl will assume you meant defined-or. If you meant the empty regex, just use parentheses or spaces to disambiguate, or even prefix the empty @@ -2088,7 +2088,7 @@ Examples: s/^=(\w+)/pod($1)/ge; # use function call $_ = 'abc123xyz'; - $a = s/abc/def/r; # $a is 'def123xyz' and + $x = s/abc/def/r; # $x is 'def123xyz' and # $_ remains 'abc123xyz'. # expand variables in $_, but dynamics only, using @@ -2717,13 +2717,13 @@ scalar. Note also that the interpolation code needs to make a decision on where the interpolated scalar ends. For instance, whether -C<< "a $b -> {c}" >> really means: +C<< "a $x -> {c}" >> really means: - "a " . $b . " -> {c}"; + "a " . $x . " -> {c}"; or: - "a " . $b -> {c}; + "a " . $x -> {c}; Most of the time, the longest possible text that does not include spaces between components and which contains matching braces or @@ -3261,14 +3261,14 @@ limited-precision representations. Or with rationals: - use 5.010; - use bigrat; - $a = 3/22; - $b = 4/6; - say "a/b is ", $a/$b; - say "a*b is ", $a*$b; - a/b is 9/44 - a*b is 1/11 + use 5.010; + use bigrat; + $x = 3/22; + $y = 4/6; + say "x/y is ", $x/$y; + say "x*y is ", $x*$y; + x/y is 9/44 + x*y is 1/11 Several modules let you calculate with (bound only by memory and CPU time) unlimited or fixed precision. There -- 2.1.2 ```

[p5pRT]

From @shlomif

0002-Move-away-from-a-and-b-for-examples.patch

```diff From 33e5196e660c1e372a9c640b10fc3a7474b9cb1a Mon Sep 17 00:00:00 2001 From: Shlomi Fish Date: Wed, 29 Oct 2014 11:19:21 +0200 Subject: [PATCH 2/3] Move away from $a and $b for examples. pod/perlvar.pod this time. --- pod/perlvar.pod | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 1a070a1..fe44c9d 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -371,19 +371,19 @@ X<$;> X<$SUBSEP> X The subscript separator for multidimensional array emulation. If you refer to a hash element as - $foo{$a,$b,$c} + $foo{$x,$y,$z} it really means - $foo{join($;, $a, $b, $c)} + $foo{join($;, $x, $y, $z)} But don't put - @foo{$a,$b,$c} # a slice--note the @ + @foo{$x,$y,$z} # a slice--note the @ which means - ($foo{$a},$foo{$b},$foo{$c}) + ($foo{$x},$foo{$y},$foo{$z}) Default is "\034", the same as SUBSEP in B. If your keys contain binary data there might not be any safe value for C<$;>. -- 2.1.2 ```

[p5pRT]

From @shlomif

0001-Move-the-POD-away-from-a-and-b.patch

```diff From 3d7e0760ae7fb7cea886098bf08470721d5141dc Mon Sep 17 00:00:00 2001 From: Shlomi Fish Date: Wed, 29 Oct 2014 11:06:30 +0200 Subject: [PATCH 1/3] Move the POD away from $a and $b. They are built ins and should not be used or overrided. Currently doing pod/perlthrtut.pod . --- pod/perlthrtut.pod | 66 +++++++++++++++++++++++++++--------------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod index e885bb2..f5e35a3 100644 --- a/pod/perlthrtut.pod +++ b/pod/perlthrtut.pod @@ -302,10 +302,10 @@ automatically. sleep(15); # Let thread run for awhile sub sub1 { - $a = 0; + my $count = 0; while (1) { - $a++; - print("\$a is $a\n"); + $count++; + print("\$count is $count\n"); sleep(1); } } @@ -424,22 +424,22 @@ number of pitfalls. One pitfall is the race condition: use threads; use threads::shared; - my $a :shared = 1; + my $x :shared = 1; my $thr1 = threads->create(\&sub1); my $thr2 = threads->create(\&sub2); $thr1->join(); $thr2->join(); - print("$a\n"); + print("$x\n"); - sub sub1 { my $foo = $a; $a = $foo + 1; } - sub sub2 { my $bar = $a; $a = $bar + 1; } + sub sub1 { my $foo = $x; $x = $foo + 1; } + sub sub2 { my $bar = $x; $x = $bar + 1; } -What do you think C<$a> will be? The answer, unfortunately, is I. Both C and C access the global variable C<$a>, once +What do you think C<$x> will be? The answer, unfortunately, is I. Both C and C access the global variable C<$x>, once to read and once to write. Depending on factors ranging from your thread implementation's scheduling algorithm to the phase of the moon, -C<$a> can be 2 or 3. +C<$x> can be 2 or 3. Race conditions are caused by unsynchronized access to shared data. Without explicit synchronization, there's no way to be sure that @@ -448,19 +448,19 @@ and the time you update it. Even this simple code fragment has the possibility of error: use threads; - my $a :shared = 2; - my $b :shared; - my $c :shared; - my $thr1 = threads->create(sub { $b = $a; $a = $b + 1; }); - my $thr2 = threads->create(sub { $c = $a; $a = $c + 1; }); + my $x :shared = 2; + my $y :shared; + my $z :shared; + my $thr1 = threads->create(sub { $y = $x; $x = $y + 1; }); + my $thr2 = threads->create(sub { $z = $x; $x = $z + 1; }); $thr1->join(); $thr2->join(); -Two threads both access C<$a>. Each thread can potentially be interrupted -at any point, or be executed in any order. At the end, C<$a> could be 3 -or 4, and both C<$b> and C<$c> could be 2 or 3. +Two threads both access C<$x>. Each thread can potentially be interrupted +at any point, or be executed in any order. At the end, C<$x> could be 3 +or 4, and both C<$y> and C<$z> could be 2 or 3. -Even C<$a += 5> or C<$a++> are not guaranteed to be atomic. +Even C<$x += 5> or C<$x++> are not guaranteed to be atomic. Whenever your program accesses data or resources that can be accessed by other threads, you must take steps to coordinate access or risk @@ -572,17 +572,17 @@ Consider the following code: use threads; - my $a :shared = 4; - my $b :shared = 'foo'; + my $x :shared = 4; + my $y :shared = 'foo'; my $thr1 = threads->create(sub { - lock($a); + lock($x); sleep(20); - lock($b); + lock($y); }); my $thr2 = threads->create(sub { - lock($b); + lock($y); sleep(20); - lock($a); + lock($x); }); This program will probably hang until you kill it. The only way it @@ -590,10 +590,10 @@ won't hang is if one of the two threads acquires both locks first. A guaranteed-to-hang version is more complicated, but the principle is the same. -The first thread will grab a lock on C<$a>, then, after a pause during which +The first thread will grab a lock on C<$x>, then, after a pause during which the second thread has probably had time to do some work, try to grab a -lock on C<$b>. Meanwhile, the second thread grabs a lock on C<$b>, then later -tries to grab a lock on C<$a>. The second lock attempt for both threads will +lock on C<$y>. Meanwhile, the second thread grabs a lock on C<$y>, then later +tries to grab a lock on C<$x>. The second lock attempt for both threads will block, each waiting for the other to release its lock. This condition is called a deadlock, and it occurs whenever two or @@ -604,8 +604,8 @@ resource is itself waiting for a lock to be released. There are a number of ways to handle this sort of problem. The best way is to always have all threads acquire locks in the exact same -order. If, for example, you lock variables C<$a>, C<$b>, and C<$c>, always lock -C<$a> before C<$b>, and C<$b> before C<$c>. It's also best to hold on to locks for +order. If, for example, you lock variables C<$x>, C<$y>, and C<$z>, always lock +C<$x> before C<$y>, and C<$y> before C<$z>. It's also best to hold on to locks for as short a period of time to minimize the risks of deadlock. The other synchronization primitives described below can suffer from @@ -961,9 +961,9 @@ though, regardless of how many CPUs a system might have. Since kernel threading can interrupt a thread at any time, they will uncover some of the implicit locking assumptions you may make in your -program. For example, something as simple as C<$a = $a + 2> can behave -unpredictably with kernel threads if C<$a> is visible to other -threads, as another thread may have changed C<$a> between the time it +program. For example, something as simple as C<$x = $x + 2> can behave +unpredictably with kernel threads if C<$x> is visible to other +threads, as another thread may have changed C<$x> between the time it was fetched on the right hand side and the time the new value is stored. -- 2.1.2 ```

[p5pRT]

From @jkeenan

On Wed Oct 29 03​:16​:15 2014\, shlomif@​shlomifish.org wrote​:

The following patches against blead\, start to convert the code examples in pod/*.pod from using $a and $b which are special variables.

Regards\,

Shlomi Fish

Thanks\, applied to blead in​: commit db69102781c2515ff4657c48b95696c5f5e3bb78 commit 592708b4f2c747075fb01e3ad9276a2a9b338f27 commit 920aefcab1aef66ce585b8cc2f371ae5bfc9ee63

-- James E Keenan (jkeenan@​cpan.org)

[p5pRT]

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

[p5pRT]

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