view release on metacpan or  search on metacpan

lib/IO/Compress/Lzop.pm  view on Meta::CPAN

This parameter defaults to 0.

=item C<< BinModeIn => 0|1 >>

This option is now a no-op. All files will be read in binmode.

=item C<< Append => 0|1 >>

The behaviour of this option is dependent on the type of output data
stream.

=over 5

=item * A Buffer

If C<Append> is enabled, all compressed data will be append to the end of
the output buffer. Otherwise the output buffer will be cleared before any
compressed data is written to it.

=item * A Filename

If C<Append> is enabled, the file will be opened in append mode. Otherwise
the contents of the file, if any, will be truncated before any compressed
data is written to it.

=item * A Filehandle

If C<Append> is enabled, the filehandle will be positioned to the end of
the file via a call to C<seek> before any compressed data is
written to it.  Otherwise the file pointer will not be moved.

=back

When C<Append> is specified, and set to true, it will I<append> all compressed
data to the output data stream.

So when the output is a filehandle it will carry out a seek to the eof
before writing any compressed data. If the output is a filename, it will be opened for
appending. If the output is a buffer, all compressed data will be
appended to the existing buffer.

Conversely when C<Append> is not specified, or it is present and is set to
false, it will operate as follows.

When the output is a filename, it will truncate the contents of the file
before writing any compressed data. If the output is a filehandle
its position will not be changed. If the output is a buffer, it will be
wiped before any compressed data is output.

Defaults to 0.

=back

=head2 Oneshot Examples

Here are a few example that show the capabilities of the module.

=head3 Streaming

This very simple command line example demonstrates the streaming capabilities of the module.
The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.

    $ echo hello world | perl -MIO::Compress::Lzop=lzop -e 'lzop \*STDIN => \*STDOUT' >output.lzo

The special filename "-" can be used as a standin for both C<\*STDIN> and C<\*STDOUT>,
so the above can be rewritten as

    $ echo hello world | perl -MIO::Compress::Lzop=lzop -e 'lzop "-" => "-"' >output.lzo

=head3 Compressing a file from the filesystem

To read the contents of the file C<file1.txt> and write the compressed
data to the file C<file1.txt.lzo>.

    use strict ;
    use warnings ;
    use IO::Compress::Lzop qw(lzop $LzopError) ;

    my $input = "file1.txt";
    lzop $input => "$input.lzo"
        or die "lzop failed: $LzopError\n";

=head3 Reading from a Filehandle and writing to an in-memory buffer

To read from an existing Perl filehandle, C<$input>, and write the
compressed data to a buffer, C<$buffer>.

    use strict ;
    use warnings ;
    use IO::Compress::Lzop qw(lzop $LzopError) ;
    use IO::File ;

    my $input = IO::File->new( "<file1.txt" )
        or die "Cannot open 'file1.txt': $!\n" ;
    my $buffer ;
    lzop $input => \$buffer
        or die "lzop failed: $LzopError\n";

=head3 Compressing multiple files

To compress all files in the directory "/my/home" that match "*.txt"
and store the compressed data in the same directory

    use strict ;
    use warnings ;
    use IO::Compress::Lzop qw(lzop $LzopError) ;

    lzop '</my/home/*.txt>' => '<*.lzo>'
        or die "lzop failed: $LzopError\n";

and if you want to compress each file one at a time, this will do the trick

    use strict ;
    use warnings ;
    use IO::Compress::Lzop qw(lzop $LzopError) ;

    for my $input ( glob "/my/home/*.txt" )
    {
        my $output = "$input.lzo" ;
        lzop $input => $output

lib/IO/Compress/Lzop.pm  view on Meta::CPAN

If C<$output> is a filename and C<Append> is enabled, the file will be
opened in append mode. Otherwise the contents of the file, if any, will be
truncated before any compressed data is written to it.

=item * A Filehandle

If C<$output> is a filehandle, the file pointer will be positioned to the
end of the file via a call to C<seek> before any compressed data is written
to it.  Otherwise the file pointer will not be moved.

=back

This parameter defaults to 0.

=item C<< Name => $string >>

Stores the contents of C<$string> in the name field lzop header.

If C<Name> is not specified, no gzip NAME field will be created.

=item C<< Time => $number >>

Sets the Time field in the lzop header to $number.

This field defaults to the time the C<IO::Compress::Lzop> object was created
if this option is not specified.

=item Extra

TODO

=item BlockSize

TODO

=item Optimize

TODO

=item Minimal

Creates the smallest possible lzop file/buffer.

Disables the creation of all checksums.

No Name is stored.

TODO

=item C<< Strict => 0|1 >>

This is a placeholder option.

=back

=head2 Examples

=head3 Streaming

This very simple command line example demonstrates the streaming capabilities
of the module. The code reads data from STDIN or all the files given on the
commandline, compresses it, and writes the compressed data to STDOUT.

    use strict ;
    use warnings ;
    use IO::Compress::Lzop qw(lzop $LzopError) ;

    my $z = IO::Compress::Lzop->new("-", Stream => 1)
        or die "IO::Compress::Lzop failed: $LzopError\n";

    while (<>) {
        $z->print("abcde");
    }
    $z->close();

Note the use of C<"-"> to means C<STDOUT>. Alternatively you can use C<\*STDOUT>.

=head3 Compressing a file from the filesystem

To read the contents of the file C<file1.txt> and write the compressed
data to the file C<file1.txt.lzo> there are a few options

Start by creating the compression object and opening the input file

    use strict ;
    use warnings ;
    use IO::Compress::Lzop qw(lzop $LzopError) ;

    my $input = "file1.txt";
    my $z = IO::Compress::Lzop->new("file1.txt.lzo")
        or die "IO::Compress::Lzop failed: $LzopError\n";

    # open the input file
    open my $fh, "<", "file1.txt"
        or die "Cannot open file1.txt: $!\n";

    # loop through the input file & write to the compressed file
    while (<$fh>) {
        $z->print($_);
    }

    # not forgetting to close the compressed file
    $z->close();

=head1 Methods

=head2 print

Usage is

    $z->print($data)
    print $z $data

Compresses and outputs the contents of the C<$data> parameter. This
has the same behaviour as the C<print> built-in.

Returns true if successful.

=head2 printf