PerlIO::encoding#
Open a filehandle with a transparent character-set encoding filter.
PerlIO::encoding provides the :encoding(NAME) layer that open and binmode accept. Bytes read through the layer are decoded from NAME into Perl character strings; character strings written through it are encoded back into NAME before reaching the layer below. Both directions go through Encode, so every encoding Encode knows is available:
open my $fh, '<:encoding(UTF-8)', $file or die $!;
binmode STDOUT, ':encoding(iso-8859-1)';
The encoding name is resolved with Encode::find_encoding. A name it does not know warns Cannot find encoding "NAME" and the layer fails to be pushed, with $! set to EINVAL.
$PerlIO::encoding::fallback holds the CHECK value handed to Encode’s encode and decode for every conversion the layer makes. It defaults to Encode::PERLQQ | Encode::WARN_ON_ERR | Encode::ONLY_PRAGMA_WARNINGS, so malformed data is substituted and warned about rather than being fatal. Each handle captures the value in effect when its layer is pushed, so changing it afterwards does not affect handles that are already open. It must be an integer: a reference croaks with PerlIO::encoding::fallback must be an integer. Whatever it is set to, the layer always adds Encode::STOP_AT_PARTIAL and always clears Encode::LEAVE_SRC.
A partial character stranded in the buffer is an error wherever it cannot be represented: closing such a handle croaks with Close with partial character, and tell on one croaks with Cannot tell at partial character.
Encodings that report needs_lines - the stateful ones that have to see whole lines - make the layer split writes at newlines and flush each line on its own.
This is a native implementation of PerlIO::encoding 0.31; its PerlIO/encoding.pm is used unchanged, and the layer loads itself (and Encode) the first time :encoding(...) is named.
Differences from upstream#
None.