NAME
Module::Generic::File::IO - File IO Object Wrapper
SYNOPSIS
use Module::Generic::File::IO;
my $io = Module::Generic::File::IO->new ||
die( Module::Generic::File::IO->error, "\n" );
my $io = Module::Generic::File::IO->new( fileno => $fileno ) ||
die( Module::Generic::File::IO->error, "\n" );
use Module::Generic::File::IO qw( wraphandle );
my $io = wraphandle( $fh );
my $io = wraphandle( $fh, '>' );VERSION
v0.1.3DESCRIPTION
This is a thin wrapper that inherits from IO::File with the purpose of providing a uniform api in conformity with standard api call throughout the Module::Generic modules family and to ensure call to any IO::File will never die, but instead set an error and return undef
Supported methods are rigorously the same as IO::File and IO::Handle on top of all the standard ones from Module::Generic
The IO methods are listed below for convenience, but make sure to check the IO::File documentation for more information.
CONSTRUCTOR
new
This instantiates a new Module::Generic::File::IO object and returns it.
It optionally takes the following parameters:
fileno-
A file descriptor. When this is provided, the newly created object will perform a "fdopen" on the file descriptor provided.
mode-
A mode which will be used along with
filenoto fdopen the file descriptor. Possible values can be<,+<,>+,+>, etc andr,r+,w,w+.aanda+
FUNCTIONS
wraphandle
my $io = Module::Generic::File::IO::wraphandle( $fh, '>' );
# or
use Module::Generic::File::IO qw( wraphandle );
my $io = wraphandle( $fh, '>' );Provided with a filehandle and an optional mode and this will return a newly created Module::Generic::File::IO
By default, the mode will be '<'
METHODS
args
Returns an array reference containing the original arguments passed during object instantiation.
autoflush
See "autoflush" in IO::Handle for details
binmode
See "binmode" in IO::File for details
blocking
See "blocking" in IO::Handle for details
can_read
Returns true if one can read from this filehandle, or false otherwise.
can_write
Returns true if one can write from this filehandle, or false otherwise.
close
See "close" in IO::Handle for details
eof
See "eof" in IO::Handle for details
fcntl
See "fcntl" in IO::Handle for details
fdopen
See "fdopen" in IO::Handle for details
fileno
See "fileno" in IO::Handle for details
flags
Returns the filehandle flags value using "fcntl" in perlfunc
flush
See "flush" in IO::Handle for details
format_formfeed
See "format_formfeed" in IO::Handle for details
format_line_break_characters
See "format_line_break_characters" in IO::Handle for details
format_lines_left
See "format_lines_left" in IO::Handle for details
format_lines_per_page
See "format_lines_per_page" in IO::Handle for details
format_name
See "format_name" in IO::Handle for details
format_page_number
See "format_page_number" in IO::Handle for details
format_top_name
See "format_top_name" in IO::Handle for details
format_write
See "format_write" in IO::Handle for details
formline
See "formline" in IO::Handle for details
getc
See "getc" in IO::Handle for details
getline
See "getline" in IO::Handle for details
getlines
See "getlines" in IO::Handle for details
getpos
See "getpos" in IO::Seekable for details
input_line_number
See "input_line_number" in IO::Handle for details
input_record_separator
See "input_record_separator" in IO::Handle for details
ioctl
See "ioctl" in IO::Handle for details
new_from_fd
See "new_from_fd" in IO::Handle for details
new_tmpfile
See "new_tmpfile" in IO::File for details
opened
See "opened" in IO::Handle for details
output_field_separator
See "output_field_separator" in IO::Handle for details
output_record_separator
See "output_record_separator" in IO::Handle for details
See "print" in IO::Handle for details
printf
See "printf" in IO::Handle for details
printflush
See "printflush" in IO::Handle for details
read
See "read" in IO::Handle for details
say
See "say" in IO::Handle for details
seek
See "seek" in IO::Seekable for details
setpos
See "setpos" in IO::Seekable for details
stat
See "stat" in IO::Handle for details
sync
See "sync" in IO::Handle for details
sysread
See "sysread" in IO::Handle for details
sysseek
See "sysseek" in IO::Seekable for details
syswrite
See "syswrite" in IO::Handle for details
tell
See "tell" in IO::Seekable for details
truncate
See "truncate" in IO::Handle for details
ungetc
See "ungetc" in IO::Handle for details
untaint
See "untaint" in IO::Handle for details
write
See "write" in IO::Handle for details
CONSTANTS
Module::Generic::File::IO automatically exports the following constants taken from Fcntl:
See also the manual page for fcntl for more detail about those constants.
SERIALISATION
Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW
For STORABLE_freeze and STORABLE_thaw, they are not implemented, because as of version 3.26 Storable raises an exception without giving any chance to the IO module to return an object representing the deserialised data. So, instead of using Storable, use instead the drop-in replacement Storable::Improved, which addresses and mitigate those issues.
If you use Storable::Improved, then serialisation and deserialisation will work seamlessly.
Failure to do use Storable::Improved, and Storable would instead return the Module::Generic::File::IO as a SCALAR object rather than a glob.
Note that by default $THAW_REOPENS_FILE is set to a true value, and this will have deserialisation recreate an object somewhat equivalent to the original one.
AUTHOR
Jacques Deguest <jack@deguest.jp>
SEE ALSO
IO::Handle, IO::File, IO::Seekable
COPYRIGHT & LICENSE
Copyright(c) 2022-2024 DEGUEST Pte. Ltd.
All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.