内容

• 名称
• 语法
• 描述
• 功能接口
  • anyinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]
    • $input_filename_or_reference 参数
    • $output_filename_or_reference 参数
  • 备注
  • 可选参数
  • 示例
• OO 接口
  • 构造函数
  • 构造函数选项
  • 示例
• 方法
  • read
  • read
  • getline
  • getc
  • ungetc
  • inflateSync
  • getHeaderInfo
  • tell
  • eof
  • seek
  • binmode
  • opened
  • autoflush
  • input_line_number
  • fileno
  • close
  • nextStream
  • trailingData
• 导入
• 示例
  • 使用 Net::FTP
• 支持
• 另请参见
• 作者
• 修改历史记录
• 版权和许可证

#名称

IO::Uncompress::AnyInflate - 解压缩基于 zlib（zip、gzip）的文件/缓冲区

#语法

use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;

my $status = anyinflate $input => $output [,OPTS]
    or die "anyinflate failed: $AnyInflateError\n";

my $z = IO::Uncompress::AnyInflate->new( $input [OPTS] )
    or die "anyinflate failed: $AnyInflateError\n";

$status = $z->read($buffer)
$status = $z->read($buffer, $length)
$status = $z->read($buffer, $length, $offset)
$line = $z->getline()
$char = $z->getc()
$char = $z->ungetc()
$char = $z->opened()

$status = $z->inflateSync()

$data = $z->trailingData()
$status = $z->nextStream()
$data = $z->getHeaderInfo()
$z->tell()
$z->seek($position, $whence)
$z->binmode()
$z->fileno()
$z->eof()
$z->close()

$AnyInflateError ;

# IO::File mode

<$z>
read($z, $buffer);
read($z, $buffer, $length);
read($z, $buffer, $length, $offset);
tell($z)
seek($z, $position, $whence)
binmode($z)
fileno($z)
eof($z)
close($z)

#说明

此模块提供了一个 Perl 接口，允许读取已使用 zlib 压缩库压缩的多种格式的文件/缓冲区。

支持的格式有

#RFC 1950

#RFC 1951（可选）

#gzip（RFC 1952）

#zip

该模块将自动检测正在使用的受支持压缩格式（如果存在）。

#功能接口

提供了一个顶级函数 anyinflate，用于在缓冲区和/或文件之间进行“一次性”解压缩。有关解压缩过程的更精细控制，请参见 “OO 接口” 部分。

use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;

anyinflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
    or die "anyinflate failed: $AnyInflateError\n";

功能接口需要 Perl5.005 或更高版本。

#anyinflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]

anyinflate 至少需要两个参数，$input_filename_or_reference 和 $output_filename_or_reference，以及零个或多个可选参数（请参见 “可选参数”）

#$input_filename_or_reference 参数

参数 $input_filename_or_reference 用于定义压缩数据的来源。

它可以采用以下形式之一

#文件名

如果 $input_filename_or_reference 参数是一个简单的标量，则假定它是一个文件名。此文件将被打开以供读取，并且输入数据将从中读取。

#文件句柄

如果 $input_filename_or_reference 参数是一个文件句柄，则输入数据将从中读取。字符串 '-' 可用作标准输入的别名。

#标量引用

如果 $input_filename_or_reference 是一个标量引用，则输入数据将从 $$input_filename_or_reference 中读取。

#数组引用

如果 $input_filename_or_reference 是一个数组引用，则数组中的每个元素都必须是一个文件名。

输入数据将依次从每个文件中读取。

在解压缩任何数据之前，将遍历整个数组以确保它只包含有效的文件名。

#输入文件通配符字符串

如果$input_filename_or_reference是一个以字符“<”和“>”为分隔符的字符串，anyinflate将假定它是一个输入文件通配符字符串。输入是与文件通配符匹配的文件列表。

有关更多详细信息，请参见File::GlobMapper。

如果$input_filename_or_reference参数是任何其他类型，将返回undef。

#$output_filename_or_reference参数

参数$output_filename_or_reference用于控制未压缩数据的目标。此参数可以采用以下形式之一。

#文件名

如果$output_filename_or_reference参数是一个简单的标量，则假定它是一个文件名。将打开此文件进行写入，并将未压缩的数据写入其中。

#文件句柄

如果$output_filename_or_reference参数是一个文件句柄，则未压缩的数据将写入其中。字符串“-”可以用作标准输出的别名。

#标量引用

如果$output_filename_or_reference是一个标量引用，则未压缩的数据将存储在$$output_filename_or_reference中。

#数组引用

如果$output_filename_or_reference是一个数组引用，则未压缩的数据将推送到数组中。

#输出文件通配符

如果$output_filename_or_reference是一个以字符“<”和“>”为分隔符的字符串，anyinflate将假定它是一个输出文件通配符字符串。输出是与文件通配符匹配的文件列表。

当$output_filename_or_reference是一个文件通配符字符串时，$input_filename_or_reference也必须是一个文件通配符字符串。其他任何内容都是错误的。

有关更多详细信息，请参见File::GlobMapper。

如果$output_filename_or_reference参数是任何其他类型，将返回undef。

#注释

当$input_filename_or_reference映射到多个压缩文件/缓冲区，并且$output_filename_or_reference是单个文件/缓冲区时，在解压缩后，$output_filename_or_reference将包含来自每个输入文件/缓冲区的所有未压缩数据的连接。

#可选参数

一次性函数 anyinflate 的可选参数（大部分）与 “构造函数选项” 部分中定义的 OO 接口所用的参数相同。例外情况如下

#AutoClose => 0|1

此选项适用于 anyinflate 的任何输入或输出数据流，这些数据流是文件句柄。

如果指定了 AutoClose，并且值为 true，则在 anyinflate 完成后，所有输入和/或输出文件句柄都将关闭。

此参数默认为 0。

#BinModeOut => 0|1

此选项现在为 no-op。所有文件都将以二进制模式写入。

#Append => 0|1

此选项的行为取决于输出数据流的类型。

• 缓冲区

  如果启用了 Append，所有未压缩数据都将附加到输出缓冲区的末尾。否则，在向输出缓冲区写入任何未压缩数据之前，将清除输出缓冲区。

• 文件名

  如果启用了 Append，文件将以追加模式打开。否则，在向其中写入任何未压缩数据之前，将截断文件（如果有）的内容。

• 文件句柄

  如果启用了 Append，在向其中写入任何未压缩数据之前，将通过调用 seek 将文件句柄定位到文件的末尾。否则，文件指针将不会移动。

当指定 Append 并将其设置为 true 时，它将把所有未压缩数据附加到输出数据流。

因此，当输出是文件句柄时，它将在写入任何未压缩数据之前执行对 eof 的搜索。如果输出是文件名，它将打开以进行追加。如果输出是缓冲区，所有未压缩数据都将附加到现有缓冲区。

相反，当未指定 Append，或存在且设置为 false 时，它将按如下方式操作。

当输出为文件名时，它将在写入任何未压缩数据之前截断文件的内容。如果输出为文件句柄，则其位置不会改变。如果输出为缓冲区，则在输出任何未压缩数据之前将其擦除。

默认为 0。

#MultiStream => 0|1

如果输入文件/缓冲区包含多个压缩数据流，此选项将把所有内容解压缩为单个数据流。

默认为 0。

#TrailingData => $scalar

解压缩完成后，返回紧跟在压缩数据流后的任何数据（如果有）。

当压缩数据流后面紧跟有用信息，并且您不知道压缩数据流的长度时，可以使用此选项。

如果输入是缓冲区，trailingData 将返回从压缩数据流末尾到缓冲区末尾的所有内容。

如果输入是文件句柄，trailingData 将返回压缩数据流末尾到达后文件句柄输入缓冲区中剩余的数据。然后，您可以使用文件句柄读取输入文件的其余部分。

如果输入是文件名，请不要使用 trailingData。

如果您在开始解压缩之前知道压缩数据流的长度，可以通过设置 InputLength 选项来避免使用 trailingData。

#示例

读取文件 file1.txt.Compressed 的内容并将解压缩数据写入文件 file1.txt。

use strict ;
use warnings ;
use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;

my $input = "file1.txt.Compressed";
my $output = "file1.txt";
anyinflate $input => $output
    or die "anyinflate failed: $AnyInflateError\n";

从现有 Perl 文件句柄 $input 读取并解压缩数据到缓冲区 $buffer。

use strict ;
use warnings ;
use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
use IO::File ;

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

解压缩目录 "/my/home" 中所有匹配 "*.txt.Compressed" 的文件并将压缩数据存储在同一目录中

use strict ;
use warnings ;
use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;

anyinflate '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
    or die "anyinflate failed: $AnyInflateError\n";

如果您想一次压缩每个文件，这将奏效

use strict ;
use warnings ;
use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;

for my $input ( glob "/my/home/*.txt.Compressed" )
{
    my $output = $input;
    $output =~ s/.Compressed// ;
    anyinflate $input => $output
        or die "Error compressing '$input': $AnyInflateError\n";
}

#OO 接口

#构造函数

IO::Uncompress::AnyInflate 的构造函数格式如下所示

my $z = IO::Uncompress::AnyInflate->new( $input [OPTS] )
    or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\n";

成功时返回 IO::Uncompress::AnyInflate 对象，失败时返回 undef。变量 $AnyInflateError 将在失败时包含错误消息。

如果您运行的是 Perl 5.005 或更高版本，从 IO::Uncompress::AnyInflate 返回的对象 $z 可以完全像 IO::File 文件句柄一样使用。这意味着可以使用 $z 执行所有正常的输入文件操作。例如，要从压缩文件/缓冲区读取一行，您可以使用以下任一形式

$line = $z->getline();
$line = <$z>;

强制参数 $input 用于确定压缩数据的来源。此参数可以采用三种形式之一。

#文件名

如果 $input 参数是标量，则假定它是一个文件名。此文件将被打开以供读取，并且压缩数据将从中读取。

#文件句柄

如果 $input 参数是文件句柄，则压缩数据将从中读取。字符串 '-' 可用作标准输入的别名。

#标量引用

如果 $input 是标量引用，则压缩数据将从 $$input 读取。

#构造函数选项

下面定义的选项名称不区分大小写，并且可以根据需要以 '-' 为前缀。因此，以下所有内容都是有效的

-AutoClose
-autoclose
AUTOCLOSE
autoclose

OPTS 是以下选项的组合

#AutoClose => 0|1

此选项仅在 $input 参数是文件句柄时才有效。如果指定，并且值为 true，则在调用 close 方法或销毁 IO::Uncompress::AnyInflate 对象后，文件将被关闭。

此参数默认为 0。

#MultiStream => 0|1

允许将多个串联压缩流视为单个压缩流。一旦达到文件/缓冲区的末尾、遇到错误（过早的 eof、损坏的压缩数据）或流的末尾没有立即跟随另一个流的开头，解压缩将停止。

此参数默认为 0。

#Prime => $string

此选项将在处理输入文件/缓冲区之前解压缩 $string 的内容。

当压缩数据嵌入在另一个文件/数据结构中并且无法在不读取前几个字节的情况下确定压缩数据开始的位置时，此选项可能很有用。如果是这种情况，则可以使用此选项使用这些字节对解压缩进行“预处理”。

#Transparent => 0|1

如果设置此选项并且输入文件/缓冲区不是压缩数据，则该模块将允许读取它。

此外，如果输入文件/缓冲区确实包含压缩数据，并且紧随其后的是非压缩数据，则设置此选项将使此模块将整个文件/缓冲区视为单个数据流。

此选项默认为 1。

#BlockSize => $num

在读取压缩的输入数据时，IO::Uncompress::AnyInflate 将以 $num 字节的块读取它。

此选项默认为 4096。

#InputLength => $size

此选项存在时，将限制从输入文件/缓冲区读取的压缩字节数，为 $size。此选项可用于压缩数据流后紧跟有用数据的情况，并且您事先知道压缩数据流的确切长度。

此选项主要用于从文件句柄读取时，在这种情况下，文件指针将指向压缩数据流后紧跟的第一个字节。

此选项默认为关闭。

#Append => 0|1

此选项控制 read 方法对未压缩数据执行的操作。

如果设置为 1，所有未压缩数据将附加到 read 方法的输出参数。

如果设置为 0，read 方法的输出参数的内容将被未压缩数据覆盖。

默认为 0。

#Strict => 0|1

此选项控制在执行解压缩时是否使用下面定义的额外检查。当 Strict 打开时，将执行额外测试，当 Strict 关闭时，将不执行额外测试。

此选项的默认值为关闭。

如果输入是 RFC 1950 数据流，将检查以下内容

1. ADLER32 校验和字段必须存在。

2. 读取的 ADLER32 字段值必须与文件中实际包含的未压缩数据的 adler32 值匹配。

如果输入是 gzip (RFC 1952) 数据流，将检查以下内容

1. 如果 gzip FLG 头字节中设置了 FHCRC 位，则头中的 CRC16 字节必须与实际读取的 gzip 头的 crc16 值匹配。

2. 如果 gzip 头包含名称字段 (FNAME)，则它仅由 ISO 8859-1 字符组成。

3. 如果 gzip 头包含注释字段 (FCOMMENT)，则它仅由 ISO 8859-1 字符和换行符组成。

4. 如果存在 gzip FEXTRA 头字段，则它必须符合 RFC 1952 中定义的子字段结构。

5. 必须存在 CRC32 和 ISIZE 尾部字段。

6. 读取的 CRC32 字段值必须与 gzip 文件中实际包含的未压缩数据的 crc32 值相匹配。

7. 读取的 ISIZE 字段值必须与从文件中实际读取的未压缩数据的长度相匹配。

#RawInflate => 0|1

在自动检测压缩格式时，尝试使用 IO::Uncompress::RawInflate 模块测试 raw-deflate (RFC 1951) 内容。

之所以不是默认行为，是因为 RFC 1951 内容只能通过尝试解压缩来检测。此过程容易出错，并且可能导致误报。

默认为 0。

#ParseExtra => 0|1 如果存在 gzip FEXTRA 头字段且设置了此选项，它将强制模块检查它是否符合 RFC 1952 中定义的子字段结构。

如果 Strict 处于启用状态，它将自动启用此选项。

默认为 0。

#示例

TODO

#方法

#read

用法为

$status = $z->read($buffer)

读取一个压缩数据块（压缩块的大小由构造函数中的 Buffer 选项决定），解压缩它并将任何未压缩的数据写入 $buffer。如果在构造函数中设置了 Append 参数，未压缩的数据将附加到 $buffer 参数。否则将覆盖 $buffer。

返回写入 $buffer 的未压缩字节数，如果为 eof 或出现错误则返回零或负数。

#read

用法为

$status = $z->read($buffer, $length)
$status = $z->read($buffer, $length, $offset)

$status = read($z, $buffer, $length)
$status = read($z, $buffer, $length, $offset)

尝试将 $length 字节的未压缩数据读入 $buffer。

此形式的 read 方法与前一个方法的主要区别在于，此方法将尝试返回 正好 $length 字节。此函数不执行此操作的唯一情况是遇到文件结尾或 IO 错误。

返回写入 $buffer 的未压缩字节数，如果为 eof 或出现错误则返回零或负数。

#getline

用法为

$line = $z->getline()
$line = <$z>

读取一行。

此方法完全支持使用变量 $/（或在使用 English 时使用 $INPUT_RECORD_SEPARATOR 或 $RS）来确定什么是行尾。段落模式、记录模式和文件吸入模式都受支持。

#getc

用法为

$char = $z->getc()

读取单个字符。

#ungetc

用法为

$char = $z->ungetc($string)

#inflateSync

用法为

$status = $z->inflateSync()

TODO

#getHeaderInfo

用法为

$hdr  = $z->getHeaderInfo();
@hdrs = $z->getHeaderInfo();

此方法返回哈希引用（在标量上下文中）或哈希引用的列表或哈希（在数组上下文中），其中包含有关压缩数据流中每个标头字段的信息。

#tell

用法为

$z->tell()
tell $z

返回未压缩的文件偏移量。

#eof

用法为

$z->eof();
eof($z);

如果已达到压缩输入流的末尾，则返回 true。

#seek

$z->seek($position, $whence);
seek($z, $position, $whence);

提供 seek 功能的子集，限制条件是只能在输入文件/缓冲区中向前查找。尝试向后查找将导致致命错误。

请注意，此模块中 seek 的实现不提供对压缩文件/缓冲区的真正随机访问。它的工作原理是从文件/缓冲区中的当前偏移量解压缩数据，直到达到 seek 参数中指定的未压缩偏移量。对于非常小的文件，这可能是一种可接受的行为。对于大文件，可能会造成不可接受的延迟。

$whence 参数采用通常值之一，即 SEEK_SET、SEEK_CUR 或 SEEK_END。

成功时返回 1，失败时返回 0。

#binmode

用法为

$z->binmode
binmode $z ;

这是一个为完整性而提供的空操作。

#opened

$z->opened()

如果对象当前引用已打开的文件/缓冲区，则返回 true。

#autoflush

my $prev = $z->autoflush()
my $prev = $z->autoflush(EXPR)

如果 $z 对象与文件或文件句柄关联，则此方法将返回底层文件句柄的当前自动刷新设置。如果 EXPR 存在且非零，它将在每次写入/打印操作后启用刷新。

如果 $z 与缓冲区关联，则此方法无效，并且始终返回 undef。

注意，特殊变量 $| 不能用于设置或检索自动刷新设置。

#input_line_number

$z->input_line_number()
$z->input_line_number(EXPR)

返回当前未压缩的行号。如果 EXPR 存在，则它具有设置行号的效果。请注意，设置行号不会更改正在读取的文件/缓冲区中的当前位置。

$/ 的内容用于确定什么构成行终止符。

#fileno

$z->fileno()
fileno($z)

如果 $z 对象与文件或文件句柄关联，则 fileno 将返回底层文件描述符。一旦调用 close 方法，fileno 将返回 undef。

如果 $z 对象与缓冲区关联，则此方法将返回 undef。

#关闭

$z->close() ;
close $z ;

关闭输出文件/缓冲区。

对于大多数版本的 Perl，如果 IO::Uncompress::AnyInflate 对象被销毁（显式地或通过引用该对象的变量超出范围），此方法将自动调用。例外情况是 Perl 版本 5.005 到 5.00504 和 5.8.0。在这些情况下，close 方法将自动调用，但直到程序终止时所有活动对象全局销毁时才调用。

因此，如果你希望你的脚本能够在所有版本的 Perl 上运行，你应该显式调用 close，而不是依赖自动关闭。

成功时返回 true，否则返回 0。

如果在创建 IO::Uncompress::AnyInflate 对象时启用了 AutoClose 选项，并且该对象与文件关联，则基础文件也将关闭。

#nextStream

用法为

my $status = $z->nextStream();

跳到输入文件/缓冲区中的下一个压缩数据流。如果找到新的压缩数据流，eof 标记将被清除，$. 将重置为 0。

如果找到新流，则返回 1；如果未找到，则返回 0；如果遇到错误，则返回 -1。

#trailingData

用法为

my $data = $z->trailingData();

解压缩完成后，返回压缩数据流之后立即存在的数据（如果有）。只有在遇到压缩数据流的末尾后调用此方法才有意义。

当压缩数据流后面紧跟有用信息，并且您不知道压缩数据流的长度时，可以使用此选项。

如果输入是缓冲区，trailingData 将返回从压缩数据流末尾到缓冲区末尾的所有内容。

如果输入是文件句柄，trailingData 将返回压缩数据流末尾到达后文件句柄输入缓冲区中剩余的数据。然后，您可以使用文件句柄读取输入文件的其余部分。

如果输入是文件名，请不要使用 trailingData。

如果你在开始解压缩之前知道压缩数据流的长度，你可以通过在构造函数中设置 InputLength 选项来避免使用 trailingData。

#导入

目前 IO::Uncompress::AnyInflate 不需要任何符号常量。

#:all

导入 anyinflate 和 $AnyInflateError。与执行以下操作相同

use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;

#示例

#与 Net::FTP 配合使用

参见 IO::Compress::FAQ

#支持

应将一般反馈/问题/错误报告发送到 https://github.com/pmqs/IO-Compress/issues（首选）或 https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress。

#另请参见

Compress::Zlib、IO::Compress::Gzip、IO::Uncompress::Gunzip、IO::Compress::Deflate、IO::Uncompress::Inflate、IO::Compress::RawDeflate、IO::Uncompress::RawInflate、IO::Compress::Bzip2、IO::Uncompress::Bunzip2、IO::Compress::Lzma、IO::Uncompress::UnLzma、IO::Compress::Xz、IO::Uncompress::UnXz、IO::Compress::Lzip、IO::Uncompress::UnLzip、IO::Compress::Lzop、IO::Uncompress::UnLzop、IO::Compress::Lzf、IO::Uncompress::UnLzf、IO::Compress::Zstd、IO::Uncompress::UnZstd、IO::Uncompress::AnyUncompress

IO::Compress::FAQ

File::GlobMapper、Archive::Zip、Archive::Tar、IO::Zlib

有关 RFC 1950、1951 和 1952，请参阅 https://datatracker.ietf.org/doc/html/rfc1950、https://datatracker.ietf.org/doc/html/rfc1951 和 https://datatracker.ietf.org/doc/html/rfc1952

zlib 压缩库由 Jean-loup Gailly [email protected] 和 Mark Adler [email protected] 编写。

zlib 压缩库的主要网站是 http://www.zlib.org。

zlib-ng 压缩库的主要网站是 https://github.com/zlib-ng/zlib-ng。

gzip 的主要网站是 http://www.gzip.org。

#作者

此模块由 Paul Marquess 编写，[email protected]。

#修改历史

请参阅 Changes 文件。

#版权和许可

版权所有 (c) 2005-2023 Paul Marquess。保留所有权利。

此程序是免费软件；您可以在与 Perl 相同的条款下重新分发和/或修改它。

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如有任何关于网站本身、搜索或文档呈现的问题，请通过 GitHub 问题跟踪器 或 电子邮件 联系他。

Perl 文档由 Perl 5 Porters 在 Perl 开发中维护。如有任何关于文档内容或格式的问题，请通过 Perl 问题跟踪器、邮件列表 或 IRC 联系他们。