NAME

       PerlIO::Layers - Querying your filehandle's capabilities

VERSION

       version 0.012

SYNOPSIS

        use PerlIO::Layers qw/query_handle/;

        if (!query_handle(\*STDOUT, 'binary')) {
            ...
        }

DESCRIPTION

       Perl's filehandles are implemented as a stack of layers, with the bottom-most usually
       doing the actual IO and the higher ones doing buffering, encoding/decoding or
       transformations. PerlIO::Layers allows you to query the filehandle's properties concerning
       these layers.

FUNCTIONS

   query_handle($fh, $query_name [, $argument])
       This query a filehandle for some information. All queries can take an optional argument,
       that will test for that layer's properties instead of all layers of the handle. Currently
       supported queries include:

       •   layer

           Check the presence of a certain layer. Unlike most other properties $argument is
           mandatory for this query.

       •   utf8

           Check whether the filehandle/layer handles unicode

       •   crlf

           Check whether the filehandle/layer does crlf translation

       •   binary

           Check whether the filehandle/layer is binary. This test is pessimistic (for unknown
           layers it will assume it's not binary).

       •   mappable

           Checks whether the filehandle/layer is memory mappable. It is the same as binary,
           except that the "utf8" layer is accepted.

       •   buffered

           Check whether the filehandle/layer is buffered.

       •   readable

           Check whether the filehandle/layer is readable.

       •   writeable

           Check whether the filehandle/layer is writeable.

       •   open

           Check whether the filehandle/layer is open.

       •   temp

           Check whether the filehandle/layer refers to a temporary file.

       •   can_crlf

           Checks whether layer $argument (or any layer if $argument it not given) can do crlf
           translation.

       •   line_buffered

           Check whether the filehandle is in line-buffering mode.

       •   autoflush

           Checks whether the filehandle is in unbuffering mode. Note that this is not the
           opposite of buffering, but more similar to autoflush, hence the name of this test.

       •   buffer_size

           Check whether the buffer size is equal to $argument.

   get_layers($fh)
       Gets information on the layers of a filehandle. It's a list with whose entries have 3
       elements: the name of the layer, the arguments of the layer (may be undef) and an arrayref
       with the flags of the layer as strings. The flags array can contain any of these values:

       •   EOF

           End of file has been reached.

       •   CANWRITE

           Writes are permitted, i.e. opened as ">" or "+<" or ">>", etc.

       •   CANREAD

           Reads are permitted i.e. opened "<" or "+>".

       •   ERROR

           An error has occurred.

       •   TRUNCATE

           Truncate file suggested by open mode.

       •   APPEND

           All writes should be appends.

       •   CRLF

           Layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF mapped to
           "\n" for input. Normally the provided "crlf" layer is the only layer that need bother
           about this. "binmode" will mess with this flag rather than add/remove layers if the
           PERLIO_K_CANCRLF bit is set for the layers class.

       •   UTF8

           Data written to this layer should be UTF-8 encoded; data provided by this layer should
           be considered UTF-8 encoded. Can be set on any layer by ":utf8" dummy layer. Also set
           on ":encoding" layer.

       •   UNBUF

           Layer is unbuffered - i.e. write to next layer down should occur for each write to
           this layer.

       •   WRBUF

           The buffer for this layer currently holds data written to it but not sent to next
           layer.

       •   RDBUF

           The buffer for this layer currently holds unconsumed data read from layer below.

       •   LINEBUF

           Layer is line buffered. Write data should be passed to next layer down whenever a "\n"
           is seen. Any data beyond the "\n" should then be processed.

       •   TEMP

           File has been unlink()ed, or should be deleted on close().

       •   OPEN

           Handle is open.

       •   FASTGETS

           This instance of this layer supports the "fast gets" interface. Normally set based on
           PERLIO_K_FASTGETS for the class and by the existence of the function(s) in the table.
           However a class that normally provides that interface may need to avoid it on a
           particular instance. The "pending" layer needs to do this when it is pushed above a
           layer which does not support the interface.

       "query_handle" provides a more high level interface to this, you should probably use that
       when you can.

   get_buffer_sizes($fh)
       Returns a list of buffer sizes for all buffered layers. Unbuffered layers are skipped.

AUTHOR

       Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Leon Timmermans.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.