perlvar.pod - add "Scoping Rules of Regex Variables" section

[demerphq]

This section is used to document the majority of the regex variables, and previous language referring to them as "dynamically scoped" has been changed or simplified and a link to the new section provided to centralize the explanation.

Strictly speaking $1 is globally scoped, but the data it access is dynamically scoped such that successful matches behave as though they localize a regex match state variable. (Maybe one day we will actually have such a variable exposed to the user.)

This patch addss links to the relevant docs in perlsyn and perlvar to various places where it seemed appropriate, and also cleans up the wording for most cases to be similar or identical across all uses. It also cleans up a bit of related language in nearby paragraphs where it seemed to improve the readability of the docs.

It also replaces the older kind of confusing example code for understanding the behavior and documents that "goto LABEL" does not play nicely with the dynamic scoping.

This fixes Github Issue #899.

[demerphq]

On Fri, 10 Feb 2023, 18:02 Dan Book, ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In pod/perlvar.pod <#20791 (comment)>: > Note there is a distinction between a capture buffer which matches the empty string a capture buffer which is optional. Eg, C<(x?)> and C<(x)?> The latter may be undef, the former not. -These variables are read-only and dynamically-scoped. The reason I think it's fine to refer to these variables as "dynamically-scoped" themselves is because all globals exist by being used, so their effective scope is just where they are usable. But it's not the variables themselves that cause the dynamic scoping of their values.

Check the discussion on the ticket. I'd say that "dynamically scoped" is an unsatisfactory description, although a least worst description in a pinch, campared to others, but i think a better description is warranted. The vars themselves are actually globals, and read only, so they can't be directly localized, and since they only change on successful match they don't really play the same way as a package variable would in the face of local. The closest would be something like local $1 = /.../ ? $1_new : $1; The other thing is that "dynamically scoped" is a bit ambiguous in that a package var is dynamically scoped, but the dynamic effects only kick in when the user explicitly uses local. Reading the ticket this caused confusion to others and I agree that linking through to a proper description is better than repeating an only somewhat correct description. Another point was that many of the vars had different descriptions etc, but they all have the same behaviour. (All that I changed anyway). Some of them said "block scoped", some of them mentioned eval and various edge cases etc. I think having them all references the same rules and avoid half correct terms is a better approach. Cheers Yves

[demerphq]

@khwilliamson I tweaked the verbiage a touch more, are you still ok with this?