[perlvar] $_, $/ and $!

Author: moritz

lib/perlvar.pod

@@ -2,6 +2,70 @@
 
 =head1 perlvar - list of known magical variables
 
+=head2 Often-Used Variables
+
+# TODO: find a better heading
+
+There are three special variables that are available in every block:
+
+=begin table
+
+    Variable    Meaning
+
+    $_          topic variable
+    $/          regex match
+    $!          exceptions
+
+=end table
+
+=head3 $_
+
+C<$_> is the topic variable. It is the default parameter for blocks that do
+not have an explicit signature, so constructs like C<for @array { ... }>
+and C<given $var { ... }> binds to C<$_> simply by invoking the block.
+
+    for <a b c> { say $_ }  # sets $_ to 'a', 'b' and 'c' in turn
+    say $_ for <a b c>;     # same, even though it's not a block
+    given 'a'   { say $_ }  # sets $_ to 'a'
+    say $_ given 'a';       # same, even though it's not a block
+
+C<CATCH> blocks set C<$_> to the exception that was caught. The C<~~>
+smart-match operator sets C<$_> on the right-hand side expression to the
+value of the left-hand side.
+
+Calling a method on C<$_> can be shortened by leaving off the variable name:
+
+    .say;                   # same as $_.say
+
+C<m/regex/> and C</regex/> regex matches and C<s/regex/subst/> substitutions
+work on C<$_>.
+
+=head3 $/
+
+C<$/> is the match variable. It stores the result of each regex match, and
+usually contains objects of type L<Match>.
+
+    'abc 12' ~~ /\w+/;  # sets $/ to a Match object
+    say $/.Str;         # abc
+
+The C<Grammar.parse> method also sets the caller's C<$/> to the resulting
+L<Match> object.
+
+Other match variables are aliases to elements of C<$/>:
+
+    $0          # same as $/[0]
+    $1          # same as $/[1]
+    $<named>    # same as $/<named>
+
+=head3 $!
+
+C<$!> is the error variable. If a C<try> block or statement prefix catches
+an exception, that exception is stored in C<$!>. If no exception was caught,
+C<$!> is set to the C<Any> type object.
+
+Note that C<CATCH> blocks I<do not> set C<$!>. Rather they set C<$_> inside
+the block to the caught exception.
+
 =head2 Compile-time "constants"
 
     $?FILE      Which file am I in?