Skip to content

Commit

Permalink
pod/perlfunc: stop recommending older syntax supported by 5.6.*
Browse files Browse the repository at this point in the history
Stop recommending the more verbose version syntax supported by 5.6.*,
as noted in the docs 5.8.0 is now old enough to drink in some parts of
the world, so we can switch this around to recommending the version
literals first, and then explaining in passing why someone might run
into the older syntax.

Furthermore, since most perl versions people encounter these days are
>=5.10, switch to 5.24.1 as an example for these versions.

While I'm at it, stop calling "use VERSION" the "peculiar" form, it
adds nothing, and just confuses the reader.
  • Loading branch information
Ævar Arnfjörð Bjarmason committed Dec 6, 2017
1 parent d106cb4 commit f1546a8
Showing 1 changed file with 25 additions and 24 deletions.
49 changes: 25 additions & 24 deletions pod/perlfunc.pod
Expand Up @@ -6358,23 +6358,24 @@ X<require>
Demands a version of Perl specified by VERSION, or demands some semantics
specified by EXPR or by L<C<$_>|perlvar/$_> if EXPR is not supplied.

VERSION may be either a numeric argument such as 5.006, which will be
compared to L<C<$]>|perlvar/$]>, or a literal of the form v5.6.1, which
will be compared to L<C<$^V>|perlvar/$^V> (or C<$PERL_VERSION> in
L<English>). An exception is raised if VERSION is greater than the
version of the current Perl interpreter. Compare with
VERSION may be either a literal such as v5.24.1, which will be
compared to L<C<$^V>|perlvar/$^V> (or C<$PERL_VERSION> in L<English>),
or a numeric argument of the form 5.024001, which will be compared to
L<C<$]>|perlvar/$]>. An exception is raised if VERSION is greater than
the version of the current Perl interpreter. Compare with
L<C<use>|/use Module VERSION LIST>, 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 that do not support this syntax. The equivalent numeric
version should be used instead.
Specifying VERSION as a numeric argument of the form 5.024001 should
generally be avoided as older less readable syntax compared to
v5.24.1. Before perl 5.8.0 released in 2002 the more verbose numeric
form was the only supported syntax, which is why you might see it in
older code.

require v5.6.1; # run time version check
require 5.6.1; # ditto
require 5.006_001; # ditto; preferred for backwards
compatibility
require v5.24.1; # run time version check
require 5.24.1; # ditto
require 5.024_001; # ditto; older syntax compatible
with perl 5.6

Otherwise, L<C<require>|/require VERSION> demands that a library file be
included if it hasn't already been included. The file is included via
Expand Down Expand Up @@ -9307,25 +9308,25 @@ package. It is exactly equivalent to
except that Module I<must> be a bareword.
The importation can be made conditional by using the L<if> module.

In the peculiar C<use VERSION> form, VERSION may be either a positive
decimal fraction such as 5.006, which will be compared to
L<C<$]>|perlvar/$]>, or a v-string of the form v5.6.1, which will be
compared to L<C<$^V>|perlvar/$^V> (aka $PERL_VERSION). An
In the C<use VERSION> form, VERSION may be either a v-string such as
v5.24.1, which will be compared to L<C<$^V>|perlvar/$^V> (aka
$PERL_VERSION), or a numeric argument of the form 5.024001, which will be
compared to L<C<$]>|perlvar/$]>. An
exception is raised 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<C<require>|/require VERSION>, which can do a
similar check at run time.
Symmetrically, C<no VERSION> allows you to specify that you want a version
of Perl older than the specified one.

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 (that is, prior to 5.6.0) that do not support this
syntax. The equivalent numeric version should be used instead.
Specifying VERSION as a numeric argument of the form 5.024001 should
generally be avoided as older less readable syntax compared to
v5.24.1. Before perl 5.8.0 released in 2002 the more verbose numeric
orm was the only supported syntax, which is why you might see it in

use v5.6.1; # compile time version check
use 5.6.1; # ditto
use 5.006_001; # ditto; preferred for backwards compatibility
use v5.24.1; # compile time version check
use 5.24.1; # ditto
use 5.024_001; # ditto; older syntax compatible with perl 5.6

This is often useful if you need to check the current Perl version before
L<C<use>|/use Module VERSION LIST>ing library modules that won't work
Expand Down

0 comments on commit f1546a8

Please sign in to comment.