NAME

Gzip::RandomAccess - extract arbitrary bits of a gzip stream

SYNOPSIS

  use Gzip::RandomAccess;

  my $gzip = Gzip::RandomAccess->new($filename);  # short version
  my $gzip = Gzip::RandomAccess->new(
    file => 'foo.gz',
    index_file => '.foo.gz.idx',
    cleanup => 1,  # delete index when out of scope
  );

  # Extract 1024 bytes from the 128th byte in
  print $gzip->extract(127, 1024), "\n";

DESCRIPTION

This module allows you to randomly access a gzip deflate stream as if it were a regular file, even though gzip is not designed to be random-access. This is achieved by streaming the gzip file in advance, building an index mapping compressed byte offsets to uncompressed offsets, and at each point storing the 32KB of data gzip needs to prime its decompression engine from that point.

The mechanism is taken from zran.c, an example in the zlib distribution; this module wraps it up in a nice XS Perl API and provides index creation and cleanup mechanisms.

METHODS

new ($filename)

new (%args)

Create a new Gzip::RandomAccess object. A single filename is accepted, otherwise the following options as a hash or hashref:

file (required)

Path to the gzip file you want to access.

index_file (default: "$file.idx")

Path to the index file to use, or create if it does not already exist. If not provided, defaults to adding '.idx' to the filename.

index_span (default: 1024*1024)

Override the number of bytes between indexing points. A smaller number creates a larger index but allows you to random-access larger files faster.

cleanup (default: 0)

If set to a true value, automatically deletes the index file when the object is destroyed.

extract ($offset, $length)

Return uncompressed content from the gzip stream of length $length from offset $offset (starting at 0).

build_index

Builds the gzip index, rebuilding if necessary. (Uncompresses the whole file - may be slow).

index_available

Returns a boolean indicating if the gzip index has been created.

uncompressed_size

Returns the total number of uncompressed bytes in the gzip stream. Unlike zcat --list the value is not modulo 4GB.

file

index_file

cleanup

Accessors for constructor arguments.

CAVEATS

Not tested on Windows, or with any compression method other than deflate.

AUTHOR

Richard Harris <richardjharris@gmail.com>

The libzran library included in this distribution is based on work by Iain Wade, subsequently based on zran.c by Mark Alder.

ZLIB LICENSE

 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages
 arising from the use of this software.

 Permission is granted to anyone to use this software for any purpose,
 including commercial applications, and to alter it and redistribute it
 freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.

cpanm Gzip::RandomAccess

perl -MCPAN -e shell
install Gzip::RandomAccess