From 4a904372e4d28940f0bcc3b8501925d58b3f0e68 Mon Sep 17 00:00:00 2001 From: Father Chrysostomos Date: Fri, 17 Jun 2011 13:29:04 -0700 Subject: [PATCH] Doc update for changes in 5.15.0 + tweaks --- lib/CORE.pod | 5 ++++- lib/feature.pm | 4 +++- pod/perlfunc.pod | 33 ++++++++++++++++++++++----------- pod/perlsub.pod | 18 +++++++----------- pod/perlsyn.pod | 4 +++- pod/perltie.pod | 9 ++++----- pod/perlvar.pod | 5 +++-- 7 files changed, 46 insertions(+), 32 deletions(-) diff --git a/lib/CORE.pod b/lib/CORE.pod index c917bba..b96c1de 100644 --- a/lib/CORE.pod +++ b/lib/CORE.pod @@ -10,11 +10,14 @@ CORE - Pseudo-namespace for Perl's core routines print hex("0x50"),"\n"; # prints 1 print CORE::hex("0x50"),"\n"; # prints 80 + CORE::say "yes"; # prints yes =head1 DESCRIPTION The C namespace gives access to the original built-in functions of -Perl. There is no C package, and therefore you do not need to use or +Perl. It also provides access to keywords normally available +only through the L pragma. There is no C +package, and therefore you do not need to use or require an hypothetical "CORE" module prior to accessing routines in this namespace. diff --git a/lib/feature.pm b/lib/feature.pm index c322440..2ee1018 100644 --- a/lib/feature.pm +++ b/lib/feature.pm @@ -55,7 +55,9 @@ It is usually impossible to add new syntax to Perl without breaking some existing programs. This pragma provides a way to minimize that risk. New syntactic constructs, or new semantic meanings to older constructs, can be enabled by C, and will be parsed -only when the appropriate feature pragma is in scope. +only when the appropriate feature pragma is in scope. (Nevertheless, the +C prefix provides access to all Perl keywords, regardless of this +pragma.) =head2 Lexical effect diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 40c1f8a..46f71d1 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -166,17 +166,21 @@ C, C, C, C, C, C, C =item Keywords related to the switch feature -C, C, CC, C +C, C, C, C, C -These are available only if you enable the C<"switch"> feature. +Except for C, these are available only if you enable the +C<"switch"> feature or use the C prefix. See L and L. -Alternately, include a C or later to the current scope. +Alternately, include a C or later to the current scope. In Perl +5.14 and earlier, C required the C<"switch"> feature, like the +other keywords. =item Keywords related to scoping C, C, C, C, C, C, C, C -C is available only if the C<"state"> feature is enabled. See +C is available only if the C<"state"> feature +is enabled or if it is prefixed with C. See L. Alternately, include a C or later to the current scope. =item Miscellaneous functions @@ -646,7 +650,8 @@ See L. Break out of a C block. This keyword is enabled by the C<"switch"> feature: see -L for more information. Alternately, include a C for more information. You can also access it by +prefixing it with C. Alternately, include a C or later to the current scope. =item caller EXPR @@ -978,7 +983,8 @@ X =item continue -C is actually a flow control statement rather than a function. If +When followed by a BLOCK, C is actually a +flow control statement rather than a function. If there is a C BLOCK attached to a BLOCK (typically in a C or C), it is always executed just before the conditional is about to be evaluated again, just like the third part of a C loop in C. Thus @@ -1005,9 +1011,11 @@ Omitting the C section is equivalent to using an empty one, logically enough, so C goes directly back to check the condition at the top of the loop. -If the C<"switch"> feature is enabled, C is also a function that +When there is no BLOCK, C is a function that falls through the current C or C block instead of iterating a dynamically enclosing C or exiting a lexically enclosing C. +In Perl 5.14 and earlier, this form of C was +only available when the C<"switch"> feature was enabled. See L and L for more information. @@ -1163,7 +1171,8 @@ Portability issues: L. Within a C or a C, a C BLOCK acts like a C that's always true. Only available after Perl 5.10, and only if the -C feature has been requested. See L. +C feature has been requested or if the keyword is prefixed with +C. See L. =item defined EXPR X X X @@ -5340,7 +5349,8 @@ simply an abbreviation for C<{ local $\ = "\n"; print LIST }>. To use FILEHANDLE without a LIST to print the contents of C<$_> to it, you must use a real filehandle like C, not an indirect one like C<$fh>. -This keyword is available only when the C<"say"> feature is enabled; see +This keyword is available only when the C<"say"> feature +is enabled, or when prefixed with C; see L. Alternately, include a C or later to the current scope. @@ -6722,13 +6732,14 @@ X =item state TYPE EXPR : ATTRS -C declares a lexically scoped variable, just like C does. +C declares a lexically scoped variable, just like C. However, those variables will never be reinitialized, contrary to lexical variables that are reinitialized each time their enclosing block is entered. C variables are enabled only when the C pragma -is in effect. See L. +is in effect, unless the keyword is written as C. +See L. =item study SCALAR X diff --git a/pod/perlsub.pod b/pod/perlsub.pod index db398dd..01c525d 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -439,10 +439,12 @@ if you want to stay compatible with releases older than 5.10. =head3 Persistent variables via state() -Beginning with perl 5.9.4, you can declare variables with the C -keyword in place of C. For that to work, though, you must have +Beginning with Perl 5.9.4, you can declare variables with the C +keyword in place of C. For that to work, though, you must have enabled that feature beforehand, either by using the C pragma, or -by using C<-E> on one-liners. (see L) +by using C<-E> on one-liners (see L). Beginning with Perl 5.16, +you can also write it as C, which does not require the +C pragma. For example, the following code maintains a private counter, incremented each time the gimme_another() function is called: @@ -740,8 +742,7 @@ To do this, you have to declare the subroutine to return an lvalue. my $val; sub canmod : lvalue { - # return $val; this doesn't work, don't say "return" - $val; + $val; # or: return $val; } sub nomod { $val; @@ -770,14 +771,9 @@ all the subroutines are called in a list context. =item Lvalue subroutines are EXPERIMENTAL -They appear to be convenient, but there are several reasons to be +They appear to be convenient, but there is at least one reason to be circumspect. -You can't use the return keyword, you must pass out the value before -falling out of subroutine scope. (see comment in example above). This -is usually not a problem, but it disallows an explicit return out of a -deeply nested loop, which is sometimes a nice way out. - They violate encapsulation. A normal mutator can check the supplied argument before setting the attribute it is protecting, an lvalue subroutine never gets that chance. Consider; diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index a88fb03..a914f85 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -530,7 +530,9 @@ Starting from Perl 5.10, you can say use feature "switch"; which enables a switch feature that is closely based on the -Perl 6 proposal. +Perl 6 proposal. Starting from Perl 5.16, one can prefix the switch +keywords with C to access the feature without a C +statement. The keywords C and C are analogous to C and C in other languages, so the code diff --git a/pod/perltie.pod b/pod/perltie.pod index 456cc60..887f2f0 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -870,11 +870,10 @@ program, where output to STDOUT and STDERR may have to be redirected in some special way. See nvi and the Apache module for examples. When tying a handle, the first argument to C should begin with an -asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have assigned -it to a scalar variable, say C<$handle>, use C<*$handle>. C -works, too, but that is considered a bug and will be fixed in Perl 5.16. It -is supposed to tie the scalar C<$handle>, not the handle inside it. -C emits a deprecation warning as of Perl 5.14. +asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have +assigned it to a scalar variable, say C<$handle>, use C<*$handle>. +C ties the scalar variable C<$handle>, not the handle inside +it. In our example we're going to create a shouting handle. diff --git a/pod/perlvar.pod b/pod/perlvar.pod index ccc4196..890909d 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -185,8 +185,9 @@ Mnemonic: works in double-quoted context. =item $$ X<$$> X<$PID> X<$PROCESS_ID> -The process number of the Perl running this script. You should -consider this variable read-only, although it will be altered +The process number of the Perl running this script. Though you I set +this variable, doing so is generally discouraged, although it can be +invaluable for some testing purposes. It will be reset automatically across C calls. Note for Linux users: on Linux, the C functions C and -- 2.7.4