From d96b4ed5954b4baf2632159a91b8c6a0f219b51d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= Date: Wed, 16 Aug 2023 18:30:28 +0100 Subject: [PATCH] pod: eliminate references to `$a` and `$b` outside sort context This causes confusion for new users when they get told to not use those variables because of how they interact with sort and friends. This changes them to `$x` and `$y`, and also changes nearby variables to keep things consistent, such as `$c` -> `$z` and `@a` -> `@x`. I dind't touch `perlfilter.pod`, since that comes from the Filter dist, which is upstream CPAN. --- pod/buildtoc | 2 +- pod/perlcall.pod | 30 +++++++++---------- pod/perldbmfilter.pod | 2 +- pod/perldiag.pod | 64 ++++++++++++++++++++--------------------- pod/perldsc.pod | 2 +- pod/perlebcdic.pod | 12 ++++---- pod/perlembed.pod | 22 +++++++------- pod/perlfunc.pod | 20 ++++++------- pod/perlgit.pod | 4 +-- pod/perlhacktips.pod | 18 ++++++------ pod/perlinterp.pod | 40 +++++++++++++------------- pod/perlintro.pod | 14 ++++----- pod/perllocale.pod | 8 +++--- pod/perlop.pod | 4 +-- pod/perlpodspec.pod | 4 +-- pod/perlre.pod | 20 ++++++------- pod/perlrebackslash.pod | 4 +-- pod/perlrecharclass.pod | 6 ++-- pod/perlref.pod | 18 ++++++------ pod/perlsyn.pod | 12 ++++---- pod/perltie.pod | 6 ++-- pod/perluniintro.pod | 8 +++--- 22 files changed, 160 insertions(+), 160 deletions(-) diff --git a/pod/buildtoc b/pod/buildtoc index 053b1817d518..9c5571b687b8 100644 --- a/pod/buildtoc +++ b/pod/buildtoc @@ -149,7 +149,7 @@ EOH | perl -ne 'map { -r && print "$_ " } split'` # Bypass internal shell buffer limit -- can't use case - if perl -e '$a = shift; exit($a =~ m|/|)' $toroff; then + if perl -e '$x = shift; exit($x =~ m|/|)' $toroff; then echo "$me: empty file list -- did you run install?" >&2 exit 1 fi diff --git a/pod/perlcall.pod b/pod/perlcall.pod index b20bbdf4d9c5..b837b21284ae 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -601,8 +601,8 @@ and simply returns their sum. sub Adder { - my($a, $b) = @_; - $a + $b; + my($x, $y) = @_; + $x + $y; } Because we are now concerned with the return value from I, the C @@ -728,8 +728,8 @@ Here is the Perl subroutine sub AddSubtract { - my($a, $b) = @_; - ($a+$b, $a-$b); + my($x, $y) = @_; + ($x+$y, $x-$y); } and this is the C function @@ -916,11 +916,11 @@ result, the subroutine calls I. sub Subtract { - my ($a, $b) = @_; + my ($x, $y) = @_; - die "death can be fatal\n" if $a < $b; + die "death can be fatal\n" if $x < $y; - $a - $b; + $x - $y; } and some C to call it @@ -1030,9 +1030,9 @@ version of the call_Subtract example above inside a destructor: package Foo; sub new { bless {}, $_[0] } sub Subtract { - my($a,$b) = @_; - die "death can be fatal" if $a < $b; - $a - $b; + my($x,$y) = @_; + die "death can be fatal" if $x < $y; + $x - $y; } sub DESTROY { call_Subtract(5, 4); } sub foo { die "foo dies"; } @@ -1278,8 +1278,8 @@ virtual. The static method, C, prints out simply the class name and a version number. The virtual method, C, prints out a single element of the array. Here is an all-Perl example of using it. - $a = Mine->new('red', 'green', 'blue'); - $a->Display(1); + $x = Mine->new('red', 'green', 'blue'); + $x->Display(1); Mine->PrintID; will print @@ -1338,8 +1338,8 @@ the C and C methods from C. So the methods C and C can be invoked like this: - $a = Mine->new('red', 'green', 'blue'); - call_Method($a, 'Display', 1); + $x = Mine->new('red', 'green', 'blue'); + call_Method($x, 'Display', 1); call_PrintID('Mine', 'PrintID'); The only thing to note is that, in both the static and virtual methods, @@ -1365,7 +1365,7 @@ currently executing. And here is some Perl to test it. PrintContext; - $a = PrintContext; + $x = PrintContext; @a = PrintContext; The output from that will be diff --git a/pod/perldbmfilter.pod b/pod/perldbmfilter.pod index f804cb84cb32..309fa21716d2 100644 --- a/pod/perldbmfilter.pod +++ b/pod/perldbmfilter.pod @@ -103,7 +103,7 @@ fix very easily. $db->filter_store_value( sub { $_ .= "\0" } ); $hash{"abc"} = "def"; - my $a = $hash{"ABC"}; + my $x = $hash{"ABC"}; # ... undef $db; untie %hash; diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 041061fb3930..75b847353aeb 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -228,16 +228,16 @@ coerced to a scalar - the number of elements in the array. (F) Each subroutine signature parameter declaration must start with a valid sigil; for example: - sub foo ($a, $, $b = 1, @c) {} + sub foo ($x, $, $y = 1, @z) {} =item A slurpy parameter may not have a default value (F) Only scalar subroutine signature parameters may have a default value; for example: - sub foo ($a = 1) {} # legal - sub foo (@a = (1)) {} # invalid - sub foo (%a = (a => b)) {} # invalid + sub foo ($x = 1) {} # legal + sub foo (@x = (1)) {} # invalid + sub foo (%x = (a => b)) {} # invalid =item assertion botched: %s @@ -2890,7 +2890,7 @@ For example: use feature 'signatures; sub foo ($$) {} # illegal - was expecting a signature - sub foo ($a, $b) + sub foo ($x, $y) :prototype($$) {} # legal @@ -2938,9 +2938,9 @@ other than C<=> introducing a default, C<,> or C<)>. use feature 'signatures'; sub foo ($=1) {} # legal - sub foo ($a = 1) {} # legal - sub foo ($a += 1) {} # illegal - sub foo ($a == 1) {} # illegal + sub foo ($x = 1) {} # legal + sub foo ($x += 1) {} # illegal + sub foo ($x == 1) {} # illegal =item Illegal pattern in regex; marked by S<<-- HERE> in m/%s/ @@ -3064,8 +3064,8 @@ throwing an exception. =item Initialization of state variables in list currently forbidden (F) C only permits initializing a single variable, specified -without parentheses. So C and C are -allowed, but not C or C<(state $a) = 42>. To initialize +without parentheses. So C and C are +allowed, but not C or C<(state $x) = 42>. To initialize more than one C variable, initialize them one at a time. =item %%s[%s] in scalar context better written as $%s[%s] @@ -3830,8 +3830,8 @@ doing it Perl met a malformed Unicode surrogate. =item Mandatory parameter follows optional parameter -(F) In a subroutine signature, you wrote something like "$a = undef, -$b", making an earlier parameter optional and a later one mandatory. +(F) In a subroutine signature, you wrote something like "$x = undef, +$y", making an earlier parameter optional and a later one mandatory. Parameters are filled from left to right, so it's impossible for the caller to omit an earlier one and pass a later one. If you want to act as if the parameters are filled from right to left, declare the rightmost @@ -4162,8 +4162,8 @@ They're written like C<$foo[1][2][3]>, as in C. the last parameter, and there must not be more than one of them; for example: - sub foo ($a, @b) {} # legal - sub foo ($a, @b, %) {} # invalid + sub foo ($x, @y) {} # legal + sub foo ($x, @y, %) {} # invalid =item '/' must follow a numeric type in unpack @@ -4568,10 +4568,10 @@ particular to avoid confusion with the C<$#> variable. For example: # bad sub f ($# ignore first arg - , $b) {} + , $y) {} # good sub f ($, # ignore first arg - $b) {} + $y) {} =item Not an ARRAY reference @@ -4811,10 +4811,10 @@ example, if you say "*foo *foo" it will be interpreted as if you said =item Optional parameter lacks default expression -(F) In a subroutine signature, you wrote something like "$a =", making a +(F) In a subroutine signature, you wrote something like "$x =", making a named optional parameter without a default value. A nameless optional parameter is permitted to have no default value, but a named one must -have a specific default. You probably want "$a = undef". +have a specific default. You probably want "$x = undef". =item "our" variable %s redeclared @@ -5370,15 +5370,15 @@ Perl assumes that memory is now corrupted. See L. flow operator (e.g. C) and a low-precedence operator like C. Consider: - sub { return $a or $b; } + sub { return $x or $y; } This is parsed as: - sub { (return $a) or $b; } + sub { (return $x) or $y; } Which is effectively just: - sub { return $a; } + sub { return $x; } Either use parentheses or the high-precedence variant of the operator. @@ -6190,8 +6190,8 @@ C may break this. come before the signature. Note that this order was the opposite in versions 5.22..5.26. So: - sub foo :lvalue ($a, $b) { ... } # 5.20 and 5.28 + - sub foo ($a, $b) :lvalue { ... } # 5.22 .. 5.26 + sub foo :lvalue ($x, $y) { ... } # 5.20 and 5.28 + + sub foo ($x, $y) :lvalue { ... } # 5.22 .. 5.26 =item Subroutine "&%s" is not available @@ -7105,12 +7105,12 @@ flags for the regex. One of the ones you specified is invalid. One way this can happen is if you didn't put in white space between the end of the regex and a following alphanumeric operator: - if ($a =~ /foo/and $bar == 3) { ... } + if ($x =~ /foo/and $bar == 3) { ... } The C<"a"> is a valid modifier flag, but the C<"n"> is not, and raises this error. Likely what was meant instead was: - if ($a =~ /foo/ and $bar == 3) { ... } + if ($x =~ /foo/ and $bar == 3) { ... } =item Unknown "re" subpragma '%s' (known ones are: %s) @@ -7881,26 +7881,26 @@ declared in an outer anonymous subroutine that has not yet been created. (Remember that named subs are created at compile time, while anonymous subs are created at run-time.) For example, - sub { my $a; sub f { $a } } + sub { my $x; sub f { $x } } -At the time that f is created, it can't capture the current value of $a, +At the time that f is created, it can't capture the current value of $x, since the anonymous subroutine hasn't been created yet. Conversely, the following won't give a warning since the anonymous subroutine has by now been created and is live: - sub { my $a; eval 'sub f { $a }' }->(); + sub { my $x; eval 'sub f { $x }' }->(); The second situation is caused by an eval accessing a variable that has gone out of scope, for example, sub f { - my $a; - sub { eval '$a' } + my $x; + sub { eval '$x' } } f()->(); -Here, when the '$a' in the eval is being compiled, f() is not currently -being executed, so its $a is not available for capture. +Here, when the '$x' in the eval is being compiled, f() is not currently +being executed, so its $x is not available for capture. =item Variable "%s" is not imported%s diff --git a/pod/perldsc.pod b/pod/perldsc.pod index 2f20fc0c240b..239d54e9679e 100644 --- a/pod/perldsc.pod +++ b/pod/perldsc.pod @@ -105,7 +105,7 @@ That's because Perl doesn't (ever) implicitly dereference your variables. If you want to get at the thing a reference is referring to, then you have to do this yourself using either prefix typing indicators, like C<${$blah}>, C<@{$blah}>, C<@{$blah[$i]}>, or else postfix pointer arrows, -like C<$a-E[3]>, C<$h-E{fred}>, or even C<$ob-Emethod()-E[3]>. +like C<< $arr->[3] >>, C<< $hash->{fred} >>, or even C<< $obj->method()->[3] >>. =head1 COMMON MISTAKES diff --git a/pod/perlebcdic.pod b/pod/perlebcdic.pod index 5ffefccf8cfa..7cc3303753b4 100644 --- a/pod/perlebcdic.pod +++ b/pod/perlebcdic.pod @@ -288,9 +288,9 @@ be compiled to run on. my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' ); - # $a is in EBCDIC code points - from_to($a, $ebcdic{ord '^'}, 'latin1'); - # $a is ISO 8859-1 code points + # $x is in EBCDIC code points + from_to($x, $ebcdic{ord '^'}, 'latin1'); + # $x is ISO 8859-1 code points and from Latin-1 code points to EBCDIC code points @@ -298,9 +298,9 @@ and from Latin-1 code points to EBCDIC code points my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' ); - # $a is ISO 8859-1 code points - from_to($a, 'latin1', $ebcdic{ord '^'}); - # $a is in EBCDIC code points + # $x is ISO 8859-1 code points + from_to($x, 'latin1', $ebcdic{ord '^'}); + # $x is in EBCDIC code points For doing I/O it is suggested that you use the autotranslating features of PerlIO, see L. diff --git a/pod/perlembed.pod b/pod/perlembed.pod index afeb68733de4..5951aefd9b23 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -339,18 +339,18 @@ the first, a C from the second, and a C from the third. PL_exit_flags |= PERL_EXIT_DESTRUCT_END; perl_run(my_perl); - /** Treat $a as an integer **/ - eval_pv("$a = 3; $a **= 2", TRUE); - printf("a = %d\n", SvIV(get_sv("a", 0))); + /** Treat $x as an integer **/ + eval_pv("$x = 3; $x **= 2", TRUE); + printf("x = %d\n", SvIV(get_sv("x", 0))); - /** Treat $a as a float **/ - eval_pv("$a = 3.14; $a **= 2", TRUE); - printf("a = %f\n", SvNV(get_sv("a", 0))); + /** Treat $x as a float **/ + eval_pv("$x = 3.14; $x **= 2", TRUE); + printf("x = %f\n", SvNV(get_sv("x", 0))); - /** Treat $a as a string **/ + /** Treat $x as a string **/ eval_pv( - "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE); - printf("a = %s\n", SvPV_nolen(get_sv("a", 0))); + "$x = 'rekcaH lreP rehtonA tsuJ'; $x = reverse($x);", TRUE); + printf("x = %s\n", SvPV_nolen(get_sv("x", 0))); perl_destruct(my_perl); perl_free(my_perl); @@ -614,8 +614,8 @@ sounds, because Perl implements ** with C's I function). First I'll create a stub exponentiation function in I: sub expo { - my ($a, $b) = @_; - return $a ** $b; + my ($x, $y) = @_; + return $x ** $y; } Now I'll create a C program, I, with a function diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index f9858d24f3cb..cf59b0b762d6 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -696,7 +696,7 @@ the stat buffer was filled by an L|/lstat FILEHANDLE> call, C<-T> and C<-B> will reset it with the results of C). Example: - print "Can do.\n" if -r $a || -w _ || -x _; + print "Can do.\n" if -r $x || -w _ || -x _; stat($filename); print "Readable\n" if -r _; @@ -1216,8 +1216,8 @@ Note that parentheses are necessary when you're chomping anything that is not a simple variable. This is because C is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as C which you might expect. Similarly, -C is interpreted as C rather than -as C. +C is interpreted as C rather than +as C. =item chop VARIABLE X @@ -2439,10 +2439,10 @@ L|perlvar/$@>. Examples: # make divide-by-zero nonfatal - eval { $answer = $a / $b; }; warn $@ if $@; + eval { $answer = $x / $y; }; warn $@ if $@; # same thing, but less efficient - eval '$answer = $a / $b'; warn $@ if $@; + eval '$answer = $x / $y'; warn $@ if $@; # a compile-time error eval { $answer = }; # WRONG @@ -2462,7 +2462,7 @@ You can use the C construct for this purpose, as this example shows: # a private exception trap for divide-by-zero - eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; + eval { local $SIG{'__DIE__'}; $answer = $x / $y; }; warn $@ if $@; This is especially significant, given that C<__DIE__> hooks can call @@ -8750,14 +8750,14 @@ would have been the next argument. So: - printf "<%*.*s>", $a, $b, $c; + printf "<%*.*s>", $x, $y, $z; -uses C<$a> for the width, C<$b> for the precision, and C<$c> +uses C<$x> for the width, C<$y> for the precision, and C<$z> as the value to format; while: - printf '<%*1$.*s>', $a, $b; + printf '<%*1$.*s>', $x, $y; -would use C<$a> for the width and precision, and C<$b> as the +would use C<$x> for the width and precision, and C<$y> as the value to format. Here are some more examples; be aware that when using an explicit diff --git a/pod/perlgit.pod b/pod/perlgit.pod index b354b73df939..4f354ee2dbb4 100644 --- a/pod/perlgit.pod +++ b/pod/perlgit.pod @@ -334,11 +334,11 @@ The core provides a wrapper program, F, which attempts to simplify as much as possible, making bisecting as simple as running a Perl one-liner. For example, if you want to know when this became an error: - perl -e 'my $a := 2' + perl -e 'my $x := 2' you simply run this: - .../Porting/bisect.pl -e 'my $a := 2;' + .../Porting/bisect.pl -e 'my $x := 2;' Using F, with one command (and no other files) it's easy to find out diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod index c93d39af3030..f26fad8e3854 100644 --- a/pod/perlhacktips.pod +++ b/pod/perlhacktips.pod @@ -1154,9 +1154,9 @@ options are probably For example - $ perl -Dst -e '$a + 1' + $ perl -Dst -e '$x + 1' .... - (-e:1) gvsv(main::a) + (-e:1) gvsv(main::x) => UNDEF (-e:1) const(IV(1)) => UNDEF IV(1) @@ -1293,8 +1293,8 @@ One way to get around this macro hell is to use the dumping functions in F; these work a little like an internal L, but they also cover OPs and other structures that you can't get at from Perl. Let's take an example. -We'll use the C<$a = $b + $c> we used before, but give it a bit of -context: C<$b = "6XXXX"; $c = 2.3;>. Where's a good place to stop and +We'll use the C<$x = $y + $z> we used before, but give it a bit of +context: C<$y = "6XXXX"; $z = 2.3;>. Where's a good place to stop and poke around? What about C, the function we examined earlier to implement the @@ -1307,7 +1307,7 @@ Notice we use C and not C - see L. With the breakpoint in place, we can run our program: - (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c' + (gdb) run -e '$y = "6XXXX"; $z = 2.3; $x = $y + $z' Lots of junk will go past as gdb reads in the relevant source files and libraries, and then: @@ -1333,7 +1333,7 @@ C uses C - but doesn't remove it. We then use C to get the NV from C in the same way as before - yes, C uses C. -Since we don't have an NV for C<$b>, we'll have to use C to +Since we don't have an NV for C<$y>, we'll have to use C to convert it. If we step again, we'll find ourselves there: (gdb) step @@ -1403,8 +1403,8 @@ And in gdb do: And then step until you hit what you're looking for. This works well in a loop if you want to only break at certain iterations: - for my $c (1..100) { - study if $c == 50; + for my $i (1..100) { + study if $i == 50; } =head2 Using gdb to look at what the parser/lexer are doing @@ -1423,7 +1423,7 @@ And in gdb: If you want to see what the parser/lexer is doing inside of C blocks and the like you need to be a little trickier: - if ($a && $b && do { BEGIN { study } 1 } && $c) { ... } + if ($x && $y && do { BEGIN { study } 1 } && $z) { ... } =head1 SOURCE CODE STATIC ANALYSIS diff --git a/pod/perlinterp.pod b/pod/perlinterp.pod index 66dd22704e11..eed9d6728f3a 100644 --- a/pod/perlinterp.pod +++ b/pod/perlinterp.pod @@ -497,7 +497,7 @@ macro which gives us the end of the string, so that needs to be a C<"\0">. Line 13 manipulates the flags; since we've changed the PV, any IV or NV -values will no longer be valid: if we have C<$a=10; $a.="6";> we don't +values will no longer be valid: if we have C<$x=10; $x.="6";> we don't want to use the old IV of 10. C is a special UTF-8-aware version of C, a macro which turns off the IOK and NOK flags and turns on POK. The final C is a macro which @@ -532,27 +532,27 @@ finished parsing, and get it to dump out the tree. This is exactly what the compiler backends L, L and CPAN module : +Let's have a look at how Perl sees C<$x = $y + $z>: - % perl -MO=Terse -e '$a=$b+$c' + % perl -MO=Terse -e '$x=$y+$z' 1 LISTOP (0x8179888) leave 2 OP (0x81798b0) enter 3 COP (0x8179850) nextstate 4 BINOP (0x8179828) sassign 5 BINOP (0x8179800) add [1] 6 UNOP (0x81796e0) null [15] - 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *b + 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *y 8 UNOP (0x81797e0) null [15] - 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *c + 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *z 10 UNOP (0x816b4f0) null [15] - 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *a + 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *x Let's start in the middle, at line 4. This is a BINOP, a binary operator, which is at location C<0x8179828>. The specific operator in question is C - scalar assignment - and you can find the code which implements it in the function C in F. As a binary operator, it has two children: the add operator, providing the -result of C<$b+$c>, is uppermost on line 5, and the left hand side is +result of C<$y+$z>, is uppermost on line 5, and the left hand side is on line 10. Line 10 is the null op: this does exactly nothing. What is that doing @@ -565,7 +565,7 @@ easier just to replace the redundant operation with the null op. Originally, the tree would have looked like this: 10 SVOP (0x816b4f0) rv2sv [15] - 11 SVOP (0x816dcf0) gv GV (0x80fa460) *a + 11 SVOP (0x816dcf0) gv GV (0x80fa460) *x That is, fetch the C entry from the main symbol table, and then look at the scalar component of it: C (C in F) @@ -599,36 +599,36 @@ That's how Perl parsed the program, from top to bottom: = / \ / \ - $a + + $x + / \ - $b $c + $y $z However, it's impossible to B the operations in this order: -you have to find the values of C<$b> and C<$c> before you add them +you have to find the values of C<$y> and C<$z> before you add them together, for instance. So, the other thread that runs through the op tree is the execution order: each op has a field C which points to the next op to be run, so following these pointers tells us how perl executes the code. We can traverse the tree in this order using the C option to C: - % perl -MO=Terse,exec -e '$a=$b+$c' + % perl -MO=Terse,exec -e '$x=$y+$z' 1 OP (0x8179928) enter 2 COP (0x81798c8) nextstate - 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *b - 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *c + 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *y + 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *z 5 BINOP (0x8179878) add [1] - 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *a + 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *x 7 BINOP (0x81798a0) sassign 8 LISTOP (0x8179900) leave This probably makes more sense for a human: enter a block, start a -statement. Get the values of C<$b> and C<$c>, and add them together. -Find C<$a>, and assign one to the other. Then leave. +statement. Get the values of C<$y> and C<$z>, and add them together. +Find C<$x>, and assign one to the other. Then leave. The way Perl builds up these op trees in the parsing process can be unravelled by examining F, the lexer, and F, the YACC -grammar. Let's look at the code that constructs the tree for C<$a = $b + -$c>. +grammar. Let's look at the code that constructs the tree for C<$x = $y + +$z>. First, we'll look at the C function in the lexer. We want to look for C, where x is the first character of the operator. @@ -664,7 +664,7 @@ returns an C token. Now that we know the two token types we want to look for in the parser, let's take the piece of F we need to construct the tree for -C<$a = $b + $c> +C<$x = $y + $z> 1 term : term ASSIGNOP term 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); } diff --git a/pod/perlintro.pod b/pod/perlintro.pod index 79f9b206df21..1841288e6206 100644 --- a/pod/perlintro.pod +++ b/pod/perlintro.pod @@ -490,9 +490,9 @@ detail.) Many operators can be combined with a C<=> as follows: - $a += 1; # same as $a = $a + 1 - $a -= 1; # same as $a = $a - 1 - $a .= "\n"; # same as $a = $a . "\n"; + $x += 1; # same as $x = $x + 1 + $x -= 1; # same as $x = $x - 1 + $x .= "\n"; # same as $x = $x . "\n"; =head2 Files and I/O @@ -546,7 +546,7 @@ elsewhere. However, in short: =item Simple matching if (/foo/) { ... } # true if $_ contains "foo" - if ($a =~ /foo/) { ... } # true if $a contains "foo" + if ($x =~ /foo/) { ... } # true if $x contains "foo" The C matching operator is documented in L. It operates on C<$_> by default, or can be bound to another variable using the C<=~> @@ -555,9 +555,9 @@ binding operator (also documented in L). =item Simple substitution s/foo/bar/; # replaces foo with bar in $_ - $a =~ s/foo/bar/; # replaces foo with bar in $a - $a =~ s/foo/bar/g; # replaces ALL INSTANCES of foo with bar - # in $a + $x =~ s/foo/bar/; # replaces foo with bar in $x + $x =~ s/foo/bar/g; # replaces ALL INSTANCES of foo with bar + # in $x The C substitution operator is documented in L. diff --git a/pod/perllocale.pod b/pod/perllocale.pod index cb40f385a129..e0ba47c092ee 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -1045,7 +1045,7 @@ so on. (See L if you care about these things.) $n = 5/2; # Assign numeric 2.5 to $n - $a = " $n"; # Locale-dependent conversion to string + $x = " $n"; # Locale-dependent conversion to string print "half five is $n\n"; # Locale-dependent output @@ -1413,8 +1413,8 @@ be confused, perhaps silently. use locale; use POSIX qw(locale_h); setlocale(LC_NUMERIC, "fr_FR") or die "Pardon"; - my $a = 1.2; - print eval "$a + 1.5"; + my $x = 1.2; + print eval "$x + 1.5"; print "\n"; prints C<13,5>. This is because in that locale, the comma is the @@ -1427,7 +1427,7 @@ generated. If you do string C's within the scope of S>, you should instead change the C line to do something like: - print eval "no locale; $a + 1.5"; + print eval "no locale; $x + 1.5"; This prints C<2.7>. diff --git a/pod/perlop.pod b/pod/perlop.pod index 07c01a5279f8..d7743775c6a4 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -2721,8 +2721,8 @@ If the C modifier is specified, sequences of characters, all in a row, that were transliterated to the same character are squashed down to a single instance of that character. - my $a = "aaabbbca"; - $a =~ tr/ab/dd/s; # $a now is "dcd" + my $x = "aaabbbca"; + $x =~ tr/ab/dd/s; # $x now is "dcd" If the C modifier is used, the I is always interpreted exactly as specified. Otherwise, if the I is shorter diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod index 7be15853a9f9..ca09d28555d3 100644 --- a/pod/perlpodspec.pod +++ b/pod/perlpodspec.pod @@ -82,11 +82,11 @@ no C line. actually knows to look for pod escapes even in the middle of a paragraph. This means that the following secret stuff will be ignored by both the compiler and the translators. - $a=3; + $x=3; =secret stuff warn "Neither POD nor CODE!?" =cut back - print "got $a\n"; + print "got $x\n"; You probably shouldn't rely upon the warn() being podded out forever. Not all pod translators are well-behaved in this regard, and perhaps the compiler will become pickier. diff --git a/pod/perlre.pod b/pod/perlre.pod index 300237f834bc..dc4e80752b1a 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -1217,8 +1217,8 @@ using C<"$+{I}">. Braces are required in referring to named capture groups, but are optional for absolute or relative numbered ones. Braces are safer when creating a regex by -concatenating smaller strings. For example if you have C, and C<$a> -contained C<"\g1">, and C<$b> contained C<"37">, you would get C which +concatenating smaller strings. For example if you have C, and C<$x> +contained C<"\g1">, and C<$y> contained C<"37">, you would get C which is probably not what you intended. If you use braces, you may also optionally add any number of blank @@ -1269,14 +1269,14 @@ Examples: /((.)(.)(.)(.)(.)(.)(.)(.)(.))\10/ # \10 is a backreference /((.)(.)(.)(.)(.)(.)(.)(.)(.))\010/ # \010 is octal - $a = '(.)\1'; # Creates problems when concatenated. - $b = '(.)\g{1}'; # Avoids the problems. - "aa" =~ /${a}/; # True - "aa" =~ /${b}/; # True - "aa0" =~ /${a}0/; # False! - "aa0" =~ /${b}0/; # True - "aa\x08" =~ /${a}0/; # True! - "aa\x08" =~ /${b}0/; # False + $x = '(.)\1'; # Creates problems when concatenated. + $y = '(.)\g{1}'; # Avoids the problems. + "aa" =~ /${x}/; # True + "aa" =~ /${y}/; # True + "aa0" =~ /${x}0/; # False! + "aa0" =~ /${y}0/; # True + "aa\x08" =~ /${x}0/; # True! + "aa\x08" =~ /${y}0/; # False Several special variables also refer back to portions of the previous match. C<$+> returns whatever the last bracket match matched. diff --git a/pod/perlrebackslash.pod b/pod/perlrebackslash.pod index d6539ad99df3..14afb9728455 100644 --- a/pod/perlrebackslash.pod +++ b/pod/perlrebackslash.pod @@ -434,8 +434,8 @@ capture group in the regex. The C<\gI> form can be equivalently written as C<\g{I}> which avoids ambiguity when building a regex by concatenating shorter -strings. Otherwise if you had a regex C, and C<$a> contained -C<"\g1">, and C<$b> contained C<"37">, you would get C which is +strings. Otherwise if you had a regex C, and C<$x> contained +C<"\g1">, and C<$y> contained C<"37">, you would get C which is probably not what you intended. In the C<\I> form, I must not begin with a "0", and there must be at diff --git a/pod/perlrecharclass.pod b/pod/perlrecharclass.pod index 85158cd24fe6..f383e56983c0 100644 --- a/pod/perlrecharclass.pod +++ b/pod/perlrecharclass.pod @@ -527,9 +527,9 @@ evaluated in single-quotish context, variable interpolation will take place before the bracketed class is parsed: $, = "\t| "; - $a =~ m'[$,]'; # single-quotish: matches '$' or ',' - $a =~ q{[$,]}' # same - $a =~ m/[$,]/; # double-quotish: Because we made an + $x =~ m'[$,]'; # single-quotish: matches '$' or ',' + $x =~ q{[$,]}' # same + $x =~ m/[$,]/; # double-quotish: Because we made an # assignment to $, above, this now # matches "\t", "|", or " " diff --git a/pod/perlref.pod b/pod/perlref.pod index 6934e0bb7eda..197db0dc711e 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -97,8 +97,8 @@ Taking a reference to an enumerated list is not the same as using square brackets--instead it's the same as creating a list of references! - @list = (\$a, \@b, \%c); - @list = \($a, @b, %c); # same thing! + @list = (\$x, \@y, \%z); + @list = \($x, @y, %z); # same thing! As a special case, C<\(@foo)> returns a list of references to the contents of C<@foo>, not a reference to C<@foo> itself. Likewise for C<%foo>, @@ -787,7 +787,7 @@ performs an aliasing operation, so that the variable name referenced on the left-hand side becomes an alias for the thing referenced on the right-hand side: - \$a = \$b; # $a and $b now point to the same scalar + \$x = \$y; # $x and $y now point to the same scalar \&foo = \&bar; # foo() now means bar() This syntax must be enabled with C. It is @@ -840,11 +840,11 @@ right type. Parentheses immediately surrounding an array (and possibly also C/C/C/C) will make each element of the array an alias to the corresponding scalar referenced on the right-hand side: - \(@a) = \(@b); # @a and @b now have the same elements - \my(@a) = \(@b); # likewise - \(my @a) = \(@b); # likewise - push @a, 3; # but now @a has an extra element that @b lacks - \(@a) = (\$a, \$b, \$c); # @a now contains $a, $b, and $c + \(@x) = \(@y); # @x and @y now have the same elements + \my(@x) = \(@y); # likewise + \(my @x) = \(@y); # likewise + push @x, 3; # but now @x has an extra element that @y lacks + \(@x) = (\$x, \$y, \$z); # @x now contains $x, $y, and $z Combining that form with C and putting parentheses immediately around a hash are forbidden (because it is not clear what they should do): @@ -920,7 +920,7 @@ X X You may not (usefully) use a reference as the key to a hash. It will be converted into a string: - $x{ \$a } = $a; + $x{ \$x } = $x; If you try to dereference the key, it won't do a hard dereference, and you won't accomplish what you're attempting. You might want to do something diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index 5245c80e4893..d1956f406167 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -42,14 +42,14 @@ you'll be notified of an uninitialized value whenever you treat C as a string or a number. Well, usually. Boolean contexts, such as: - if ($a) {} + if ($x) {} are exempt from warnings (because they care about truth rather than definedness). Operators such as C<++>, C<-->, C<+=>, C<-=>, and C<.=>, that operate on undefined variables such as: - undef $a; - $a++; + undef $x; + $x++; are also always exempt from such warnings. @@ -1036,7 +1036,7 @@ These examples of attempts to use an ellipsis are syntax errors: print ...; open(my $fh, ">", "/dev/passwd") or ...; if ($condition && ... ) { say "Howdy" }; - ... if $a > $b; + ... if $x > $y; say "Cromulent" if ...; $flub = 5 + ...; @@ -1087,11 +1087,11 @@ actually knows to look for pod escapes even in the middle of a paragraph. This means that the following secret stuff will be ignored by both the compiler and the translators. - $a=3; + $x=3; =secret stuff warn "Neither POD nor CODE!?" =cut back - print "got $a\n"; + print "got $x\n"; You probably shouldn't rely upon the C being podded out forever. Not all pod translators are well-behaved in this regard, and perhaps diff --git a/pod/perltie.pod b/pod/perltie.pod index 5e032aefeb37..4c75ac2bac14 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -782,7 +782,7 @@ to iterate through the hash, such as via a keys(), values(), or each() call. sub FIRSTKEY { carp &whowasi if $DEBUG; my $self = shift; - my $a = keys $self->{LIST}->%*; # reset each() iterator + my $x = keys $self->{LIST}->%*; # reset each() iterator each $self->{LIST}->%* } @@ -1047,8 +1047,8 @@ Here's how to use our little example: tie(*FOO,'Shout'); print FOO "hello\n"; - $a = 4; $b = 6; - print FOO $a, " plus ", $b, " equals ", $a + $b, "\n"; + $x = 4; $y = 6; + print FOO $x, " plus ", $y, " equals ", $x + $y, "\n"; print ; =head2 UNTIE this diff --git a/pod/perluniintro.pod b/pod/perluniintro.pod index 30f822f67bba..bbb743e5b1d3 100644 --- a/pod/perluniintro.pod +++ b/pod/perluniintro.pod @@ -733,12 +733,12 @@ are merged (double-quoted interpolation, explicit concatenation, or printf/sprintf parameter substitution), the result will be UTF-8 encoded as if copies of the byte strings were upgraded to UTF-8: for example, - $a = "ab\x80c"; - $b = "\x{100}"; - print "$a = $b\n"; + $x = "ab\x80c"; + $y = "\x{100}"; + print "$x = $y\n"; the output string will be UTF-8-encoded C, but -C<$a> will stay byte-encoded. +C<$x> will stay byte-encoded. Sometimes you might really need to know the byte length of a string instead of the character length. For that use the C pragma