IO::Zlib - IO:: style interface to Compress::Zlib

With any version of Perl 5 you can use the basic OO interface:

    use IO::Zlib;

    $fh = new IO::Zlib;
    if ($fh->open("file.gz", "rb")) {
        print <$fh>;
        $fh->close;
    }

    $fh = IO::Zlib->new("file.gz", "wb9");
    if (defined $fh) {
        print $fh "bar\n";
        $fh->close;
    }

    $fh = IO::Zlib->new("file.gz", "rb");
    if (defined $fh) {
        print <$fh>;
        undef $fh;       # automatically closes the file
    }

With Perl 5.004 you can also use the TIEHANDLE interface to access compressed files just like ordinary files:

    use IO::Zlib;

    tie *FILE, 'IO::Zlib', "file.gz", "wb";
    print FILE "line 1\nline2\n";

    tie *FILE, 'IO::Zlib', "file.gz", "rb";
    while (<FILE>) { print "LINE: ", $_ };

CWIO::Zlib provides an IO:: style interface to Compress::Zlib and hence to gzip/zlib compressed files. It provides many of the same methods as the IO::Handle interface.

Starting from IO::Zlib version 1.02, IO::Zlib can also use an external gzip command. The default behaviour is to try to use an external gzip if no CWCompress::Zlib can be loaded, unless explicitly disabled by

    use IO::Zlib qw(:gzip_external 0);

If explicitly enabled by

    use IO::Zlib qw(:gzip_external 1);

then the external gzip is used instead of CWCompress::Zlib.

new ( [ARGS] )

Creates an CWIO::Zlib object. If it receives any parameters, they are passed to the method CWopen; if the open fails, the object is destroyed. Otherwise, it is returned to the caller.

open ( FILENAME, MODE )

CWopen takes two arguments. The first is the name of the file to open and the second is the open mode. The mode can be anything acceptable to Compress::Zlib and by extension anything acceptable to zlib (that basically means POSIX fopen() style mode strings plus an optional number to indicate the compression level).

opened

Returns true if the object currently refers to a opened file.

close

Close the file associated with the object and disassociate the file from the handle. Done automatically on destroy.

getc

Return the next character from the file, or undef if none remain.

getline

Return the next line from the file, or undef on end of string. Can safely be called in an array context. Currently ignores $/ ($INPUT_RECORD_SEPARATOR or CW$RS when English is in use) and treats lines as delimited by \n.

getlines

Get all remaining lines from the file. It will croak() if accidentally called in a scalar context.

print ( ARGS... )

Print ARGS to the file.

read ( BUF, NBYTES, [OFFSET] )

Read some bytes from the file. Returns the number of bytes actually read, 0 on end-of-file, undef on error.

eof

Returns true if the handle is currently positioned at end of file?

seek ( OFFSET, WHENCE )

Seek to a given position in the stream. Not yet supported.

tell

Return the current position in the stream, as a numeric offset. Not yet supported.

setpos ( POS )

Set the current position, using the opaque value returned by CWgetpos(). Not yet supported.

getpos ( POS )

Return the current position in the string, as an opaque object. Not yet supported.

If the external gzip is used, the following CWopens are used:

    open(FH, "gzip -dc $filename |")  # for read opens
    open(FH, " | gzip > $filename")   # for write opens

You can modify the 'commands' for example to hardwire an absolute path by e.g.

    use IO::Zlib ':gzip_read_open'  => '/some/where/gunzip -c %s |';
    use IO::Zlib ':gzip_write_open' => '| /some/where/gzip.exe > %s';

The CW%s is expanded to be the filename (CWsprintf is used, so be careful to escape any other CW% signs). The 'commands' are checked for sanity - they must contain the CW%s, and the read open must end with the pipe sign, and the write open must begin with the pipe sign.

has_Compress_Zlib

Returns true if CWCompress::Zlib is available. Note that this does not mean that CWCompress::Zlib is being used: see gzip_external and gzip_used.

gzip_external

Undef if an external gzip can be used if CWCompress::Zlib is not available (see has_Compress_Zlib), true if an external gzip is explicitly used, false if an external gzip must not be used. See gzip_used.

gzip_used

True if an external gzip is being used, false if not.

gzip_read_open

Return the 'command' being used for opening a file for reading using an external gzip.

gzip_write_open

Return the 'command' being used for opening a file for writing using an external gzip.

IO::Zlib::getlines: must be called in list context

If you want read lines, you must read in list context.

IO::Zlib::gzopen_external: mode '...' is illegal

Use only modes 'rb' or 'wb' or /wb[1-9]/.

IO::Zlib::import: '...' is illegal

The known import symbols are the CW:gzip_external, CW:gzip_read_open, and CW:gzip_write_open. Anything else is not recognized.

IO::Zlib::import: ':gzip_external' requires an argument

The CW:gzip_external requires one boolean argument.

IO::Zlib::import: 'gzip_read_open' requires an argument

The CW:gzip_external requires one string argument.

IO::Zlib::import: 'gzip_read' '...' is illegal

The CW:gzip_read_open argument must end with the pipe sign (|) and have the CW%s for the filename. See USING THE EXTERNAL GZIP.

IO::Zlib::import: 'gzip_write_open' requires an argument

The CW:gzip_external requires one string argument.

IO::Zlib::import: 'gzip_write_open' '...' is illegal

The CW:gzip_write_open argument must begin with the pipe sign (|) and have the CW%s for the filename. An output redirect (>) is also often a good idea, depending on your operating system shell syntax. See USING THE EXTERNAL GZIP.

IO::Zlib::import: no Compress::Zlib and no external gzip

Given that we failed to load CWCompress::Zlib and that the use of an external gzip was disabled, IO::Zlib has not much chance of working.

IO::Zlib::open: needs a filename

No filename, no open.

IO::Zlib::READ: NBYTES must be specified

We must know how much to read.

IO::Zlib::READ: OFFSET is not supported

Offsets of gzipped streams are not supported.

IO::Zlib::WRITE: too long LENGTH

The LENGTH must be less than or equal to the buffer size.

IO::Zlib::WRITE: OFFSET is not supported

Offsets of gzipped streams are not supported.

perlfunc, I/O Operators in perlop, IO::Handle, Compress::Zlib

Created by Tom Hughes <tom@compton.nu>.

Support for external gzip added by Jarkko Hietaniemi <jhi@iki.fi>.

Copyright (c) 1998-2004 Tom Hughes <tom@compton.nu>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.