NAME

       Test::MockFile::FileHandle - Provides a class for Test::MockFile to tie to on open or
       sysopen.

VERSION

       Version 0.036

SYNOPSIS

       This is a helper class for Test::MockFile. It leverages data in the Test::MockFile
       namespace but lives in its own package since it is the class that file handles are tied to
       when created in Test::MockFile

           use Test::MockFile::FileHandle;
           tie *{ $_[0] }, 'Test::MockFile::FileHandle', $abs_path, $rw;

EXPORT

       No exports are provided by this module.

SUBROUTINES/METHODS

   TIEHANDLE
       Args: ($class, $file, $mode)

       Returns a blessed object for Test::MockFile to tie against. There are no error conditions
       handled here.

       One of the object variables tracked here is a pointer to the file contents in
       %Test::MockFile::files_being_mocked. In order to allow MockFiles to be DESTROYED when they
       go out of scope, we have to weaken this pointer.

       See Test::MockFile for more info.

   PRINT
       This method will be triggered every time the tied handle is printed to with the print() or
       say() functions. Beyond its self reference it also expects the list that was passed to the
       print function.

       We append to "$Test::MockFile::files_being_mocked{$file}-"{'contents'}> with what was
       sent. If the file handle wasn't opened in a read mode, then this call with throw EBADF via
       $!

   PRINTF
       This method will be triggered every time the tied handle is printed to with the printf()
       function. Beyond its self reference it also expects the format and list that was passed to
       the printf function.

       We use sprintf to format the output and then it is sent to PRINT

   WRITE
       This method will be called when the handle is written to via the syswrite function.

       Arguments passed are:"( $self, $buf, $len, $offset )"

       This is one of the more complicated functions to mimic properly because $len and $offset
       have to be taken into account. Reviewing how syswrite works reveals there are all sorts of
       weird corner cases.

   READLINE
       This method is called when the handle is read via <HANDLE> or readline HANDLE.

       Based on the numeric location we are in the file (tell), we read until the EOF separator
       ($/) is seen. tell is updated after the line is read. undef is returned if tell is already
       at EOF.

   GETC
       UNIMPLEMENTED: Open a ticket in github <https://github.com/cpanelinc/Test-MockFile/issues>
       if you need this feature.

       This method will be called when the getc function is called. It reads 1 character out of
       contents and adds 1 to tell. The character is returned.

   READ
       Arguments passed are:"( $self, $file_handle, $len, $offset )"

       This method will be called when the handle is read from via the read or sysread functions.
       Based on $offset and $len, it's possible to end up with some really weird strings with
       null bytes in them.

   CLOSE
       This method will be called when the handle is closed via the close function. The object is
       untied and the file contents (weak reference) is removed. Further calls to this object
       should fail.

   UNTIE
       As with the other types of ties, this method will be called when untie happens. It may be
       appropriate to "auto CLOSE" when this occurs. See The untie Gotcha below.

       What's strange about the development of this class is that we were unable to determine how
       to trigger this call. At the moment, the call is just redirected to CLOSE.

   DESTROY
       As with the other types of ties, this method will be called when the tied handle is about
       to be destroyed. This is useful for debugging and possibly cleaning up.

       At the moment, the call is just redirected to CLOSE.

   EOF
       This method will be called when the eof function is called. Based on "$self->{'tell'}", we
       determine if we're at EOF.

   BINMODE
       Binmode does nothing as whatever format you put the data into the file as is how it will
       come out. Possibly we could decode the SV if this was done but then we'd have to do it
       every time contents are altered. Please open a ticket if you want this to do something.

       No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists
       on this method.

   OPEN
       UNIMPLEMENTED: Open a ticket in github <https://github.com/cpanelinc/Test-MockFile/issues>
       if you need this feature.

       No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists
       on this method.

   FILENO
       UNIMPLEMENTED: Open a ticket in github <https://github.com/cpanelinc/Test-MockFile/issues>
       if you need this feature.

       No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists
       on this method.

   SEEK
       Arguments passed are:"( $self, $pos, $whence )"

       Moves the location of our current tell location.

       $whence is UNIMPLEMENTED: Open a ticket in github <https://github.com/cpanelinc/Test-
       MockFile/issues> if you need this feature.

       No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists
       on this method.

   TELL
       Returns the numeric location we are in the file. The "TELL" tells us where we are in the
       file contents.

       No perldoc documentation <http://perldoc.perl.org/perltie.html#Tying-FileHandles> exists
       on this method.