File Coverage

blib/lib/Filesys/POSIX/IO/Handle.pm

Criterion	Covered	Total	%
statement	36	36	100.0
branch			n/a
condition			n/a
subroutine	14	14	100.0
pod	8	9	88.8
total	58	59	98.3

# Copyright (c) 2014, cPanel, Inc.
# All rights reserved.
# http://cpanel.net/
#
# This is free software; you can redistribute it and/or modify it under the same
# terms as Perl itself.  See the LICENSE file for further details.

package Filesys::POSIX::IO::Handle;

use strict;
use warnings;

use Fcntl qw(SEEK_CUR);
use Filesys::POSIX::Bits;
use Filesys::POSIX::Bits::System;

=head1 NAME

Filesys::POSIX::IO::Handle - Basic wrapper for Perl file handles

=head1 DESCRIPTION

This package provides a wrapper for standard Perl file handles.  It is not meant
to supplant the behavior or necessity of L; rather, it is meant to
provide a base reference for all of the I/O operations supported by
L, which ignores concerns such as buffering and the like.

=head1 METHODS

=over

=item Cnew($fh)>

Returns a blessed reference to the file handle passed.

=cut

sub new {
    my ( $class, $fh ) = @_;

    return bless \$fh, $class;
}

=item C<$handle-Ewrite($buf, $len)>

Calls L on the current file handle, passing the C<$buf> and
C<$len> arguments literally.  Returns the result of L.

=cut

sub write {
    my ( $self, $buf, $len ) = @_;

    return syswrite( $$self, $buf, $len );
}

=item C<$handle-Eprint(@args)>

Prints a concatenation of each item passed, joined by C<$/>, to the current file
handle.

=cut

sub print {
    my ( $self, @args ) = @_;
    my $buf = join( $/, @args );

    return $self->write( $buf, length $buf );
}

=item C<$handle-Esprintf($format, @args)>

Prints a formatted string to the current file handle.  Uses L.

=cut

sub printf {
    my ( $self, $format, @args ) = @_;
    my $buf = sprintf( $format, @args );

    return $self->write( $buf, length $buf );
}

=item C<$handle-Eread($buf, $len)>

Reads C<$len> bytes from C<$handle> into C<$buf>.

=cut

sub read {
    my $self = shift;
    my $len  = pop;

    return sysread( $$self, $_[0], $len );
}

=item C<$handle-Eseek($pos, $whence)>

Seek C<$handle> to C<$pos> bytes, relative to the current byte position,
according to the seek mode listed in C<$whence>.  C<$whence> is a position
modifier as specified in L.

=cut

sub seek {
    my ( $self, $pos, $whence ) = @_;

    return sysseek(
        $$self, $pos,
        Filesys::POSIX::Bits::System::convertWhenceToSystem($whence)
    );
}

=item C<$handle-Eeof>

Returns a boolean indicating whether the file handle has reached end-of-file.

=cut

sub eof {
    my ($self) = @_;

    return eof $$self;
}

=item C<$handle-Etell>

Returns the current absolute byte position of the current file C<$handle>.

=cut

sub tell {
    my ($self) = @_;

    return sysseek( $$self, 0, SEEK_CUR );
}

=item C<$handle-Eclose>

Close the current file handle.

=cut

sub close {
    my ($self) = @_;

    close $$self;
}

=back

=head1 SEE ALSO

=over

=item L

Provides an implementation of the interface described herein, but for access to
regular file data for L filesystem hierarchies.

=back

=cut

1;

__END__