[perl #78654] Proposed addition to perlop.pod re \Q and friends
Tom Wyant
# Please include the string: [perl #78654]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=78654 >
This is a bug report for perl from wy...@cpan.org,
generated with the help of perlbug 1.39 running under perl 5.12.2.
-----------------------------------------------------------------
[Please describe your issue here]
The perlop.pod documentation on \Q and friends is (at least to me)
obscure in the matter of when their action is applied. This resulted in
core non-bug 78292, in which I promised to try to clarify the docs.
The appended universal diff is my attempt at clarification. If accepted,
it is to be applied to the perlop.pod that shipped with Perl 5.12.2,
though of course I would hope that 5.13.x gets equivalent treatment.
The patch inserts a paragraph after the discussion of the effect of
locale on \l and friends, because that is the structure of the
corresponding part of perlre.pod, though it could be argued that the
paragraph should go right after the listing of the escape sequences
themselves.
Herewith my opus:
--- perlop.old 2010-09-06 19:30:32.000000000 -0400
+++ perlop.pod 2010-10-27 14:42:46.000000000 -0400
@@ -1060,6 +1060,11 @@
beyond) is being used, the case map used by C<\l>, C<\L>, C<\u> and
C<\U> is as defined by Unicode.
+The C<\l>, C<\u>, C<\L>, C<\U>, and C<\Q> escape sequences are applied
+B<after> interpolation takes place. For example, C<"\Q\t"> is equivalent
+to C<quotemeta "\t">, and produces a back slash followed by a tab
+character, not a back slash followed by the letter C<t>.
+
All systems use the virtual C<"\n"> to represent a line terminator,
called a "newline". There is no such thing as an unvarying, physical
newline character. It is only an illusion that the operating system,
[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
category=docs
severity=wishlist
---
Site configuration information for perl 5.12.2:
Configured by tom at Wed Sep 8 13:04:10 EDT 2010.
Summary of my perl5 (revision 5 version 12 subversion 2) configuration:
Platform:
osname=darwin, osvers=9.8.0, archname=darwin-2level
uname='darwin white2 9.8.0 darwin kernel version 9.8.0: wed jul 15 16:55:01 pdt 2009; root:xnu-1228.15.4~1release_i386 i386 '
config_args='-Dprefix=/usr/local/perl/5.12.2'
hint=recommended, useposix=true, d_sigaction=define
useithreads=undef, usemultiplicity=undef
useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
use64bitint=undef, use64bitall=undef, uselongdouble=undef
usemymalloc=n, bincompat5005=undef
Compiler:
cc='cc', ccflags ='-fno-common -DPERL_DARWIN -no-cpp-precomp -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include',
optimize='-O3',
cppflags='-no-cpp-precomp -fno-common -DPERL_DARWIN -no-cpp-precomp -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include'
ccversion='', gccversion='4.0.1 (Apple Inc. build 5484)', gccosandvers=''
intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
alignbytes=8, prototype=define
Linker and Libraries:
ld='env MACOSX_DEPLOYMENT_TARGET=10.3 cc', ldflags =' -fstack-protector -L/usr/local/lib'
libpth=/usr/local/lib /usr/lib
libs=-lgdbm -ldbm -ldl -lm -lutil -lc
perllibs=-ldl -lm -lutil -lc
libc=/usr/lib/libc.dylib, so=dylib, useshrplib=false, libperl=libperl.a
gnulibc_version=''
Dynamic Linking:
dlsrc=dl_dlopen.xs, dlext=bundle, d_dlsymun=undef, ccdlflags=' '
cccdlflags=' ', lddlflags=' -bundle -undefined dynamic_lookup -L/usr/local/lib -fstack-protector'
Locally applied patches:
---
@INC for perl 5.12.2:
/sw/lib/perl5
/sw/lib/perl5/darwin
/usr/local/perl/5.12.2/lib/site_perl/5.12.2/darwin-2level
/usr/local/perl/5.12.2/lib/site_perl/5.12.2
/usr/local/perl/5.12.2/lib/5.12.2/darwin-2level
/usr/local/perl/5.12.2/lib/5.12.2
.
---
Environment for perl 5.12.2:
DYLD_LIBRARY_PATH (unset)
HOME=/Users/tom
LANG=en_US.UTF-8
LANGUAGE (unset)
LD_LIBRARY_PATH (unset)
LOGDIR (unset)
PATH=/usr/local/perl/5.12.2/bin:/ImageMagick-6.4.1/bin:/sw/bin:/sw/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11/bin:/usr/X11R6/bin:/Users/tom/Code/Tools
PERL5LIB=/sw/lib/perl5:/sw/lib/perl5/darwin
PERLPKGOPT=-noppm
PERL_BADLANG (unset)
SHELL=/bin/bash
Ronald J Kimball
> --- perlop.old 2010-09-06 19:30:32.000000000 -0400
> +++ perlop.pod 2010-10-27 14:42:46.000000000 -0400
> @@ -1060,6 +1060,11 @@
> beyond) is being used, the case map used by C<\l>, C<\L>, C<\u> and
> C<\U> is as defined by Unicode.
>
> +The C<\l>, C<\u>, C<\L>, C<\U>, and C<\Q> escape sequences are applied
> +B<after> interpolation takes place. For example, C<"\Q\t"> is equivalent
> +to C<quotemeta "\t">, and produces a back slash followed by a tab
> +character, not a back slash followed by the letter C<t>.
> +
> All systems use the virtual C<"\n"> to represent a line terminator,
> called a "newline". There is no such thing as an unvarying, physical
> newline character. It is only an illusion that the operating system,
"backslash" should be a single word.
Ronald
harry...@comcast.net
In principle, I believe it can go either way. But in practice, I defer to the need for consistency in the Perl documentation.
Tom