248 lines
7.2 KiB
HTML
248 lines
7.2 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Dpkg::Compression::FileHandle</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Dpkg::Compression::FileHandle</H1>
|
|
Section: libdpkg-perl (3perl)<BR>Updated: 2020-03-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Dpkg::Compression::FileHandle - object dealing transparently with file compression
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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();
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
Dpkg::Compression::FileHandle is an object 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 behaviour with the method <TT>"set_compression"</TT>.
|
|
<P>
|
|
|
|
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 <TT>"set_filename"</TT> method).
|
|
<P>
|
|
|
|
Once a file has been opened, the filehandle must be closed before being
|
|
able to open another file.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>STANDARD FUNCTIONS</H2>
|
|
|
|
|
|
|
|
The standard functions acting on filehandles should accept a
|
|
Dpkg::Compression::FileHandle object transparently including
|
|
<TT>"open"</TT> (only when using the variant with 3 parameters), <TT>"close"</TT>,
|
|
<TT>"binmode"</TT>, <TT>"eof"</TT>, <TT>"fileno"</TT>, <TT>"getc"</TT>, <TT>"print"</TT>, <TT>"printf"</TT>, <TT>"read"</TT>,
|
|
<TT>"sysread"</TT>, <TT>"say"</TT>, <TT>"write"</TT>, <TT>"syswrite"</TT>, <TT>"seek"</TT>, <TT>"sysseek"</TT>, <TT>"tell"</TT>.
|
|
<P>
|
|
|
|
Note however that <TT>"seek"</TT> and <TT>"sysseek"</TT> will only work on uncompressed
|
|
files as compressed files are really pipes to the compressor programs
|
|
and you can't seek on a pipe.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>FileHandle METHODS</H2>
|
|
|
|
|
|
|
|
The object inherits from IO::File so all methods that work on this
|
|
object should work for Dpkg::Compression::FileHandle too. There
|
|
may be exceptions though.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>PUBLIC METHODS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">$fh = Dpkg::Compression::FileHandle->new(%opts)<DD>
|
|
|
|
|
|
|
|
|
|
Creates a new filehandle supporting on-the-fly compression/decompression.
|
|
Supported options are ``filename'', ``compression'', ``compression_level'' (see
|
|
respective set_* functions) and ``add_comp_ext''. If ``add_comp_ext''
|
|
evaluates 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.
|
|
<DT id="2">$fh->ensure_open($mode, %opts)<DD>
|
|
|
|
|
|
|
|
|
|
Ensure the file is opened in the requested mode (``r'' for read and ``w'' for
|
|
write). The options are passed down to the compressor's <B>spawn()</B> call, if one
|
|
is used. Opens the file with the recorded filename if needed. If the file
|
|
is already open but not in the requested mode, then it errors out.
|
|
<DT id="3">$fh->set_compression($comp)<DD>
|
|
|
|
|
|
|
|
|
|
Defines the compression method used. <TT>$comp</TT> should one of the methods supported by
|
|
<B>Dpkg::Compression</B> or ``none'' or ``auto''. ``none'' indicates that the file is
|
|
uncompressed and ``auto'' indicates that the method must be guessed based
|
|
on the filename extension used.
|
|
<DT id="4">$fh->set_compression_level($level)<DD>
|
|
|
|
|
|
|
|
|
|
Indicate the desired compression level. It should be a value accepted
|
|
by the function <TT>"compression_is_valid_level"</TT> of <B>Dpkg::Compression</B>.
|
|
<DT id="5">$fh->set_filename($name, [$add_comp_ext])<DD>
|
|
|
|
|
|
|
|
|
|
Use <TT>$name</TT> as filename when the file must be opened/created. If
|
|
<TT>$add_comp_ext</TT> is passed, it indicates whether the default extension
|
|
of the compression method must be automatically added to the filename
|
|
(or not).
|
|
<DT id="6">$file = $fh-><B>get_filename()</B><DD>
|
|
|
|
|
|
|
|
|
|
Returns the filename that would be used when the filehandle must
|
|
be opened (both in read and write mode). This function errors out
|
|
if ``add_comp_ext'' is enabled while the compression method is set
|
|
to ``auto''. The returned filename includes the extension of the compression
|
|
method if ``add_comp_ext'' is enabled.
|
|
<DT id="7">$ret = $fh-><B>use_compression()</B><DD>
|
|
|
|
|
|
|
|
|
|
Returns ``0'' if no compression is used and the compression method used
|
|
otherwise. If the compression is set to ``auto'', the value returned
|
|
depends on the extension of the filename obtained with the <B>get_filename</B>
|
|
method.
|
|
<DT id="8">$real_fh = $fh-><B>get_filehandle()</B><DD>
|
|
|
|
|
|
|
|
|
|
Returns the real underlying filehandle. Useful if you want to pass it
|
|
along in a derived object.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>DERIVED OBJECTS</H2>
|
|
|
|
|
|
|
|
If you want to create an object that inherits from
|
|
Dpkg::Compression::FileHandle you must be aware that
|
|
the object is a reference to a <FONT SIZE="-1">GLOB</FONT> that is returned by <B>Symbol::gensym()</B>
|
|
and as such it's not a <FONT SIZE="-1">HASH.</FONT>
|
|
<P>
|
|
|
|
You can store internal data in a hash but you have to use
|
|
<TT>"*$self-"</TT>{...}> to access the associated hash like in the example below:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
sub set_option {
|
|
my ($self, $value) = @_;
|
|
*$self->{option} = $value;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>CHANGES</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Version 1.01 (dpkg 1.17.11)</H3>
|
|
|
|
|
|
|
|
New argument: <TT>$fh</TT>-><B>ensure_open()</B> accepts an <TT>%opts</TT> argument.
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Version 1.00 (dpkg 1.15.6)</H3>
|
|
|
|
|
|
|
|
Mark the module as public.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="9"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="10"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="11"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="12"><A HREF="#lbAE">STANDARD FUNCTIONS</A><DD>
|
|
<DT id="13"><A HREF="#lbAF">FileHandle METHODS</A><DD>
|
|
<DT id="14"><A HREF="#lbAG">PUBLIC METHODS</A><DD>
|
|
<DT id="15"><A HREF="#lbAH">DERIVED OBJECTS</A><DD>
|
|
<DT id="16"><A HREF="#lbAI">CHANGES</A><DD>
|
|
<DL>
|
|
<DT id="17"><A HREF="#lbAJ">Version 1.01 (dpkg 1.17.11)</A><DD>
|
|
<DT id="18"><A HREF="#lbAK">Version 1.00 (dpkg 1.15.6)</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:38 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|