This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfunc: Don’t put __SUB__ between substr entries
[perl5.git] / pod / perlfunc.pod
index 6a09a53..532ea3b 100644 (file)
@@ -161,9 +161,13 @@ C<umask>, C<unlink>, C<utime>
 =item Keywords related to the control flow of your Perl program
 X<control flow>
 
-C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
+C<caller>, C<continue>, C<die>, C<do>,
+C<dump>, C<eval>, C<evalbytes> C<exit>,
 C<__FILE__>, C<goto>, C<last>, C<__LINE__>, C<next>, C<__PACKAGE__>,
-C<redo>, C<return>, C<sub>, C<wantarray>,
+C<redo>, C<return>, C<sub>, C<__SUB__>, C<wantarray>
+
+C<__SUB__> is only available with a C<use v5.16> (or higher) declaration or
+with the C<"current_sub"> feature (see L<feature>).
 
 =item Keywords related to the switch feature
 
@@ -186,7 +190,8 @@ L<feature>.  Alternately, include a C<use v5.10> or later to the current scope.
 
 =item Miscellaneous functions
 
-C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>,
+C<defined>, C<dump>, C<eval>, C<evalbytes>,
+C<formline>, C<local>, C<my>, C<our>,
 C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
@@ -1634,6 +1639,17 @@ Note that the value is parsed every time the C<eval> executes.
 If EXPR is omitted, evaluates C<$_>.  This form is typically used to
 delay parsing and subsequent execution of the text of EXPR until run time.
 
+If the C<unicode_eval> feature is enabled (which is the default under a
+C<use 5.16> or higher declaration), EXPR or C<$_> is treated as a string of
+characters, so C<use utf8> declarations have no effect, and source filters
+are forbidden.  In the absence of the C<unicode_eval> feature, the string
+will sometimes be treated as characters and sometimes as bytes, depending
+on the internal encoding, and source filters activated within the C<eval>
+exhibit the erratic, but historical, behaviour of affecting some outer file
+scope that is still compiling.  See also the L</evalbytes> keyword, which
+always treats its input as a byte stream and works properly with source
+filters, and the L<feature> pragma.
+
 In the second form, the code within the BLOCK is parsed only once--at the
 same time the code surrounding the C<eval> itself was parsed--and executed
 within the context of the current Perl program.  This form is typically
@@ -1763,6 +1779,21 @@ surrounding lexical scope, but rather the scope of the first non-DB piece
 of code that called it.  You don't normally need to worry about this unless
 you are writing a Perl debugger.
 
+=item evalbytes EXPR
+X<evalbytes>
+
+=item evalbytes
+
+This function is like L</eval> with a string argument, except it always
+parses its argument, or C<$_> if EXPR is omitted, as a string of bytes.  A
+string containing characters whose ordinal value exceeds 255 results in an
+error.  Source filters activated within the evaluated code apply to the
+code itself.
+
+This function is only available under the C<evalbytes> feature, a
+C<use v5.16> (or higher) declaration, or with a C<CORE::> prefix.  See
+L<feature> for more information.
+
 =item exec LIST
 X<exec> X<execute>
 
@@ -2536,6 +2567,19 @@ Note that C<glob> splits its arguments on whitespace and treats
 each segment as separate pattern.  As such, C<glob("*.c *.h")> 
 matches all files with a F<.c> or F<.h> extension.  The expression
 C<glob(".* *")> matches all files in the current working directory.
+If you want to glob filenames that might contain whitespace, you'll
+have to use extra quotes around the spacey filename to protect it.
+For example, to glob filenames that have an C<e> followed by a space
+followed by an C<f>, use either of:
+
+    @spacies = <"*e f*">;
+    @spacies = glob '"*e f*"';
+    @spacies = glob q("*e f*");
+
+If you had to get a variable through, you could do this:
+
+    @spacies = glob "'*${var}e f*'";
+    @spacies = glob qq("*${var}e f*");
 
 If non-empty braces are the only wildcard characters used in the
 C<glob>, no filenames are matched, but potentially many strings
@@ -6864,6 +6908,15 @@ See L<perlsub> and L<perlref> for details about subroutines and
 references; see L<attributes> and L<Attribute::Handlers> for more
 information about attributes.
 
+=item __SUB__
+X<__SUB__>
+
+A special token that returns the a reference to the current subroutine, or
+C<undef> outside of a subroutine.
+
+This token is only available under C<use v5.16> or the "current_sub"
+feature.  See L<feature>.
+
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
 X<substr> X<substring> X<mid> X<left> X<right>