.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::BOM 3pm"
.TH File::BOM 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::BOM \- Utilities for handling Byte Order Marks
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use File::BOM qw( :all )
.Ve
.SS "high-level functions"
.IX Subsection "high-level functions"
.Vb 3
\&    # read a file with encoding from the BOM:
\&    open_bom(FH, $file)
\&    open_bom(FH, $file, \*(Aq:utf8\*(Aq) # the same but with a default encoding
\&
\&    # get encoding too
\&    $encoding = open_bom(FH, $file, \*(Aq:utf8\*(Aq);
\&
\&    # open a potentially unseekable file:
\&    ($encoding, $spillage) = open_bom(FH, $file, \*(Aq:utf8\*(Aq);
\&
\&    # change encoding of an open handle according to BOM
\&    $encoding = defuse(*HANDLE);
\&    ($encoding, $spillage) = defuse(*HANDLE);
\&
\&    # Decode a string according to leading BOM:
\&    $unicode = decode_from_bom($string_with_bom);
\&    
\&    # Decode a string and get the encoding:
\&    ($unicode, $encoding) = decode_from_bom($string_with_bom)
.Ve
.SS "PerlIO::via interface"
.IX Subsection "PerlIO::via interface"
.Vb 2
\&    # Read the Right Thing from a unicode file with BOM:
\&    open(HANDLE, \*(Aq<:via(File::BOM)\*(Aq, $filename)
\&
\&    # Writing little\-endian UTF\-16 file with BOM:
\&    open(HANDLE, \*(Aq>:encoding(UTF\-16LE):via(File::BOM)\*(Aq, $filename)
.Ve
.SS "lower-level functions"
.IX Subsection "lower-level functions"
.Vb 2
\&    # read BOM encoding from a filehandle:
\&    $encoding = get_encoding_from_filehandle(FH)
\&
\&    # Get encoding even if FH is unseekable:
\&    ($encoding, $spillage) = get_encoding_from_filehandle(FH);
\&
\&    # Get encoding from a known unseekable handle:
\&    ($encdoing, $spillage) = get_encoding_from_stream(FH);
\&
\&    # get encoding and BOM length from BOM at start of string:
\&    ($encoding, $offset) = get_encoding_from_bom($string);
.Ve
.SS "variables"
.IX Subsection "variables"
.Vb 2
\&    # print a BOM for a known encoding
\&    print FH $enc2bom{$encoding};
\&
\&    # get an encoding from a known BOM
\&    $enc = $bom2enc{$bom}
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functions for handling unicode byte order marks, which are
to be found at the beginning of some files and streams.
.PP
For details about what a byte order mark is, see
<http://www.unicode.org/unicode/faq/utf_bom.html#BOM>
.PP
The intention of File::BOM is for files with BOMs to be readable as seamlessly
as possible, regardless of the encoding used. To that end, several different
interfaces are available, as shown in the synopsis above.
.SH "EXPORTS"
.IX Header "EXPORTS"
Nothing by default.
.SS "symbols"
.IX Subsection "symbols"
.IP "\(bu" 4
\&\fBopen_bom()\fR
.IP "\(bu" 4
\&\fBdefuse()\fR
.IP "\(bu" 4
\&\fBdecode_from_bom()\fR
.IP "\(bu" 4
\&\fBget_encoding_from_filehandle()\fR
.IP "\(bu" 4
\&\fBget_encoding_from_stream()\fR
.IP "\(bu" 4
\&\fBget_encoding_from_bom()\fR
.IP "\(bu" 4
\&\f(CW%bom2enc\fR
.IP "\(bu" 4
\&\f(CW%enc2bom\fR
.SS "tags"
.IX Subsection "tags"
.IP "\(bu" 4
:all
.Sp
All of the above
.IP "\(bu" 4
:subs
.Sp
subroutines only
.IP "\(bu" 4
:vars
.Sp
just \f(CW%bom2enc\fR and \f(CW%enc2bom\fR
.SH "VARIABLES"
.IX Header "VARIABLES"
.ie n .SS "%bom2enc"
.el .SS "\f(CW%bom2enc\fP"
.IX Subsection "%bom2enc"
Maps Byte Order marks to their encodings.
.PP
The keys of this hash are strings which represent the BOMs, the values are their
encodings, in a format which is understood by Encode
.PP
The encodings represented in this hash are: \s-1UTF\-8, UTF\-16BE, UTF\-16LE,
UTF\-32BE\s0 and \s-1UTF\-32LE\s0
.ie n .SS "%enc2bom"
.el .SS "\f(CW%enc2bom\fP"
.IX Subsection "%enc2bom"
A reverse-lookup hash for bom2enc, with a few aliases used in Encode, namely utf8, iso\-10646\-1 and \s-1UCS\-2.\s0
.PP
Note that \s-1UTF\-16, UTF\-32\s0 and \s-1UCS\-4\s0 are not included in this hash. Mainly
because Encode::encode automatically puts BOMs on output. See Encode::Unicode
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "open_bom"
.IX Subsection "open_bom"
.Vb 1
\&    $encoding = open_bom(HANDLE, $filename, $default_mode)
\&
\&    ($encoding, $spill) = open_bom(HANDLE, $filename, $default_mode)
.Ve
.PP
opens \s-1HANDLE\s0 for reading on \f(CW$filename\fR, setting the mode to the appropriate
encoding for the \s-1BOM\s0 stored in the file.
.PP
On failure, a fatal error is raised, see the \s-1DIAGNOSTICS\s0 section for details on
how to catch these. This is in order to allow the return value(s) to be used for
other purposes.
.PP
If the file doesn't contain a \s-1BOM,\s0 \f(CW$default_mode\fR is used instead. Hence:
.PP
.Vb 1
\&    open_bom(FH, \*(Aqmy_file.txt\*(Aq, \*(Aq:utf8\*(Aq)
.Ve
.PP
Opens my_file.txt for reading in an appropriate encoding found from the \s-1BOM\s0 in
that file, or as a \s-1UTF\-8\s0 file if none is found.
.PP
In the absence of a \f(CW$default_mode\fR argument, the following 2 calls should be equivalent:
.PP
.Vb 1
\&    open_bom(FH, \*(Aqno_bom.txt\*(Aq);
\&
\&    open(FH, \*(Aq<\*(Aq, \*(Aqno_bom.txt\*(Aq);
.Ve
.PP
If an undefined value is passed as the handle, a symbol will be generated for it
like \fBopen()\fR does:
.PP
.Vb 3
\&    # create filehandle on the fly
\&    $enc = open_bom(my $fh, $filename, \*(Aq:utf8\*(Aq);
\&    $line = <$fh>;
.Ve
.PP
The filehandle will be cued up to read after the \s-1BOM.\s0 Unseekable files (e.g.
fifos) will cause croaking, unless called in list context to catch spillage
from the handle. Any spillage will be automatically decoded from the encoding,
if found.
.PP
.Vb 1
\&    e.g.
\&
\&    # croak if my_socket is unseekable
\&    open_bom(FH, \*(Aqmy_socket\*(Aq);
\&
\&    # keep spillage if my_socket is unseekable
\&    ($encoding, $spillage) = open_bom(FH, \*(Aqmy_socket\*(Aq);
\&
\&    # discard any spillage from open_bom
\&    ($encoding) = open_bom(FH, \*(Aqmy_socket\*(Aq);
.Ve
.SS "defuse"
.IX Subsection "defuse"
.Vb 1
\&    $enc = defuse(FH);
\&
\&    ($enc, $spill) = defuse(FH);
.Ve
.PP
\&\s-1FH\s0 should be a filehandle opened for reading, it will have the relevant encoding
layer pushed onto it be binmode if a \s-1BOM\s0 is found. Spillage should be Unicode,
not bytes.
.PP
Any uncaptured spillage will be silently lost. If the handle is unseekable, use
list context to avoid data loss.
.PP
If no \s-1BOM\s0 is found, the mode will be unaffected.
.SS "decode_from_bom"
.IX Subsection "decode_from_bom"
.Vb 1
\&    $unicode_string = decode_from_bom($string, $default, $check)
\&
\&    ($unicode_string, $encoding) = decode_from_bom($string, $default, $check)
.Ve
.PP
Reads a \s-1BOM\s0 from the beginning of \f(CW$string\fR, decodes \f(CW$string\fR (minus the \s-1BOM\s0) and
returns it to you as a perl unicode string.
.PP
if \f(CW$string\fR doesn't have a \s-1BOM,\s0 \f(CW$default\fR is used instead.
.PP
\&\f(CW$check\fR, if supplied, is passed to Encode::decode as the third argument.
.PP
If there's no \s-1BOM\s0 and no default, the original string is returned and encoding
is ''.
.PP
See Encode
.SS "get_encoding_from_filehandle"
.IX Subsection "get_encoding_from_filehandle"
.Vb 1
\&    $encoding = get_encoding_from_filehandle(HANDLE)
\&
\&    ($encoding, $spillage) = get_encoding_from_filehandle(HANDLE)
.Ve
.PP
Returns the encoding found in the given filehandle.
.PP
The handle should be opened in a non-unicode way (e.g. mode '<:bytes') so that
the \s-1BOM\s0 can be read in its natural state.
.PP
After calling, the handle will be set to read at a point after the \s-1BOM\s0 (or at
the beginning of the file if no \s-1BOM\s0 was found)
.PP
If called in scalar context, unseekable handles cause a \fBcroak()\fR.
.PP
If called in list context, unseekable handles will be read byte-by-byte and any
spillage will be returned. See \fBget_encoding_from_stream()\fR
.SS "get_encoding_from_stream"
.IX Subsection "get_encoding_from_stream"
.Vb 1
\&    ($encoding, $spillage) = get_encoding_from_stream(*FH);
.Ve
.PP
Read a \s-1BOM\s0 from an unrewindable source. This means reading the stream one byte
at a time until either a \s-1BOM\s0 is found or every possible \s-1BOM\s0 is ruled out. Any
non-BOM bytes read from the handle will be returned in \f(CW$spillage\fR.
.PP
If a \s-1BOM\s0 is found and the spillage contains a partial character (judging by the
expected character width for the encoding) more bytes will be read from the
handle to ensure that a complete character is returned.
.PP
Spillage is always in bytes, not characters.
.PP
This function is less efficient than get_encoding_from_filehandle, but should
work just as well on a seekable handle as on an unseekable one.
.SS "get_encoding_from_bom"
.IX Subsection "get_encoding_from_bom"
.Vb 1
\&    ($encoding, $offset) = get_encoding_from_bom($string)
.Ve
.PP
Returns the encoding and length in bytes of the \s-1BOM\s0 in \f(CW$string\fR.
.PP
If there is no \s-1BOM,\s0 an empty string is returned and \f(CW$offset\fR is zero.
.PP
To get the data from the string, the following should work:
.PP
.Vb 1
\&    use Encode;
\&
\&    my($encoding, $offset) = get_encoding_from_bom($string);
\&
\&    if ($encoding) {
\&        $string = decode($encoding, substr($string, $offset))
\&    }
.Ve
.SH "PerlIO::via interface"
.IX Header "PerlIO::via interface"
File::BOM can be used as a PerlIO::via interface.
.PP
.Vb 1
\&    open(HANDLE, \*(Aq<:via(File::BOM)\*(Aq, \*(Aqmy_file.txt\*(Aq);
\&
\&    open(HANDLE, \*(Aq>:encoding(UTF\-16LE):via(File::BOM)\*(Aq, \*(Aqout_file.txt\*(Aq);
\&    print "foo\en"; # BOM is written to file here
.Ve
.PP
This method is less prone to errors on non-seekable files as spillage is
incorporated into an internal buffer, but it doesn't give you any information
about the encoding being used, or indeed whether or not a \s-1BOM\s0
was present.
.PP
There are a few known problems with this interface, especially surrounding
\&\fBseek()\fR and \fBtell()\fR, please see the \s-1BUGS\s0 section for more details about this.
.SS "Reading"
.IX Subsection "Reading"
The via(File::BOM) layer must be added before the handle is read from, otherwise
any \s-1BOM\s0 will be missed. If there is no \s-1BOM,\s0 no decoding will be done.
.PP
Because of a limitation in PerlIO::via, \fBread()\fR always works on bytes, not characters. \s-1BOM\s0 decoding will still be done but output will be bytes of \s-1UTF\-8.\s0
.PP
.Vb 3
\&    open(BOM, \*(Aq<:via(File::BOM)\*(Aq, $file);
\&    $bytes_read = read(BOM, $buffer, $length);
\&    $unicode = decode(\*(AqUTF\-8\*(Aq, $buffer, Encode::FB_QUIET);
\&
\&    # Now $unicode is valid unicode and $buffer contains any left\-over bytes
.Ve
.SS "Writing"
.IX Subsection "Writing"
Add the via(File::BOM) layer on top of a unicode encoding layer to print a \s-1BOM\s0
at the start of the output file. This needs to be done before any data is
written. The \s-1BOM\s0 is written as part of the first print command on the handle, so
if you don't print anything to the handle, you won't get a \s-1BOM.\s0
.PP
There is a \*(L"Wide character in print\*(R" warning generated when the via(File::BOM)
layer doesn't receive utf8 on writing. This glitch was resolved in perl version
5.8.7, but if your perl version is older than that, you'll need to make sure
that the via(File::BOM) layer receives utf8 like this:
.PP
.Vb 2
\&    # This works OK
\&    open(FH, \*(Aq>:encoding(UTF\-16LE):via(File::BOM):utf8\*(Aq, $filename)
\&
\&    # This generates warnings with older perls
\&    open(FH, \*(Aq>:encoding(UTF\-16LE):via(File::BOM)\*(Aq, $filename)
.Ve
.SS "Seeking"
.IX Subsection "Seeking"
Seeking with \s-1SEEK_SET\s0 results in an offset equal to the length of any detected
\&\s-1BOM\s0 being applied to the position parameter. Thus:
.PP
.Vb 2
\&    # Seek to end of BOM (not start of file!)
\&    seek(FILE_BOM_HANDLE, 0, SEEK_SET)
.Ve
.SS "Telling"
.IX Subsection "Telling"
In order to work correctly with \fBseek()\fR, \fBtell()\fR also returns a postion adjusted
by the length of the \s-1BOM.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Encode
.IP "\(bu" 4
Encode::Unicode
.IP "\(bu" 4
<http://www.unicode.org/unicode/faq/utf_bom.html#BOM>
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following exceptions are raised via \fBcroak()\fR
.IP "\(bu" 4
Couldn't read '<filename>': $!
.Sp
\&\fBopen_bom()\fR couldn't open the given file for reading
.IP "\(bu" 4
Couldn't set binmode of handle opened on '<filename>' to '<mode>': $!
.Sp
\&\fBopen_bom()\fR couldn't set the binmode of the handle
.IP "\(bu" 4
No string
.Sp
decode_from_bom called on an undefined value
.IP "\(bu" 4
Unseekable handle: $!
.Sp
\&\fBget_encoding_from_filehandle()\fR or \fBopen_bom()\fR called on an unseekable file or handle in scalar context.
.IP "\(bu" 4
Couldn't read from handle: $!
.Sp
\&\fB_get_encoding_seekable()\fR couldn't read the handle. This function is called from
\&\fBget_encoding_from_filehandle()\fR, \fBdefuse()\fR and \fBopen_bom()\fR
.IP "\(bu" 4
Couldn't reset read position: $!
.Sp
_get_encoding_seekable couldn't seek to the position after the \s-1BOM.\s0
.IP "\(bu" 4
Couldn't read byte: $!
.Sp
get_encoding_from_stream couldn't read from the handle. This function is called
from \fBget_encoding_from_filehandle()\fR and \fBopen_bom()\fR when the handle or file is
unseekable.
.SH "BUGS"
.IX Header "BUGS"
Older versions of PerlIO::via have a few problems with writing, see above.
.PP
The current version of PerlIO::via has limitations with regard to seek and tell,
currently only line-wise seek and tell are supported by this module. If \fBread()\fR
is used to read partial lines, \fBtell()\fR will still give the position of the end of
the last line read.
.PP
Under windows, \fBtell()\fR seems to return erroneously when reading files with unix
line endings.
.PP
Under windows, warnings may be generated when using the PerlIO::via interface to
read \s-1UTF\-16LE\s0 and \s-1UTF\-32LE\s0 encoded files. This seems to be a bug in the relevant
encoding(...) layers.
.SH "AUTHOR"
.IX Header "AUTHOR"
Matt Lawrence <mattlaw@cpan.org>
.PP
With thanks to Mark Fowler and Steve Purkis for additional tests and advice.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005 Matt Lawrence, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.