X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/981b911e11a28c0a992f2065cfe21131e0b43d90..2cb35ee012cfe486aa75a422e7bb3cb18ff51336:/pod/perlvar.pod

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 684cd53..257fdb6 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -503,9 +503,10 @@ initially consists of the arguments to any B<-I> command-line
 switches, followed by the default Perl library, probably
 F</usr/local/lib/perl>, followed by ".", to represent the current
 directory.  ("." will not be appended if taint checks are enabled,
-either by C<-T> or by C<-t>.)  If you need to modify this at runtime,
-you should use the C<use lib> pragma to get the machine-dependent
-library properly loaded also:
+either by C<-T> or by C<-t>, or if configured not to do so by the
+C<-Ddefault_inc_excludes_dot> compile time option.)  If you need to
+modify this at runtime, you should use the C<use lib> pragma to get
+the machine-dependent library properly loaded also:
 
     use lib '/mypath/libdir/';
     use SomeMod;
@@ -540,6 +541,19 @@ inplace editing.
 
 Mnemonic: value of B<-i> switch.
 
+=item @ISA
+X<@ISA>
+
+Each package contains a special array called C<@ISA> which contains a list
+of that class's parent classes, if any. This array is simply a list of
+scalars, each of which is a string that corresponds to a package name. The
+array is examined when Perl does method resolution, which is covered in
+L<perlobj>.
+
+To load packages while adding them to C<@ISA>, see the L<parent> pragma. The
+discouraged L<base> pragma does this as well, but should not be used except
+when compatibility with the discouraged L<fields> pragma is required.
+
 =item $^M
 X<$^M>
 
@@ -646,13 +660,12 @@ or a C<die()>.  The C<__DIE__> handler is explicitly disabled during
 the call, so that you can die from a C<__DIE__> handler.  Similarly
 for C<__WARN__>.
 
-Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
-even inside an C<eval()>.  Do not use this to rewrite a pending
-exception in C<$@>, or as a bizarre substitute for overriding
-C<CORE::GLOBAL::die()>.  This strange action at a distance may be fixed
-in a future release so that C<$SIG{__DIE__}> is only called if your
-program is about to exit, as was the original intent.  Any other use is
-deprecated.
+The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was
+never intended to happen this way, but an implementation glitch made
+this possible. This used to be deprecated, as it allowed strange action
+at a distance like rewriting a pending exception in C<$@>. Plans to
+rectify this have been scrapped, as users found that rewriting a 
+pending exception is actually a useful feature, and not a bug.
 
 C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
 may be called to report (probable) errors found by the parser.  In such
@@ -715,13 +728,14 @@ conversion, which works for both v-strings or version objects:
 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 a decimal representation of the Perl version.
+See also C<L</$]>> for a decimal representation of the Perl version.
 
 The main advantage of C<$^V> over C<$]> is that, for Perl v5.10.0 or
 later, it overloads operators, allowing easy comparison against other
 version representations (e.g. decimal, literal v-string, "v1.2.3", or
 objects).  The disadvantage is that prior to v5.10.0, it was only a
-literal v-string, which can't be easily printed or compared.
+literal v-string, which can't be easily printed or compared, whereas
+the behavior of C<$]> is unchanged on all versions of Perl.
 
 Mnemonic: use ^V for a version object.
 
@@ -894,16 +908,43 @@ find uses of these problematic match variables in your code.
 =over 8
 
 =item $<I<digits>> ($1, $2, ...)
-X<$1> X<$2> X<$3>
+X<$1> X<$2> X<$3> X<$I<digits>>
 
 Contains the subpattern from the corresponding set of capturing
 parentheses from the last successful pattern match, not counting patterns
 matched in nested blocks that have been exited already.
 
+Note there is a distinction between a capture buffer which matches
+the empty string a capture buffer which is optional. Eg, C<(x?)> and
+C<(x)?> The latter may be undef, the former not.
+
 These variables are read-only and dynamically-scoped.
 
 Mnemonic: like \digits.
 
+=item @{^CAPTURE}
+X<@{^CAPTURE}> X<@^CAPTURE>
+
+An array which exposes the contents of the capture buffers, if any, of
+the last successful pattern match, not counting patterns matched
+in nested blocks that have been exited already.
+
+Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index
+is equivalent to $2, etc.
+
+    if ("foal"=~/(.)(.)(.)(.)/) {
+        print join "-", @{^CAPTURE};
+    }
+
+should output "f-o-a-l".
+
+See also L</$I<digits>>, L</%{^CAPTURE}> and L</%{^CAPTURE_ALL}>.
+
+Note that unlike most other regex magic variables there is no single
+letter equivalent to C<@{^CAPTURE}>.
+
+This variable was added in 5.25.7
+
 =item $MATCH
 
 =item $&
@@ -1062,10 +1103,12 @@ examples given for the C<@-> variable.
 
 This variable was added in Perl v5.6.0.
 
+=item %{^CAPTURE}
+
 =item %LAST_PAREN_MATCH
 
 =item %+
-X<%+> X<%LAST_PAREN_MATCH>
+X<%+> X<%LAST_PAREN_MATCH> X<%{^CAPTURE}>
 
 Similar to C<@+>, the C<%+> hash allows access to the named capture
 buffers, should they exist, in the last successful match in the
@@ -1078,6 +1121,9 @@ For example, C<$+{foo}> is equivalent to C<$1> after the following match:
 The keys of the C<%+> hash list only the names of buffers that have
 captured (and that are thus associated to defined values).
 
+If multiple distinct capture groups have the same name, then
+C<$+{NAME}> will refer to the leftmost defined group in the match.
+
 The underlying behaviour of C<%+> is provided by the
 L<Tie::Hash::NamedCapture> module.
 
@@ -1087,7 +1133,8 @@ iterative access to them via C<each> may have unpredictable results.
 Likewise, if the last successful match changes, then the results may be
 surprising.
 
-This variable was added in Perl v5.10.0.
+This variable was added in Perl v5.10.0. The C<%{^CAPTURE}> alias was
+added in 5.25.7.
 
 This variable is read-only and dynamically-scoped.
 
@@ -1135,6 +1182,9 @@ After a match against some variable C<$var>:
 
 This variable was added in Perl v5.6.0.
 
+=item %{^CAPTURE_ALL}
+X<%{^CAPTURE_ALL}>
+
 =item %-
 X<%->
 
@@ -1179,7 +1229,8 @@ iterative access to them via C<each> may have unpredictable results.
 Likewise, if the last successful match changes, then the results may be
 surprising.
 
-This variable was added in Perl v5.10.0.
+This variable was added in Perl v5.10.0. The C<%{^CAPTURE_ALL}> alias was
+added in 5.25.7.
 
 This variable is read-only and dynamically-scoped.
 
@@ -1942,6 +1993,7 @@ undefines the variable during the scope of execution of the including
 function.
 
 This variable was added in Perl 5.8.2 and removed in 5.26.0.
+Setting it to anything other than C<undef> was made fatal in Perl 5.28.0.
 
 =item ${^GLOBAL_PHASE}
 X<${^GLOBAL_PHASE}>