Clarification in perlre.pod about captures created inside a DEFINE

1 files changed, 13 insertions, 0 deletions

diff --git a/pod/perlre.pod b/pod/perlre.pod
index dafe4cf48f..8f6a04f185 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -1560,6 +1560,19 @@ after the recursion returns, so the extra layer of capturing groups is
 necessary. Thus C<$+{NAME_PAT}> would not be defined even though
 C<$+{NAME}> would be.
 
+Finally, keep in mind that subpatterns created inside a DEFINE block
+count towards the absolute and relative number of captures, so this:
+
+    my @captures = "a" =~ /(.)                  # First capture
+                           (?(DEFINE)
+                               (?<EXAMPLE> 1 )  # Second capture
+                           )/x;
+    say scalar @captures;
+
+Will output 2, not 1. This is particularly important if you intend to
+compile the definitions with the C<qr//> operator, and later
+interpolate them in another pattern.
+
 =item C<< (?>pattern) >>
 X<backtrack> X<backtracking> X<atomic> X<possessive>