pod and comments: Note escape vs quote #23264
Conversation
khwilliamson
force-pushed
the
escape
branch
2 times, most recently
from
ede7f9d to
8d8d490
Compare
pod/perlre.pod
Outdated
| Today it is more common to use the C<L<quotemeta()|perlfunc/quotemeta>> | ||
| (If C<use locale> is in effect, then this depends on the current locale.) | ||
|
|
||
| This template used to be a common paradigm, but these days it is more |
There was a problem hiding this comment.
It's not really the purpose of this PR, but I think it's a little misleading to say that quotemeta "disables metacharacters special meanings" without also saying that it actually does a very similar thing to the example just above, without being locale dependent for ASCII characters. i.e. it's exactly equivalent to s/([^A-Za-z_0-9])/\\$1/g or s/(\W)/\\$1/ag for ASCII characters (with behavior on non-ASCII characters dependent on the unicode_strings feature).
There was a problem hiding this comment.
With the additional very useful feature that it can be interpolated with \Q and \E rather than applied to the whole pattern.
There was a problem hiding this comment.
@Grinnz please check if new wording is ok
There was a problem hiding this comment.
I'm generally in favor of the changes presented in this p.r. But there is a lot in it, and I'd particularly like extra eyeballs on the changes in pod/perlre.pod.
pod/perlre.pod
Outdated
|
|
||
| quotemeta $pattern; | ||
|
|
||
| does either of these: |
There was a problem hiding this comment.
I'm not quite sure this is correct, it's not quite how the quotemeta docs describe it, but it sounds complex. In particular it says that ASCII characters are always subject to the ASCII style escaping regardless of unicode_strings or the utf8 flag. Maybe better to say it does similar things, give the basics, and link to the quotemeta docs for details.
This adds a bit of text about metacharacters that was missing from this introductory pod.
Fixes Perl#15221 The documentation and comments were misleading about conflating quoting a metacharacter and escaping it. Since \Q stands for quote, we have to continue to use that terminology. This commit clarifies that the two terms are often equivalent. This also adds detail about quotemeta and \Q.
By adding a word to a =heading, a sentence can be removed, and is clearer. But since some pod somewhere may link to that heading, a section at the end is added with the old name, and pointing to the new one. Dan Book searched and found no instances in CPAN of the old heading being linked to, but this guarantees that nothing breaks.
Fixes #15221
The documentation and comments was misleading about conflating quoting a metacharacter and escaping it. Since \Q stands for quote, we have to continue to use that terminology. This commit clarifies that the two terms are often equivalent.