Change 20518 by [EMAIL PROTECTED] on 2003/08/06 11:26:56
Rework the version strings/objects documentation.
Affected files ...
... //depot/maint-5.8/perl/pod/perldata.pod#13 edit
... //depot/maint-5.8/perl/pod/perlfunc.pod#34 edit
... //depot/maint-5.8/perl/pod/perlvar.pod#25 edit
Differences ...
==== //depot/maint-5.8/perl/pod/perldata.pod#13 (text) ====
Index: perl/pod/perldata.pod
--- perl/pod/perldata.pod#12~20516~ Wed Aug 6 03:47:28 2003
+++ perl/pod/perldata.pod Wed Aug 6 04:26:56 2003
@@ -344,32 +344,50 @@
benefits of v-strings were greatly outweighed by the potential for
Surprise and Confusion.
-A literal of the form C<v1.20.300.4000> is parsed as a string composed
-of characters with the specified ordinals. This form, known as
-v-strings, provides an alternative, more readable way to construct
-strings, rather than use the somewhat less readable interpolation form
-C<"\x{1}\x{14}\x{12c}\x{fa0}">. This is useful for representing
-Unicode strings, and for comparing version "numbers" using the string
-comparison operators, C<cmp>, C<gt>, C<lt> etc. If there are two or
-more dots in the literal, the leading C<v> may be omitted.
+The rest of this section describes v-strings as they were between and
+including Perls 5.6.0 and 5.8.0. It is retained here for maintenance
+purposes. Note that the equivalence of strings and v-strings is
+especially deprecated. For example, version objects will stringify
+as "5.6.0", not as "\5\6\0". See L</"Version Objects">.
+
+[OBSOLETE] A literal of the form C<v1.20.300.4000> is parsed as a
+string composed of characters with the specified ordinals. This form,
+known as v-strings, provides an alternative, more readable way to
+construct strings, rather than use the somewhat less readable
+interpolation form C<"\x{1}\x{14}\x{12c}\x{fa0}">. This is useful for
+representing Unicode strings, and for comparing version "numbers"
+using the string comparison operators, C<cmp>, C<gt>, C<lt> etc. If
+there are two or more dots in the literal, the leading C<v> may be
+omitted.
print v9786; # prints UTF-8 encoded SMILEY, "\x{263a}"
print v102.111.111; # prints "foo"
print 102.111.111; # same
-Such literals are accepted by both C<require> and C<use> for
-doing a version check. The C<$^V> special variable also contains the
+[OBSOLETE] Note that using the v-strings for IPv4 addresses is not
+portable unless you also use the inet_aton()/inet_ntoa() routines of
+the Socket package.
+
+=head3 Version Objects
+
+The most important intended use of v-strings (see L/"Version Strings">)
+will live on as "version objects". Version objects can be used to
+request a minimum acceptable version of either Perl itself or of a
+module. The literals of the form I<number.number.number ...> used in
+C<use> and C<require>, for example
+
+ use 5.6.0;
+ require 5.8.1;
+ use Module 1.2.3;
+
+are version ojects. The C<$^V> special variable also contains the
running Perl interpreter's version in this form. See L<perlvar/$^V>.
-Note that using the v-strings for IPv4 addresses is not portable unless
-you also use the inet_aton()/inet_ntoa() routines of the Socket package.
Note that since Perl 5.8.1 the single-number v-strings (like C<v65>)
are not v-strings before the C<< => >> operator (which is usually used
to separate a hash key from a hash value), instead they are interpreted
as literal strings ('v65'). They were v-strings from Perl 5.6.0 to
Perl 5.8.0, but that caused more confusion and breakage than good.
-Multi-number v-strings like C<v65.66> and C<65.66.67> continue to
-be v-strings always.
=head3 Special Literals
==== //depot/maint-5.8/perl/pod/perlfunc.pod#34 (text) ====
Index: perl/pod/perlfunc.pod
--- perl/pod/perlfunc.pod#33~20516~ Wed Aug 6 03:47:28 2003
+++ perl/pod/perlfunc.pod Wed Aug 6 04:26:56 2003
@@ -4017,18 +4017,18 @@
specified by EXPR or by C<$_> if EXPR is not supplied.
VERSION may be either a numeric argument such as 5.006, which will be
-compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+compared to C<$]>, or a literal of the form 5.6.1, which will be compared
to C<$^V> (aka $PERL_VERSION). A fatal error is produced at run time if
VERSION is greater than the version of the current Perl interpreter.
Compare with L</use>, which can do a similar check at compile time.
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl which do not support this syntax. The equivalent numeric
-version should be used instead.
+Specifying VERSION as a literal of the form 5.6.1 is bad for backwards
+compatibility, because it leads to misleading error messages under
+earlier versions of Perl which do not support this syntax.
+The equivalent numeric version should be used instead if compatibility
+with Perl versions lower than 5.6.0 is required.
- require v5.6.1; # run time version check
- require 5.6.1; # ditto
+ require 5.6.1; # run time version check
require 5.006_001; # ditto; preferred for backwards compatibility
Otherwise, demands that a library file be included if it hasn't already
@@ -6132,19 +6132,19 @@
except that Module I<must> be a bareword.
VERSION may be either a numeric argument such as 5.006, which will be
-compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+compared to C<$]>, or a literal of the form 5.6.1, which will be compared
to C<$^V> (aka $PERL_VERSION. A fatal error is produced if VERSION is
greater than the version of the current Perl interpreter; Perl will not
attempt to parse the rest of the file. Compare with L</require>, which can
do a similar check at run time.
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl which do not support this syntax. The equivalent numeric
-version should be used instead.
+Specifying VERSION as a literal of the form 5.6.1 is bad for backwards
+compatibility, because it leads to misleading error messages under
+earlier versions of Perl which do not support this syntax.
+The equivalent numeric version should be used instead if compatibility
+with Perl versions lower than 5.6.0 is required.
- use v5.6.1; # compile time version check
- use 5.6.1; # ditto
+ use 5.6.1; # compile time version check
use 5.006_001; # ditto; preferred for backwards compatibility
This is often useful if you need to check the current Perl version before
==== //depot/maint-5.8/perl/pod/perlvar.pod#25 (text) ====
Index: perl/pod/perlvar.pod
--- perl/pod/perlvar.pod#24~20516~ Wed Aug 6 03:47:28 2003
+++ perl/pod/perlvar.pod Wed Aug 6 04:26:56 2003
@@ -1158,17 +1158,15 @@
=item $^V
-The revision, version, and subversion of the Perl interpreter, represented
-as a string composed of characters with those ordinals. Thus in Perl v5.6.0
-it equals C<chr(5) . chr(6) . chr(0)> and will return true for
-C<$^V eq v5.6.0>. Note that the characters in this string value can
-potentially be in Unicode range.
+The revision, version, and subversion of the Perl interpreter,
+represented as a version object (see L<perldata/"Version Objects").
+For example in Perl v5.6.0 C<$^V eq 5.6.0> will return true.
This can be used to determine whether the Perl interpreter executing a
script is in the right range of versions. (Mnemonic: use ^V for Version
Control.) Example:
- warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
+ warn "No \"our\" declarations!\n" if $^V and $^V lt 5.6.0;
To convert C<$^V> into its string representation use sprintf()'s
C<"%vd"> conversion:
End of Patch.
