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.
=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
a more elaborate exception handling implementation using objects that
maintain arbitrary state about the nature of the exception. Such a scheme
is sometimes preferable to matching particular string values of $@ using
-regular expressions. Here's an example:
+regular expressions. Because $@ is a global variable, and eval() may be
+used within object implementations, care must be taken that analyzing the
+error object doesn't replace the reference in the global variable. The
+easiest solution is to make a local copy of the reference before doing
+other manipulations. Here's an example:
use Scalar::Util 'blessed';
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
- if ($@) {
- if (blessed($@) && $@->isa("Some::Module::Exception")) {
+ if (my $ev_err = $@) {
+ if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
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<print LIST, "\n">,
-and C<say()> works just like C<print($_, "\n")>.
-
-That means that a call to say() appends any output record separator
-I<after> the added newline.
+C<say LIST> is simply an abbreviation for C<{ local $/ = "\n"; print
+LIST }>.
This keyword is only available when the "say" feature is
enabled: see L<feature>.
%E like %e, but using an upper-case "E"
%G like %g, but with an upper-case "E" (if applicable)
%b an unsigned integer, in binary
- %B like %x, but using an upper-case "B" with the # flag
+ %B like %b, but using an upper-case "B" with the # flag
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
into the next variable in the parameter list
=item flags
one or more of:
+
space prefix positive number with a space
+ prefix positive number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
- # prefix non-zero octal with "0", non-zero hex with "0x"
- or "0X", non-zero binary with "0b" or "OB"
+ # ensure the leading "0" for any octal,
+ prefix non-zero hexadecimal with "0x" or "0X",
+ prefix non-zero binary with "0b" or "0B"
For example:
- printf '<% d>', 12; # prints "< 12>"
- printf '<%+d>', 12; # prints "<+12>"
- printf '<%6s>', 12; # prints "< 12>"
- printf '<%-6s>', 12; # prints "<12 >"
- printf '<%06s>', 12; # prints "<000012>"
- printf '<%#x>', 12; # prints "<0xc>"
+ printf '<% d>', 12; # prints "< 12>"
+ printf '<%+d>', 12; # prints "<+12>"
+ printf '<%6s>', 12; # prints "< 12>"
+ printf '<%-6s>', 12; # prints "<12 >"
+ printf '<%06s>', 12; # prints "<000012>"
+ printf '<%#o>', 12; # prints "<014>"
+ printf '<%#x>', 12; # prints "<0xc>"
+ printf '<%#X>', 12; # prints "<0XC>"
+ printf '<%#b>', 12; # prints "<0b1100>"
+ printf '<%#B>', 12; # prints "<0B1100>"
When a space and a plus sign are given as the flags at once,
a plus sign is used to prefix a positive number.
printf '<%+ d>', 12; # prints "<+12>"
printf '<% +d>', 12; # prints "<+12>"
+When the # flag and a precision are given in the %o conversion,
+the precision is incremented if it's necessary for the leading "0".
+
+ printf '<%#.5o>', 012; # prints "<00012>"
+ printf '<%#.5o>', 012345; # prints "<012345>"
+ printf '<%#.0o>', 0; # prints "<0>"
+
=item vector flag
This flag tells perl to interpret the supplied string as a vector of
https://perl5.git.perl.org / perl5.git / blobdiff