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.3

DESCRIPTION

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 fileno to fdopen the file descriptor. Possible values can be <, +<, >+, +>, etc and r, r+, w, w+. a and a+

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

print

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:

O_*

F_GETFL

F_SETFL

LOCK_SH

LOCK_EX

LOCK_NB

LOCK_UN

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 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.

cpanm Module::Generic

perl -MCPAN -e shell
install Module::Generic