X<scalar> X<string> X<character>
C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
-C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>,
+C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>,
C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
=item Regular expressions and pattern matching
=item Functions for list data
X<list>
-C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack>
+C<grep>, C<join>, C<map>, C<qw//>, C<reverse>, C<sort>, C<unpack>
=item Functions for real %HASHes
X<hash>
X<process> X<pid> X<process id>
C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
-C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
+C<pipe>, C<qx//>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
C<times>, C<wait>, C<waitpid>
=item Keywords related to perl modules
C<abs>, C<bless>, C<break>, C<chomp>, C<chr>, C<continue>, C<default>,
C<exists>, C<formline>, C<given>, C<glob>, C<import>, C<lc>, C<lcfirst>,
-C<lock>, C<map>, C<my>, C<no>, C<our>, C<prototype>, C<qr>, C<qw>, C<qx>,
+C<lock>, C<map>, C<my>, C<no>, C<our>, C<prototype>, C<qr//>, C<qw//>, C<qx//>,
C<readline>, C<readpipe>, C<ref>, C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>,
C<ucfirst>, C<untie>, C<use>, C<when>
suitable for passing binary data. This includes turning off possible CRLF
translation and marking it as bytes (as opposed to Unicode characters).
Note that, despite what may be implied in I<"Programming Perl"> (the
-Camel) or elsewhere, C<:raw> is I<not> the simply inverse of C<:crlf>
--- other layers which would affect binary nature of the stream are
+Camel) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>
+-- other layers which would affect the binary nature of the stream are
I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
PERLIO environment variable.
of this version of Perl therefore refers to "layers" rather than to
"disciplines". Now back to the regularly scheduled documentation...>
-To mark FILEHANDLE as UTF-8, use C<:utf8>.
+To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(utf8)>.
+C<:utf8> just marks the data as UTF-8 without further checking,
+while C<:encoding(utf8)> checks the data for actually being valid
+UTF-8. More details can be found in L<PerlIO::encoding>.
In general, binmode() should be called after open() but before any I/O
is done on the filehandle. Calling binmode() will normally flush any
If you chomp a list, each element is chomped, and the total number of
characters removed is returned.
-If the C<encoding> pragma is in scope then the lengths returned are
-calculated from the length of C<$/> in Unicode characters, which is not
-always the same as the length of C<$/> in the native encoding.
-
Note that parentheses are necessary when you're chomping anything
that is not a simple variable. This is because C<chomp $cwd = `pwd`;>
is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
Returns the character represented by that NUMBER in the character set.
For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face. Note that characters from 128
-to 255 (inclusive) are by default not encoded in UTF-8 Unicode for
-backward compatibility reasons (but see L<encoding>).
+chr(0x263a) is a Unicode smiley face.
Negative values give the Unicode replacement character (chr(0xfffd)),
except under the L<bytes> pragma, where low eight bits of the value
For the reverse, use L</ord>.
-Note that under the C<bytes> pragma the NUMBER is masked to
-the low eight bits.
+Note that characters from 128 to 255 (inclusive) are by default
+internally not encoded as UTF-8 for backward compatibility reasons.
-See L<perlunicode> and L<encoding> for more about Unicode.
+See L<perlunicode> for more about Unicode.
=item chroot FILENAME
X<chroot> X<root>
=item close
-Closes the file or pipe associated with the file handle, returning
-true only if IO buffers are successfully flushed and closes the system
-file descriptor. Closes the currently selected filehandle if the
-argument is omitted.
+Closes the file or pipe associated with the file handle, flushes the IO
+buffers, and closes the system file descriptor. Returns true if those
+operations have succeeded and if no error was reported by any PerlIO
+layer. Closes the currently selected filehandle if the argument is
+omitted.
You don't have to close FILEHANDLE if you are immediately going to do
another C<open> on it, because C<open> will close it for you. (See
be open any more when the program is reincarnated, with possible
resulting confusion on the part of Perl.
-This function is now largely obsolete, partly because it's very
-hard to convert a core file into an executable, and because the
-real compiler backends for generating portable bytecode and compilable
-C code have superseded it. That's why you should now invoke it as
-C<CORE::dump()>, if you don't want to be warned against a possible
+This function is now largely obsolete, mostly because it's very hard to
+convert a core file into an executable. That's why you should now invoke
+it as C<CORE::dump()>, if you don't want to be warned against a possible
typo.
-If you're looking to use L<dump> to speed up your program, consider
-generating bytecode or native C code as described in L<perlcc>. If
-you're just trying to accelerate a CGI script, consider using the
-C<mod_perl> extension to B<Apache>, or the CPAN module, CGI::Fast.
-You might also consider autoloading or selfloading, which at least
-make your program I<appear> to run faster.
-
=item each HASH
X<each> X<hash, iterator>
Note the I<characters>: if the EXPR is in Unicode, you will get the
number of characters, not the number of bytes. To get the length
-in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
+of the internal string in bytes, use C<bytes::length(EXPR)>, see
+L<bytes>. Note that the internal encoding is variable, and the number
+of bytes usually meaningless. To get the number of bytes that the
+string would have when encoded as UTF-8, use
+C<length(Encoding::encode_utf8(EXPR))>.
=item link OLDFILE,NEWFILE
X<link>
translates a list of numbers to the corresponding characters. And
- %hash = map { getkey($_) => $_ } @array;
+ %hash = map { get_a_key_for($_) => $_ } @array;
is just a funny way to write
%hash = ();
- foreach $_ (@array) {
- $hash{getkey($_)} = $_;
+ foreach (@array) {
+ $hash{get_a_key_for($_)} = $_;
}
Note that C<$_> is an alias to the list value, so it can be used to
the original list for which the BLOCK or EXPR evaluates to true.
If C<$_> is lexical in the scope where the C<map> appears (because it has
-been declared with C<my $_>) then, in addition to being locally aliased to
-the list elements, C<$_> keeps being lexical inside the block; i.e. it
+been declared with C<my $_>), then, in addition to being locally aliased to
+the list elements, C<$_> keeps being lexical inside the block; that is, it
can't be seen from the outside, avoiding any potential side-effects.
C<{> starts both hash references and blocks, so C<map { ...> could be either
%hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
-or to force an anon hash constructor use C<+{>
+or to force an anon hash constructor use C<+{>:
@hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end
=item no Module
+=item no VERSION
+
See the C<use> function, of which C<no> is the opposite.
=item oct EXPR
that affect how the input and output are processed (see L<open> and
L<PerlIO> for more details). For example
- open(FH, "<:utf8", "file")
+ open(FH, "<:encoding(UTF-8)", "file")
will open the UTF-8 encoded file containing Unicode characters,
see L<perluniintro>. Note that if layers are specified in the
uses C<$_>.
For the reverse, see L</chr>.
-See L<perlunicode> and L<encoding> for more about Unicode.
+See L<perlunicode> for more about Unicode.
=item our EXPR
X<our> X<global>
prototype is returned.
=item push ARRAY,LIST
-X<push>, X<stack>
+X<push> X<stack>
Treats ARRAY as a stack, and pushes the values of LIST
onto the end of ARRAY. The length of ARRAY increases by the length of
closedir DIR;
=item readline EXPR
+
+=item readline
X<readline> X<gets> X<fgets>
-Reads from the filehandle whose typeglob is contained in EXPR. In scalar
-context, each call reads and returns the next line, until end-of-file is
-reached, whereupon the subsequent call returns undef. In list context,
-reads until end-of-file is reached and returns a list of lines. Note that
-the notion of "line" used here is however you may have defined it
-with C<$/> or C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
+Reads from the filehandle whose typeglob is contained in EXPR (or from
+*ARGV if EXPR is not provided). In scalar context, each call reads and
+returns the next line, until end-of-file is reached, whereupon the
+subsequent call returns undef. In list context, reads until end-of-file
+is reached and returns a list of lines. Note that the notion of "line"
+used here is however you may have defined it with C<$/> or
+C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
When C<$/> is set to C<undef>, when readline() is in scalar
context (i.e. file slurp mode), and when an empty file is read, it
omitted, uses C<$_>.
=item readpipe EXPR
+
+=item readpipe
X<readpipe>
EXPR is executed as a system command.
This is the internal function implementing the C<qx/EXPR/>
operator, but you can use it directly. The C<qx/EXPR/>
operator is discussed in more detail in L<perlop/"I/O Operators">.
+If EXPR is omitted, uses C<$_>.
=item recv SOCKET,SCALAR,LENGTH,FLAGS
X<recv>
print "r is not a reference at all.\n";
}
+The return value C<LVALUE> indicates a reference to an lvalue that is not
+a variable. You get this from taking the reference of function calls like
+C<pos()> or C<substr()>. C<VSTRING> is returned if the reference points
+to a L<version string|perldata\"Version Strings">.
+
+The result C<Regexp> indicates that the argument is a regular expression
+resulting from C<qr//>.
+
See also L<perlref>.
=item rename OLDNAME,NEWNAME
Otherwise, C<require> demands that a library file be included if it
hasn't already been included. The file is included via the do-FILE
-mechanism, which is essentially just a variety of C<eval>. Has
-semantics similar to the following subroutine:
+mechanism, which is essentially just a variety of C<eval> with the
+caveat that lexical variables in the invoking script will be invisible
+to the included code. Has semantics similar to the following subroutine:
sub require {
my ($filename) = @_;
walks through @INC and encounters a subroutine, this subroutine gets
called with two parameters, the first being a reference to itself, and the
second the name of the file to be included (e.g. "F<Foo/Bar.pm>"). The
-subroutine should return nothing, or a list of up to 4 values in the
+subroutine should return nothing, or a list of up to three values in the
following order:
=over
=item 1
-A reference to a scalar, containing any initial source code to prepend to
-the file or generator output.
-
-
-=item 2
-
A filehandle, from which the file will be read.
-=item 3
+=item 2
A reference to a subroutine. If there is no filehandle (previous item),
then this subroutine is expected to generate one line of source code per
Again, return 1 for each valid line, and 0 after all lines have been
returned.
-=item 4
+=item 3
Optional state for the subroutine. The state is passed in as C<$_[1]>. A
reference to the subroutine itself is passed in as C<$_[0]>.
=item say
Just like C<print>, but implicitly appends a newline.
-C<say LIST> is simply an abbreviation for C<{ local $/ = "\n"; print
+C<say LIST> is simply an abbreviation for C<{ local $\ = "\n"; print
LIST }>.
This keyword is only available when the "say" feature is
=item select
-Returns the currently selected filehandle. Sets the current default
-filehandle for output, if FILEHANDLE is supplied. This has two
+Returns the currently selected filehandle. If FILEHANDLE is supplied,
+sets the new current default filehandle for output. This has two
effects: first, a C<write> or a C<print> without a filehandle will
default to this FILEHANDLE. Second, references to variables related to
output will refer to this output channel. For example, if you have to
=item state TYPE EXPR : ATTRS
C<state> declares a lexically scoped variable, just like C<my> does.
-However, those variables will be initialized only once, contrary to
+However, those variables will never be reinitialized, contrary to
lexical variables that are reinitialized each time their enclosing block
is entered.
except that Module I<must> be a bareword.
-VERSION may be either a numeric argument such as 5.006, which will be
-compared to C<$]>, or a literal of the form v5.6.1, which will be compared
-to C<$^V> (aka $PERL_VERSION. A fatal error is produced if VERSION is
-greater than the version of the current Perl interpreter; Perl will not
-attempt to parse the rest of the file. Compare with L</require>, which can
-do a similar check at run time.
+In the peculiar C<use VERSION> form, VERSION may be either a numeric
+argument such as 5.006, which will be compared to C<$]>, or a literal of
+the form v5.6.1, which will be compared to C<$^V> (aka $PERL_VERSION). A
+fatal error is produced if VERSION is greater than the version of the
+current Perl interpreter; Perl will not attempt to parse the rest of the
+file. Compare with L</require>, which can do a similar check at run time.
+Symmetrically, C<no VERSION> allows you to specify that you want a version
+of perl older than the specified one.
Specifying VERSION as a literal of the form v5.6.1 should generally be
avoided, because it leads to misleading error messages under earlier
C<use>ing library modules that have changed in incompatible ways from
older versions of Perl. (We try not to do this more than we have to.)
+Also, if the specified perl version is greater than or equal to 5.9.5,
+C<use VERSION> will also load the C<feature> pragma and enable all
+features available in the requested version. See L<feature>.
+
The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
C<require> makes sure the module is loaded into memory if it hasn't been
yet. The C<import> is not a builtin--it's just an ordinary static method
extend the string with sufficiently many zero bytes. It is an error
to try to write off the beginning of the string (i.e. negative OFFSET).
-The string should not contain any character with the value > 255 (which
-can only happen if you're using UTF-8 encoding). If it does, it will be
-treated as something that is not UTF-8 encoded. When the C<vec> was
-assigned to, other parts of your program will also no longer consider the
-string to be UTF-8 encoded. In other words, if you do have such characters
-in your string, vec() will operate on the actual byte string, and not the
-conceptual character string.
+If the string happens to be encoded as UTF-8 internally (and thus has
+the UTF8 flag set), this is ignored by C<vec>, and it operates on the
+internal byte string, not the conceptual character string, even if you
+only have characters with values less than 256.
Strings created with C<vec> can also be manipulated with the logical
operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit
=item warn LIST
X<warn> X<warning> X<STDERR>
-Produces a message on STDERR just like C<die>, but doesn't exit or throw
-an exception.
+Prints the value of LIST to STDERR. If the last element of LIST does
+not end in a newline, appends the same text as C<die> does.
If LIST is empty and C<$@> already contains a value (typically from a
previous eval) that value is used after appending C<"\t...caught">