Test::MockFile::FileHandle(3pm)

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

VERSION
Version 0.039

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.

In append mode (">>" or "+>>"), output is always written at the end of the file contents. In other write modes, output is written at the current tell position, overwriting existing bytes. The tell position advances by the number of bytes written.

If the file handle wasn't opened in a write mode, this call will set $! to EBADF and return.

  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.

Per "printf" in perlfunc, "printf" does not append "$\" (the output record separator), unlike "print". We therefore write directly via "_write_bytes" instead of delegating 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
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. Returns undef at EOF.

  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/cpanel/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/cpanel/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 controls the seek origin:

0 (SEEK_SET) - seek to $pos from start of file
1 (SEEK_CUR) - seek to $pos relative to current position
2 (SEEK_END) - seek to $pos relative to end of file

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.