diff options
Diffstat (limited to 'pod')
| -rw-r--r-- | pod/perldelta.pod | 108 | ||||
| -rw-r--r-- | pod/perlfunc.pod | 62 | ||||
| -rw-r--r-- | pod/perlhist.pod | 1 | ||||
| -rw-r--r-- | pod/perlipc.pod | 2 | ||||
| -rw-r--r-- | pod/perlop.pod | 23 | ||||
| -rw-r--r-- | pod/perlvar.pod | 24 | ||||
| -rw-r--r-- | pod/perlxs.pod | 19 |
7 files changed, 148 insertions, 91 deletions
diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 2bedcdb6c9..746c242288 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -57,6 +57,33 @@ cases remains unchanged: See L<perldata>. +=head2 Perl's version numbering has changed + +Beginning with Perl version 5.6, the version number convention has been +changed to a "dotted integer" scheme that is more commonly found in open +source projects. + +Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc. +The next development series following v5.6 will be numbered v5.7.x, +beginning with v5.7.0, and the next major production release following +v5.6 will be v5.8. + +The English module now sets $PERL_VERSION to $^V (a string value) rather +than C<$]> (a numeric value). (This is a potential incompatibility. +Send us a report via perlbug if you are affected by this.) + +The v1.2.3 syntax is also now legal in Perl. +See L<Support for strings represented as a vector of ordinals> for more on that. + +To cope with the new versioning system's use of at least three significant +digits for each version component, the method used for incrementing the +subversion number has also changed slightly. We assume that versions older +than v5.6 have been incrementing the subversion component in multiples of +10. Versions after v5.6.0 will increment them by 1. Thus, using the new +notation, 5.005_03 is the same as v5.5.30, and the first maintenance +version following v5.6.0 will be v5.6.1, which amounts to a floating point +value of 5.006_001). + =item Possibly changed pseudo-random number generator In 5.005_0x and earlier, perl's rand() function used the C library @@ -286,29 +313,6 @@ create new threads from Perl (i.e., C<use Thread;> will not work with interpreter threads). C<use Thread;> continues to be available when you ask for -Duse5005threads, bugs and all. -=head2 Perl's version numbering has changed - -Beginning with Perl version 5.6, the version number convention has been -changed to a "dotted tuple" scheme that is more commonly found in open -source projects. - -Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc. -The next development series following v5.6 will be numbered v5.7.x, -beginning with v5.7.0, and the next major production release following -v5.6 will be v5.8. - -The v1.2.3 syntax is also now legal in Perl. See L<Support for version tuples> -for more on that. - -To cope with the new versioning system's use of at least three significant -digits for each version component, the method used for incrementing the -subversion number has also changed slightly. We assume that versions older -than v5.6 have been incrementing the subversion component in multiples of -10. Versions after v5.6 will increment them by 1. Thus, using the new -notation, 5.005_03 is the same as v5.5.30, and the first maintenance -version following v5.6 will be v5.6.1, which amounts to a floating point -value of 5.006_001). - =head2 New Configure flags The following new flags may be enabled on the Configure command line @@ -455,36 +459,42 @@ mostly useful as an alternative to the C<vars> pragma, but also provides the opportunity to introduce typing and other attributes for such variables. See L<perlfunc/our>. -=head2 Support for version tuples +=head2 Support for strings represented as a vector of ordinals -Literals of the form v1.2.3.4 are now parsed as the utf8 string -C<"\x{1}\x{2}\x{3}\x{4}">. This allows comparing version numbers using -regular string comparison operators C<eq>, C<ne>, C<lt>, C<gt> etc. +Literals of the form v1.2.3.4 are now parsed as a string comprised of +of characters with the specified ordinals. This is an alternative, more +readable way to construct (possibly unicode) strings instead of +interpolating characters, as in C<"\x{1}\x{2}\x{3}\x{4}">. -These "dotted tuples" are dual-valued. They are both strings of utf8 -characters, and floating point numbers. Thus v1.2.3.4 has the string -value C<"\x{1}\x{2}\x{3}\x{4}"> and the numeric value 1.002_003_004. -As another example, v5.5.640 has the string value C<"\x{5}\x{5}\x{280}"> -(remember 280 hexadecimal is 640 decimal) and the numeric value -5.005_64. +Strings written in this form are also useful to represent version "numbers". +It is easy to compare such version "numbers" (which are really just plain +strings) using any of the usual string comparison operators C<eq>, C<ne>, +C<lt>, C<gt>, etc., or perform bitwise string operations on them using C<|>, +C<&>, etc. In conjunction with the new C<$^V> magic variable (which contains -the perl version in this format), such literals can be used to -check if you're running a particular version of Perl. +the perl version as a string), such literals can be used as a readable way +to check if you're running a particular version of Perl: + # this will parse in older versions of Perl also if ($^V and $^V gt v5.5.640) { - # new style version numbers are supported + # new features supported } -C<require> and C<use> also support such literals: +C<require> and C<use> also have some special magic to support such literals. +They will be interpreted as a version rather than as a module name: + + require v5.6.0; # croak if $^V lt v5.6.0 + use v5.6.0; # same, but croaks at compile-time - require v5.6.0; # croak if $^V lt v5.6.0 - use v5.6.0; # same, but croaks at compile-time +Also, C<sprintf> and C<printf> support the Perl-specific format flag C<%v> +to print ordinals of characters in arbitrary strings: -C<sprintf> and C<printf> support the Perl-specific format type C<%v> -to print arbitrary strings as dotted tuples. + printf "v%vd", $^V; # prints current version, such as "v5.5.650" + printf "%*vX", ":", $addr; # formats IPv6 address + printf "%*vb", "", $bits; # displays bitstring as contiguous 0's and 1's - printf "v%v", $^V; # prints current version, such as "v5.5.650" +See L<perlop/"Strings of Character"> for additional information. =head2 Weak references @@ -851,9 +861,12 @@ only during normal running are warranted. See L<perlvar>. =head2 New variable $^V contains Perl version in v5.6.0 format -C<$^V> contains the Perl version number as a version tuple that -can be used in string or numeric comparisons. See -C<Support for version tuples> for an example. +C<$^V> contains the Perl version number as a string comprised of +characters whose ordinals match the version numbers, so that it may +be used in string comparisons. + +See C<Support for strings represented as a vector of ordinals> for an +example. =head2 Optional Y2K warnings @@ -1388,6 +1401,11 @@ For other details, see L<Benchmark>. The Devel::Peek module provides access to the internal representation of Perl variables and data. It is a data debugging tool for the XS programmer. +=item English + +$PERL_VERSION now stands for C<$^V> (a string value) rather than for C<$]> +(a numeric value). + =item ExtUtils::MakeMaker change#4135, also needs docs in module pod diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index e11364d509..f4cee09073 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -3549,9 +3549,17 @@ rename(2) manpage or equivalent system documentation for details. =item require Demands some semantics specified by EXPR, or by C<$_> if EXPR is not -supplied. If a version number or tuple is specified, or if EXPR is -numeric, demands that the current version of Perl -(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR. +supplied. + +If a VERSION is specified as a literal of the form v5.6.0, +demands that the current version of Perl (C<$^V> or $PERL_VERSION) be +at least as recent as that version, at run time. (For compatibility +with older versions of Perl, a numeric argument will also be interpreted +as VERSION.) Compare with L</use>, which can do a similar check at +compile time. + + require v5.6.0; # run time version check + require 5.005_03; # same, number still supported for compatibility Otherwise, demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is @@ -4337,10 +4345,6 @@ In addition, Perl permits the following widely-supported conversions: %n special: *stores* the number of characters output so far into the next variable in the parameter list -And the following Perl-specific conversion: - - %v a string, output as a tuple of integers ("Perl" is 80.101.114.108) - Finally, for backward (and we do mean "backward") compatibility, Perl permits these unnecessary but widely-supported conversions: @@ -4366,9 +4370,13 @@ and the conversion letter: h interpret integer as C type "short" or "unsigned short" If no flags, interpret integer as C type "int" or "unsigned" -There is also one Perl-specific flag: +There are also two Perl-specific flags: V interpret integer as Perl's standard integer type + v interpret string as a vector of integers, output as + numbers separated either by dots, or by an arbitrary + string received from the argument list when the flag + is preceded by C<*> Where a number would appear in the flags, an asterisk (C<*>) may be used instead, in which case Perl uses the next item in the parameter @@ -4376,6 +4384,13 @@ list as the given number (that is, as the field width or precision). If a field width obtained through C<*> is negative, it has the same effect as the C<-> flag: left-justification. +The C<v> flag is useful for displaying ordinal values of characters +in arbitrary strings: + + printf "version is v%vd\n", $^V; # Perl's version + printf "address is %*vX\n", ":", $addr; # IPv6 address + printf "bits are %*vb\n", "", $bits; # random bitstring + If C<use locale> is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See L<perllocale>. @@ -5222,12 +5237,14 @@ Note the LIST is prepended whole, not one element at a time, so the prepended elements stay in the same order. Use C<reverse> to do the reverse. +=item use Module VERSION LIST + +=item use Module VERSION + =item use Module LIST =item use Module -=item use Module VERSION LIST - =item use VERSION Imports some semantics into the current package from the named module, @@ -5238,13 +5255,17 @@ package. It is exactly equivalent to except that Module I<must> be a bareword. -If the first argument to C<use> is a number or a version tuple, it is -treated as a version instead of a module name. If the version -of the Perl interpreter is less than VERSION, then an error message -is printed and Perl exits immediately. +VERSION, which can be specified as a literal of the form v5.6.0, demands +that the current version of Perl (C<$^V> or $PERL_VERSION) be at least +as recent as that version. (For compatibility with older versions of Perl, +a numeric literal will also be interpreted as VERSION.) If the version +of the running Perl interpreter is less than VERSION, then an error +message is printed and Perl exits immediately without attempting to +parse the rest of the file. Compare with L</require>, which can do a +similar check at run time. - use 5.005_03; # version number - use v5.6.0; # version tuple + use v5.6.0; # compile time version check + use 5.005_03; # same, number still supported for compatibility This is often useful if you need to check the current Perl version before C<use>ing library modules that have changed in incompatible ways from @@ -5271,9 +5292,12 @@ That is exactly equivalent to If the VERSION argument is present between Module and LIST, then the C<use> will call the VERSION method in class Module with the given version as an argument. The default VERSION method, inherited from -the Universal class, croaks if the given version is larger than the -value of the variable C<$Module::VERSION>. (Note that there is not a -comma after VERSION!) +the UNIVERSAL class, croaks if the given version is larger than the +value of the variable C<$Module::VERSION>. + +Again, there is a distinction between omitting LIST (C<import> called +with no arguments) and an explicit empty LIST C<()> (C<import> not +called). Note that there is no comma after VERSION! Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are: diff --git a/pod/perlhist.pod b/pod/perlhist.pod index 7a8d1e5879..0e1df8abd3 100644 --- a/pod/perlhist.pod +++ b/pod/perlhist.pod @@ -334,6 +334,7 @@ the strings?). 5.005_63 1999-Dec-09 5.5.640 2000-Feb-02 5.5.650 2000-Feb-08 5.6 beta1 + 5.5.660 2000-Feb-22 5.6 beta2 =head2 SELECTED RELEASE SIZES diff --git a/pod/perlipc.pod b/pod/perlipc.pod index 3034197e14..3649e4f883 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -126,7 +126,7 @@ or even the more elaborate: use POSIX ":sys_wait_h"; sub REAPER { my $child; - while ($child = waitpid(-1,WNOHANG)) { + while (($child = waitpid(-1,WNOHANG)) > 0) { $Kid_Status{$child} = $?; } $SIG{CHLD} = \&REAPER; # still loathe sysV diff --git a/pod/perlop.pod b/pod/perlop.pod index d932704666..15124125a3 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -1802,17 +1802,18 @@ operation you intend by using C<""> or C<0+>, as in the examples below. See L<perlfunc/vec> for information on how to manipulate individual bits in a bit vector. -=head2 Version tuples - -A literal of the form C<v1.20.300.4000> is parsed as a dual-valued quantity. -It has the string value of C<"\x{1}\x{14}\x{12c}\x{fa0}"> (i.e., a UTF-8 -string) and a numeric value of C<1 + 20/1000 + 300/1000000 + 4000/1000000000>. -This is useful for representing Unicode strings, and for comparing version -numbers using the string comparison operators, C<cmp>, C<gt>, C<lt> etc. - -Such "version tuples" or "vectors" are accepted by both C<require> and -C<use>. The C<$^V> variable contains the running Perl interpreter's -version in this format. See L<perlvar/$^V>. +=head2 Strings of Character + +A literal of the form C<v1.20.300.4000> is parsed as a string comprised +of characters with the specified ordinals. This 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. + +Such literals are accepted by both C<require> and C<use> for doing a version +check. The C<$^V> special variable also contains the running Perl +interpreter's version in this form. See L<perlvar/$^V>. =head2 Integer Arithmetic diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 285a0d5863..947942c003 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -699,8 +699,6 @@ As of release 5 of Perl, assignment to C<$[> is treated as a compiler directive, and cannot influence the behavior of any other file. Its use is highly discouraged. -=item $PERL_VERSION - =item $] The version + patchlevel / 1000 of the Perl interpreter. This variable @@ -713,7 +711,10 @@ of perl in the right bracket?) Example: See also the documentation of C<use VERSION> and C<require VERSION> for a convenient way to fail if the running Perl interpreter is too old. -See C<$^V> for a more modern representation of the Perl version. +The use of this variable is deprecated. The floating point representation +can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a +more modern representation of the Perl version that allows accurate string +comparisons. =item $COMPILING @@ -905,24 +906,23 @@ The time at which the program began running, in seconds since the epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, and B<-C> filetests are based on this value. -=item $PERL_VERSION_TUPLE +=item $PERL_VERSION =item $^V The revision, version, and subversion of the Perl interpreter, represented -as a "version tuple". Version tuples have both a numeric value and a -string value. The numeric value is a floating point number that amounts -to revision + version/1000 + subversion/1000000, and the string value -is made of characters possibly in the UTF-8 range: -C<chr($revision) . chr($version) . chr($subversion)>. +as a string comprised 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. 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: +Control.) Example: - warn "No "our" declarations!\n" if $^V and $^V lt v5.6; + warn "No "our" declarations!\n" if $^V and $^V lt v5.6.0; -See also the documentation of C<use VERSION> and C<require VERSION> +See the documentation of C<use VERSION> and C<require VERSION> for a convenient way to fail if the running Perl interpreter is too old. See also C<$]> for an older representation of the Perl version. diff --git a/pod/perlxs.pod b/pod/perlxs.pod index a2755b8f2d..7359d34818 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -502,9 +502,9 @@ C<ST(1)>. =head2 Default Parameter Values -Default values for XSUB arguments can be specified by -placing an assignment statement in the parameter list. The -default value may be a number or a string. Defaults should +Default values for XSUB arguments can be specified by placing an +assignment statement in the parameter list. The default value may +be a number, a string or the special string C<NO_INIT>. Defaults should always be used on the right-most parameters only. To allow the XSUB for rpcb_gettime() to have a default host @@ -1314,6 +1314,19 @@ methods will be called as this: THIS->set_blue( val ); +You could also write a single get/set method using an optional argument: + + int + color::blue( val = NO_INIT ) + int val + PROTOTYPE $;$ + CODE: + if (items > 1) + THIS->set_blue( val ); + RETVAL = THIS->blue(); + OUTPUT: + RETVAL + If the function's name is B<DESTROY> then the C++ C<delete> function will be called and C<THIS> will be given as its parameter. The generated C++ code for |