view release on metacpan or  search on metacpan

lib/Dpkg/Compression/FileHandle.pm  view on Meta::CPAN

# Copyright © 2008-2010 Raphaël Hertzog <hertzog@debian.org>
# Copyright © 2012-2014 Guillem Jover <guillem@debian.org>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

=encoding utf8

=head1 NAME

Dpkg::Compression::FileHandle - class dealing transparently with file compression

=head1 SYNOPSIS

    use Dpkg::Compression::FileHandle;

    my ($fh, @lines);

    $fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');
    print $fh "Something\n";
    close $fh;

    $fh = Dpkg::Compression::FileHandle->new();
    open($fh, '>', 'sample.bz2');
    print $fh "Something\n";
    close $fh;

    $fh = Dpkg::Compression::FileHandle->new();
    $fh->open('sample.xz', 'w');
    $fh->print("Something\n");
    $fh->close();

    $fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');
    @lines = <$fh>;
    close $fh;

    $fh = Dpkg::Compression::FileHandle->new();
    open($fh, '<', 'sample.bz2');
    @lines = <$fh>;
    close $fh;

    $fh = Dpkg::Compression::FileHandle->new();
    $fh->open('sample.xz', 'r');
    @lines = $fh->getlines();
    $fh->close();

=head1 DESCRIPTION

Dpkg::Compression::FileHandle is a class that can be used
like any filehandle and that deals transparently with compressed
files. By default, the compression scheme is guessed from the filename
but you can override this behavior with the method set_compression().

If you don't open the file explicitly, it will be auto-opened on the
first read or write operation based on the filename set at creation time
(or later with the set_filename() method).

Once a file has been opened, the filehandle must be closed before being
able to open another file.

=cut

package Dpkg::Compression::FileHandle 1.01;

use v5.36;

use Carp;

use Dpkg::Compression;
use Dpkg::Compression::Process;
use Dpkg::Gettext;
use Dpkg::ErrorHandling;

use parent qw(IO::File Tie::Handle);

# Useful reference to understand some kludges required to have the class
# behave like a filehandle:
#   <http://blog.woobling.org/2009/10/are-filehandles-objects.html>

=head1 STANDARD FUNCTIONS

The standard functions acting on filehandles should accept a
Dpkg::Compression::FileHandle object transparently including
open() (only when using the variant with 3 parameters), close(),
binmode(), eof(), fileno(), getc(), print(), printf(), read(),
sysread(), say(), write(), syswrite(), seek(), sysseek(), tell().

Note however that seek() and sysseek() will only work on uncompressed
files as compressed files are really pipes to the compressor programs
and you can't seek on a pipe.

=head1 FileHandle METHODS

The class inherits from L<IO::File> so all methods that work on this
class should work for Dpkg::Compression::FileHandle too. There
may be exceptions though.

=head1 PUBLIC METHODS

=over 4

=item $fh = Dpkg::Compression::FileHandle->new(%opts)

Creates a new filehandle supporting on-the-fly compression/decompression.

Options:

=over

=item B<filename>

See $fh->set_filename().

=item B<compression>

See $fh->set_compression().

=item B<compression_level>

See $fh->set_compression_level().

=item B<add_comp_ext>

If set to true, then the extension corresponding to the selected
compression scheme is automatically added to the recorded filename. It's
obviously incompatible with automatic detection of the compression method.

=back

=cut

## Class methods.

sub new {
    my ($this, %opts) = @_;
    my $class = ref($this) || $this;
    my $self = IO::File->new();
    # Tying is required to overload the open functions and to auto-open
    # the file on first read/write operation.
    tie *$self, $class, $self; ## no critic (Miscellanea::ProhibitTies)
    bless $self, $class;
    # Initializations.
    *$self->{compression} = 'auto';