view release on metacpan or  search on metacpan

lib/Compress/BGZF/Writer.pm  view on Meta::CPAN

    if ($self->{write_eof} && defined fileno($self->{fh})) {
        print { $self->{fh} } BGZF_EOF;
    }
    if (defined fileno($self->{fh}) ) {
        close $self->{fh}
            or croak "Error closing compressed file";
    }

    return;

}

sub write_index {

    #-------------------------------------------------------------------------
    # ARG 0 : index output filename
    #-------------------------------------------------------------------------
    # No returns
    #-------------------------------------------------------------------------

    my ($self, $fn_out) = @_;

    $self->finalize(); # always clear remaining buffer to fully populate index
    croak "missing index output filename" if (! defined $fn_out);
    open my $fh_out, '>:raw', $fn_out
        or croak "Error opening index file for writing";

    my @offsets = @{ $self->{idx} };
    pop @offsets; # last offset is EOF
    print {$fh_out} pack('Q<', scalar(@offsets))
        or croak "Error printing to index file";
    for (@offsets) {
        print {$fh_out} pack('Q<Q<', @{$_})
            or croak "Error printing offset to index file";
    }

    close $fh_out
        or croak "Error closing index file after writing";
    return;

}

sub DESTROY {

    my ($self) = @_;

    # make sure we call finalize in case the caller forgot
    $self->finalize();

    return;

}

1;


__END__

=head1 NAME

Compress::BGZF::Writer - Performs blocked GZIP (BGZF) compression

=head1 SYNOPSIS

    use Compress::BGZF::Writer;

    # Use as filehandle
    my $fh_bgz = Compress::BGZF::Writer->new_filehandle( $bgz_filename );
    print ref($writer), "\n"; # prints 'GLOB'
    while ( my $chunk = generate_data() ) {
        print {$fh_bgz} $chunk;
    }
    close $fh_bgz;

    # Use as object
    my $writer = Compress::BGZF::Writer->new( $bgz_filename );
    print ref($writer), "\n"; # prints 'Compress::BGZF::Writer'
    while ( my ($id,$content) = generate_record() ) {
        my $virt_offset = $writer->add_data( $content );
        my $content_len = length $content;
        print {$idx_file} "$id\t$virt_offset\t$content_len\n";
    }
    $writer->finalize(); # flush remaining buffer;

=head1 DESCRIPTION

C<Compress::BGZF::Writer> is a module for writing blocked GZIP (BGZF) files from
any input. There are two main modes of construction - as an object (using
C<new()>) and as a filehandle glob (using C<new_filehandle>). The filehandle
mode is straightforward for general use. The object mode is useful for
tracking the virtual offsets of data chunks as they are added (for instance,
for generation of a custom index).

=head1 METHODS

=head2 Filehandle Functions

=over 4

=item B<new_filehandle>

    my $fh_out = Compress::BGZF::Writer->new_filehandle();
    my $fh_out = Compress::BGZF::Writer->new_filehandle( $output_fn );

Create a new C<Compress::BGZF::Writer> engine and tie it to a IO::File handle,
which is returned. Takes an optional single argument
for the filename to be written to (defaults to STDOUT).

=item B<print>

=item B<close>

    print {$fh_out} $some_data;
    close $fh_out;

These functions emulate the standard perl functions of the same name.

=back

=head2 0bject-oriented Methods

=over 4

=item B<new>

    my $writer = Compress::BGZF::Writer->new();
    my $writer = Compress::BGZF::Writer->new( $output_fn );

Create a new C<Compress::BGZF::Writer> engine. Takes an optional single argument
for the filename to be written to (defaults to STDOUT).

=item B<set_level>

    $writer->set_level( $compression_level );

Set the DEFLATE compression level to use (0-9). Available constants include
Z_NO_COMPRESSION, Z_BEST_SPEED, Z_DEFAULT_COMPRESSION, Z_BEST_COMPRESSION
(defaults to Z_DEFAULT_COMPRESSION). The author's observations suggest that
the default is reasonable unless speed is of the essence, in which case
setting a level of 1-2 can sometimes halve the compression time.

=item B<set_write_eof>

    $writer->set_write_eof;    # turn on
    $writer->set_write_eof(1); # turn on
    $writer->set_write_eof(0); # turn off