Manpages - open.3perl
Table of Contents
![](https://distro.tube/img/logo.png)
NAME
open - perl pragma to set default PerlIO layers for input and output
SYNOPSIS
use open IN => :crlf, OUT => :raw; open my $in, <, foo.txt or die “open failed: $!”; my $line = <$in>; # CRLF translated close $in; open my $out, >, bar.txt or die “open failed: $!”; print $out $line; # no translation of bytes close $out; use open OUT => :encoding(UTF-8); use open IN => :encoding(iso-8859-7); use open IO => :locale; # IO implicit only for :utf8, :encoding, :locale use open :encoding(UTF-8); use open :encoding(iso-8859-7); use open :locale; # with :std, also affect global standard handles use open :std, :encoding(UTF-8); use open :std, OUT => :encoding(cp1252); use open :std, IO => :raw :encoding(UTF-16LE);
DESCRIPTION
Full-fledged support for I/O layers is now implemented provided Perl is configured to use PerlIO as its IO system (which has been the default since 5.8, and the only supported configuration since 5.16).
The open
pragma serves as one of the interfaces to declare default
layers (previously known as disciplines) for all I/O. Any open(),
readpipe() (aka qx//) and similar operators found within the lexical
scope of this pragma will use the declared defaults via the ${^OPEN}
variable.
Layers are specified with a leading colon by convention. You can specify a stack of multiple layers as a space-separated string. See PerlIO for more information on the available layers.
With the IN
subpragma you can declare the default layers of input
streams, and with the OUT
subpragma you can declare the default layers
of output streams. With the IO
subpragma (may be omitted for :utf8
,
:locale
, or :encoding
) you can control both input and output streams
simultaneously.
When open() is given an explicit list of layers (with the three-arg syntax), they override the list declared using this pragma. open() can also be given a single colon (:) for a layer name, to override this pragma and use the default as detailed in Defaults and how to override them in PerlIO.
To translate from and to an arbitrary text encoding, use the :encoding
layer. The matching of encoding names in :encoding
is loose: case does
not matter, and many encodings have several aliases. See
Encode::Supported for details and the list of supported locales.
If you want to set your encoding layers based on your locale environment
variables, you can use the :locale
pseudo-layer. For example:
$ENV{LANG} = ru_RU.KOI8-R; # the :locale will probe the locale environment variables like LANG use open OUT => :locale; open(my $out, >, koi8) or die “open failed: $!”; print $out chr(0x430); # CYRILLIC SMALL LETTER A = KOI8-R 0xc1 close $out; open(my $in, <, koi8) or die “open failed: $!”; printf “%#x\n”, ord(<$in>); # this should print 0xc1 close $in;
The logic of :locale
is described in full in “The :locale
sub-pragma” in encoding, but in short it is first trying
nl_langinfo(CODESET) and then guessing from the LC_ALL and LANG locale
environment variables. :locale
also implicitly turns on :std
.
:std
is not a layer but an additional subpragma. When specified in the
import list, it activates an additional functionality of pushing the
layers selected for input/output handles to the standard filehandles
(STDIN, STDOUT, STDERR). If the new layers and existing layer stack both
end with an :encoding
layer, the existing :encoding
layer will also
be removed.
For example, if both input and out are chosen to be :encoding(UTF-8)
,
a :std
will mean that STDIN, STDOUT, and STDERR will also have
:encoding(UTF-8)
set. On the other hand, if only output is chosen to
be in :encoding(koi8r)
, a :std
will cause only the STDOUT and STDERR
to be in koi8r
.
The effect of :std
is not lexical as it modifies the layer stack of
the global handles. If you wish to apply only this global effect and not
the effect on handles that are opened in that scope, you can isolate the
call to this pragma in its own lexical scope.
{ use open :std, IO => :encoding(UTF-8) }
IMPLEMENTATION DETAILS
There is a class method in PerlIO::Layer
find
which is implemented
as XS code. It is called by import
to validate the layers:
PerlIO::Layer::->find(“perlio”)
The return value (if defined) is a Perl object, of class PerlIO::Layer
which is created by the C code in perlio.c. As yet there is nothing
useful you can do with the object at the perl level.
SEE ALSO
binmode in perlfunc, open in perlfunc, perlunicode, PerlIO, encoding