X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlvar.pod;h=6e62a10689203f796e8abcf4b8b67beef2e219a4;hb=7ba193690277b4a41f1778d1f2dae795f7da82c7;hp=fc738a090350adc686c4ac42d6984e288a53e81c;hpb=87e95b7ff3268cc4f947098ed09d244372b3af0d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlvar.pod b/pod/perlvar.pod index fc738a0..6e62a10 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -58,14 +58,14 @@ the change may affect other modules which rely on the default values of the special variables that you have changed. This is one of the correct ways to read the whole file at once: - open my $fh, "foo" or die $!; + open my $fh, "<", "foo" or die $!; local $/; # enable localized slurp mode my $content = <$fh>; close $fh; But the following code is quite bad: - open my $fh, "foo" or die $!; + open my $fh, "<", "foo" or die $!; undef $/; # enable slurp mode my $content = <$fh>; close $fh; @@ -81,7 +81,7 @@ inside some short C<{}> block, you should create one yourself. For example: my $content = ''; - open my $fh, "foo" or die $!; + open my $fh, "<", "foo" or die $!; { local $/; $content = <$fh>; @@ -148,18 +148,24 @@ don't use it: =item * -Various unary functions, including functions like ord() and int(), as well -as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to -STDIN. +The following functions: + +abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob, +hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, +quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only), +rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst, +unlink, unpack. =item * -Various list functions like print() and unlink(). +All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN. +See L + =item * -The pattern matching operations C, C, and C when used -without an C<=~> operator. +The pattern matching operations C, C and C (aka C) +when used without an C<=~> operator. =item * @@ -172,6 +178,10 @@ The implicit iterator variable in the grep() and map() functions. =item * +The implicit variable of given(). + +=item * + The default place to put an input record when a C<< >> operation's result is tested by itself as the sole criterion of a C test. Outside a C test, this will not happen. @@ -181,7 +191,7 @@ test. Outside a C test, this will not happen. As C<$_> is a global variable, this may lead in some cases to unwanted side-effects. As of perl 5.9.1, you can now use a lexical version of C<$_> by declaring it in a file or in a block with C. Moreover, -declaring C restores the global C<$_> in the current scope. +declaring C restores the global C<$_> in the current scope. (Mnemonic: underline is understood in certain operations.) @@ -302,6 +312,8 @@ matched. For example: (Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. +=item $LAST_SUBMATCH_RESULT + =item $^N X<$^N> @@ -344,17 +356,20 @@ Similar to C<@+>, the C<%+> hash allows access to the named capture buffers, should they exist, in the last successful match in the currently active dynamic scope. -C<$+{foo}> is equivalent to C<$1> after the following match: +For example, C<$+{foo}> is equivalent to C<$1> after the following match: - 'foo'=~/(?foo)/; + 'foo' =~ /(?foo)/; -The underlying behaviour of %+ is provided by the L -module. +The keys of the C<%+> hash list only the names of buffers that have +captured (and that are thus associated to defined values). -B As C<%-> and C<%+> are tied views into a common internal hash +The underlying behaviour of C<%+> is provided by the +L module. + +B C<%-> and C<%+> are tied views into a common internal hash associated with the last successful regular expression. Therefore mixing iterative access to them via C may have unpredictable results. -Likewise, if the last successful match changes then the results may be +Likewise, if the last successful match changes, then the results may be surprising. =item HANDLE->input_line_number(EXPR) @@ -428,7 +443,7 @@ instead of lines, with the maximum record size being the referenced integer. So this: local $/ = \32768; # or \"32768", or \$var_containing_32768 - open my $fh, $myfile or die $!; + open my $fh, "<", $myfile or die $!; local $_ = <$fh>; will read a record of no more than 32768 bytes from FILE. If you're @@ -464,7 +479,8 @@ buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe or socket, such as when you are running a Perl program under B and want to see the output as it's happening. This has no effect on input buffering. See L -for that. (Mnemonic: when you want your pipes to be piping hot.) +for that. See L on how to select the output channel. +See also L. (Mnemonic: when you want your pipes to be piping hot.) =item IO::Handle->output_field_separator EXPR @@ -615,16 +631,20 @@ After a match against some variable $var: =item %- X<%-> -Similar to %+, this variable allows access to the named capture -buffers that were defined in the last successful match. It returns -a reference to an array containing one value per buffer of a given -name in the pattern. +Similar to C<%+>, this variable allows access to the named capture buffers +in the last successful match in the currently active dynamic scope. To +each capture buffer name found in the regular expression, it associates a +reference to an array containing the list of values captured by all +buffers with that name (should there be several of them), in the order +where they appear. + +Here's an example: - if ('1234'=~/(?1)(?2)(?3)(?4)/) { - foreach my $name (sort keys(%-)) { - my $ary = $-{$name}; + if ('1234' =~ /(?1)(?2)(?3)(?4)/) { + foreach my $bufname (sort keys %-) { + my $ary = $-{$bufname}; foreach my $idx (0..$#$ary) { - print "\$-{$name}[$idx] : ", + print "\$-{$bufname}[$idx] : ", (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"), "\n"; } @@ -638,12 +658,16 @@ would print out: $-{B}[0] : '2' $-{B}[1] : '4' -The behaviour of %- is implemented via the L module. +The keys of the C<%-> hash correspond to all buffer names found in +the regular expression. + +The behaviour of C<%-> is implemented via the +L module. -Note that C<%-> and C<%+> are tied views into a common internal hash +B C<%-> and C<%+> are tied views into a common internal hash associated with the last successful regular expression. Therefore mixing iterative access to them via C may have unpredictable results. -Likewise, if the last successful match changes then the results may be +Likewise, if the last successful match changes, then the results may be surprising. =item HANDLE->format_name(EXPR) @@ -753,8 +777,7 @@ X<$^ENCODING> The I to the Encode object that is used to convert the source code to Unicode. Thanks to this variable your perl script does not have to be written in UTF-8. Default is I. The direct -manipulation of this variable is highly discouraged. See L -for more details. +manipulation of this variable is highly discouraged. =item $OS_ERROR @@ -768,7 +791,7 @@ variable, or in other words, if a system or library call fails, it sets this variable. This means that the value of C<$!> is meaningful only I after a B: - if (open(FH, $filename)) { + if (open my $fh, "<", $filename) { # Here $! is meaningless. ... } else { @@ -791,6 +814,10 @@ went bang?) Also see L. +=item %OS_ERROR + +=item %ERRNO + =item %! X<%!> @@ -915,7 +942,9 @@ the same as the first number. However, a value assigned to C<$(> must be a single number used to set the real gid. So the value given by C<$(> should I be assigned -back to C<$(> without being forced numeric, such as by adding zero. +back to C<$(> without being forced numeric, such as by adding zero. Note +that this is different to the effective gid (C<$)>) which does take a +list. You can change both the real gid and the effective gid at the same time by using POSIX::setgid(). Changes to $( require a check to $! @@ -1036,7 +1065,7 @@ X<$^C> X<$COMPILING> The current value of the flag associated with the B<-c> switch. Mainly of use with B<-MO=...> to allow code to alter its behavior when being compiled, such as for example to AUTOLOAD at compile -time rather than normal, deferred loading. See L. Setting +time rather than normal, deferred loading. Setting C<$^C = 1> is similar to calling C. =item $DEBUGGING @@ -1296,15 +1325,12 @@ switch); see L for more info on this. X<$^V> X<$PERL_VERSION> 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 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. +as a C object. This variable first appeared in perl 5.6.0; earlier versions of perl will -see an undefined value. +see an undefined value. Before perl 5.10.0 $^V was represented as a v-string. -This can be used to determine whether the Perl interpreter executing a +$^V 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: