内容

• 名称
• 概要
• 描述
• 函数式接口
  • rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]
    • $input_filename_or_reference 参数
    • $output_filename_or_reference 参数
  • 注意
  • 可选参数
  • 示例
    • 流式处理
    • 压缩文件系统中的文件
    • 从文件句柄读取并写入内存缓冲区
    • 压缩多个文件
• 面向对象接口
  • 构造函数
  • 构造函数选项
  • 示例
• 方法
  • print
  • printf
  • syswrite
  • write
  • flush
  • tell
  • eof
  • seek
  • binmode
  • opened
  • autoflush
  • input_line_number
  • fileno
  • close
  • newStream([OPTS])
  • deflateParams
• 导入
• 示例
  • Apache::GZip 再探
  • 使用 Net::FTP
• 支持
• 参见
• 作者
• 修改历史
• 版权和许可

#名称

IO::Compress::RawDeflate - 编写 RFC 1951 文件/缓冲区

#概要

use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

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

my $z = IO::Compress::RawDeflate->new( $output [,OPTS] )
    or die "rawdeflate failed: $RawDeflateError\n";

$z->print($string);
$z->printf($format, $string);
$z->write($string);
$z->syswrite($string [, $length, $offset]);
$z->flush();
$z->tell();
$z->eof();
$z->seek($position, $whence);
$z->binmode();
$z->fileno();
$z->opened();
$z->autoflush();
$z->input_line_number();
$z->newStream( [OPTS] );

$z->deflateParams();

$z->close() ;

$RawDeflateError ;

# IO::File mode

print $z $string;
printf $z $format, $string;
tell $z
eof $z
seek $z, $position, $whence
binmode $z
fileno $z
close $z ;

#描述

此模块提供了一个 Perl 接口，允许根据 RFC 1951 将压缩数据写入文件或缓冲区。

请注意，RFC 1951 数据不是一个好的独立压缩格式选择，尤其是在您想要自动检测它时。

要读取 RFC 1951 文件/缓冲区，请参见配套模块 IO::Uncompress::RawInflate。

#函数式接口

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

use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

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

函数式接口需要 Perl5.005 或更高版本。

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

rawdeflate 至少需要两个参数，$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 是一个由字符 "<" 和 ">" 分隔的字符串，rawdeflate 将假定它是一个输入文件通配符字符串。输入是与文件通配符匹配的文件列表。

有关更多详细信息，请参阅 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 是一个由字符 "<" 和 ">" 分隔的字符串，rawdeflate 将假定它是一个输出文件通配符字符串。输出是与文件通配符匹配的文件列表。

当 $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中。

#可选参数

一次性函数rawdeflate的可选参数（在很大程度上）与在"构造函数选项"部分中定义的OO接口中使用的参数相同。例外情况列在下面

#AutoClose => 0|1

此选项适用于任何作为文件句柄的rawdeflate输入或输出数据流。

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

此参数默认为 0。

#BinModeIn => 0|1

此选项现在是一个空操作。所有文件都将以二进制模式读取。

#Append => 0|1

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

• 缓冲区

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

• 文件名

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

• 文件句柄

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

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

因此，当输出是文件句柄时，它将在写入任何压缩数据之前执行 seek 到文件末尾的操作。如果输出是文件名，它将以追加模式打开。如果输出是缓冲区，所有压缩数据都将追加到现有缓冲区。

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

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

默认为 0。

#示例

以下是一些示例，展示了该模块的功能。

#流式传输

这个非常简单的命令行示例演示了该模块的流式传输功能。代码从 STDIN 读取数据，压缩数据，并将压缩后的数据写入 STDOUT。

$ echo hello world | perl -MIO::Compress::RawDeflate=rawdeflate -e 'rawdeflate \*STDIN => \*STDOUT' >output.1951

特殊文件名 "-" 可用作 \*STDIN 和 \*STDOUT 的占位符，因此上述代码可以改写为

$ echo hello world | perl -MIO::Compress::RawDeflate=rawdeflate -e 'rawdeflate "-" => "-"' >output.1951

#从文件系统压缩文件

要读取文件 file1.txt 的内容并将压缩后的数据写入文件 file1.txt.1951。

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

my $input = "file1.txt";
rawdeflate $input => "$input.1951"
    or die "rawdeflate failed: $RawDeflateError\n";

#从文件句柄读取并写入内存缓冲区

要从现有的 Perl 文件句柄 $input 读取数据，并将压缩后的数据写入缓冲区 $buffer。

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
use IO::File ;

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

#压缩多个文件

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

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

rawdeflate '</my/home/*.txt>' => '<*.1951>'
    or die "rawdeflate failed: $RawDeflateError\n";

如果您想一次压缩一个文件，这将起作用

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

for my $input ( glob "/my/home/*.txt" )
{
    my $output = "$input.1951" ;
    rawdeflate $input => $output
        or die "Error compressing '$input': $RawDeflateError\n";
}

#OO 接口

#构造函数

IO::Compress::RawDeflate 构造函数的格式如下所示

my $z = IO::Compress::RawDeflate->new( $output [,OPTS] )
    or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";

成功时返回一个 IO::Compress::RawDeflate 对象，失败时返回 undef。变量 $RawDeflateError 将在失败时包含错误消息。

如果您运行的是 Perl 5.005 或更高版本，则从 IO::Compress::RawDeflate 返回的对象 $z 可以像 IO::File 文件句柄一样使用。这意味着所有正常的输出文件操作都可以使用 $z 执行。例如，要写入压缩文件/缓冲区，您可以使用以下两种形式之一

$z->print("hello world\n");
print $z "hello world\n";

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

#文件名

如果 $output 参数是一个简单的标量，则假定它是一个文件名。此文件将被打开以供写入，压缩后的数据将被写入其中。

#文件句柄

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

#标量引用

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

如果 $output 参数是任何其他类型，IO::Compress::RawDeflate::new 将返回 undef。

#构造函数选项

OPTS 是以下选项的任意组合，可以是零个或多个

#AutoClose => 0|1

此选项仅在 $output 参数为文件句柄时有效。如果指定并且值为真，则当调用 close 方法或销毁 IO::Compress::RawDeflate 对象时，将导致关闭 $output。

此参数默认为 0。

#Append => 0|1

以追加模式打开 $output。

此选项的行为取决于 $output 的类型。

• 缓冲区

  如果 $output 是缓冲区并且启用了 Append，则所有压缩数据将追加到 $output 的末尾。否则，在写入任何数据之前，将清除 $output。

• 文件名

  如果 $output 是文件名并且启用了 Append，则将以追加模式打开文件。否则，在写入任何压缩数据之前，将截断文件的内容（如果有）。

• 文件句柄

  如果 $output 是文件句柄，则在写入任何压缩数据之前，将通过调用 seek 将文件指针定位到文件末尾。否则，文件指针将不会移动。

此参数默认为 0。

#Merge => 0|1

此选项用于压缩输入数据并将其追加到 $output 中现有的压缩数据流。最终结果是存储在 $output 中的单个压缩数据流。

如果 $output 不是 RFC 1951 数据流，则尝试使用此选项将导致致命错误。

Merge 选项有一些其他限制

1. 此模块需要使用 zlib 1.2.1 或更高版本才能正常工作。如果使用旧版本的 zlib 使用 Merge，则会抛出致命错误。

2. 如果 $output 是文件或文件句柄，则它必须是可寻址的。

此参数默认为 0。

#-Level

定义 zlib 使用的压缩级别。该值应为 0 到 9 之间的数字（0 表示不压缩，9 表示最大压缩），或以下定义的符号常量之一。

Z_NO_COMPRESSION
Z_BEST_SPEED
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION

默认值为 Z_DEFAULT_COMPRESSION。

注意，这些常量默认情况下不会由 IO::Compress::RawDeflate 导入。

use IO::Compress::RawDeflate qw(:strategy);
use IO::Compress::RawDeflate qw(:constants);
use IO::Compress::RawDeflate qw(:all);

#-策略

定义用于调整压缩的策略。使用下面定义的符号常量之一。

Z_FILTERED
Z_HUFFMAN_ONLY
Z_RLE
Z_FIXED
Z_DEFAULT_STRATEGY

默认值为 Z_DEFAULT_STRATEGY。

#Strict => 0|1

这是一个占位符选项。

#示例

待办事项

#方法

#print

用法是

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

压缩并输出$data参数的内容。这与print内置函数的行为相同。

如果成功，则返回 true。

#printf

用法是

$z->printf($format, $data)
printf $z $format, $data

压缩并输出$data参数的内容。

如果成功，则返回 true。

#syswrite

用法是

$z->syswrite $data
$z->syswrite $data, $length
$z->syswrite $data, $length, $offset

压缩并输出$data参数的内容。

返回写入的未压缩字节数，如果失败则返回undef。

#write

用法是

$z->write $data
$z->write $data, $length
$z->write $data, $length, $offset

压缩并输出$data参数的内容。

返回写入的未压缩字节数，如果失败则返回undef。

#flush

用法是

$z->flush;
$z->flush($flush_type);

将任何待处理的压缩数据刷新到输出文件/缓冲区。

此方法接受一个可选参数$flush_type，它控制刷新的执行方式。默认情况下，使用的$flush_type是Z_FINISH。$flush_type的其他有效值为Z_NO_FLUSH、Z_SYNC_FLUSH、Z_FULL_FLUSH和Z_BLOCK。强烈建议您仅在完全理解其含义的情况下才设置flush_type参数 - 过度使用flush会严重降低实现的压缩级别。有关详细信息，请参阅zlib文档。

成功时返回 true。

#tell

用法是

$z->tell()
tell $z

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

#eof

用法是

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

如果已调用close方法，则返回 true。

#seek

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

提供seek功能的子集，限制是仅允许在输出文件/缓冲区中向前搜索。尝试向后搜索是致命错误。

文件的空部分/缓冲区将写入 NULL (0x00) 字节。

$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)

此方法在压缩时始终返回undef。

#fileno

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

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

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

#close

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

刷新所有挂起的压缩数据，然后关闭输出文件/缓冲区。

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

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

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

如果在创建IO::Compress::RawDeflate对象时启用了AutoClose选项，并且对象与文件相关联，则底层文件也将被关闭。

#newStream([OPTS])

用法是

$z->newStream( [OPTS] )

关闭当前压缩数据流并开始一个新的数据流。

OPTS包含创建$z对象时可用的任何选项。

有关更多详细信息，请参阅"构造函数选项"部分。

#deflateParams

用法是

$z->deflateParams

待办事项

#Importing

IO::Compress::RawDeflate中的一些方法需要一些符号常量。默认情况下不导入任何常量。

#:all

导入rawdeflate、$RawDeflateError以及IO::Compress::RawDeflate可以使用的所有符号常量。与执行以下操作相同

use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;

#:constants

导入所有符号常量。与执行以下操作相同

use IO::Compress::RawDeflate qw(:flush :level :strategy) ;

#:flush

这些符号常量由flush方法使用。

Z_NO_FLUSH
Z_PARTIAL_FLUSH
Z_SYNC_FLUSH
Z_FULL_FLUSH
Z_FINISH
Z_BLOCK

#:level

这些符号常量由构造函数中的Level选项使用。

Z_NO_COMPRESSION
Z_BEST_SPEED
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION

#:strategy

这些符号常量由构造函数中的Strategy选项使用。

Z_FILTERED
Z_HUFFMAN_ONLY
Z_RLE
Z_FIXED
Z_DEFAULT_STRATEGY

#示例

#Apache::GZip 再探

参见 IO::Compress::FAQ

#使用 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::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::AnyInflate, 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 维护者在 Perl 开发过程中维护。如果您遇到文档内容或格式方面的任何问题，请通过 Perl 问题跟踪器、邮件列表 或 IRC 与他们联系。