NAME

       IO::Handle::Prototype::Fallback - Create IO::Handle like objects using a set of callbacks.

SYNOPSIS

           my $fh = IO::Handle::Prototype::Fallback->new(
               getline => sub {
                   my $fh = shift;

                   ...
               },
           );

DESCRIPTION

       This class provides a way to define a filehandle based on callbacks.

       Fallback implementations are provided to the extent possible based on the provided
       callbacks, for both writing and reading.

SPECIAL CALLBACKS

       This class provides two additional methods on top of IO::Handle, designed to let you
       implement things with a minimal amount of baggage.

       The fallback methods are all best implemented using these, though these can be implemented
       in terms of Perl's standard methods too.

       However, to provide the most consistent semantics, it's better to do this:

           IO::Handle::Prototype::Fallback->new(
               __read => sub {
                   shift @array;
               },
           );

       Than this:

           IO::Handle::Prototype::Fallback->new(
               getline => sub {
                   shift @array;
               },
           );

       Because the fallback implementation of "getline" implements all of the extra crap you'd
       need to handle to have a fully featured implementation.

       __read
           Return a chunk of data of any size (could use $/ or not, it depends on you, unlike
           "getline" which probably should respect the value of $/).

           This avoids the annoying "substr" stuff you need to do with "read".

       __write $string
           Write out a string.

           This is like a simplified "print", which can disregard $, and "$\" as well as multiple
           argument forms, and does not have the extra "substr" annoyance of "write" or
           "syswrite".

WRAPPING

       If you provide a single reading related callback ("__read", "getline" or "read") then your
       callback will be used to implement all of the other reading primitives using a string
       buffer.

       These implementations handle $/ in all forms ("undef", ref to number and string), all the
       funny calling conventions for "read", etc.

FALLBACKS

       Any callback that can be defined purely in terms of other callbacks in a way will be
       added. For instance "getc" can be implemented in terms of "read", "say" can be implemented
       in terms of "print", "print" can be implemented in terms of "write", "write" can be
       implemented in terms of "print", etc.

       None of these require special wrapping and will always be added if their dependencies are
       present.

GLOB OVERLOADING

       When overloaded as a glob a tied handle will be returned. This allows you to use the
       handle in Perl's IO builtins. For instance:

           my $line = <$fh>

       will not call the "getline" method natively, but the tied interface arranges for that to
       happen.