内容

• 名称
• 概要
• 说明
• 功能接口
  • bzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]
    • $input_filename_or_reference 参数
    • $output_filename_or_reference 参数
  • 注释
  • 可选参数
  • 示例
    • 流式传输
    • 从文件系统压缩文件
    • 从文件句柄读取并写入内存缓冲区
    • 压缩多个文件
• OO 接口
  • 构造函数
  • 构造函数选项
  • 示例
• 方法
  • print
  • printf
  • syswrite
  • write
  • flush
  • tell
  • eof
  • seek
  • binmode
  • opened
  • autoflush
  • input_line_number
  • fileno
  • close
  • newStream([OPTS])
• 导入
• 示例
  • Apache::GZip 重新审视
  • 使用 Net::FTP
• 支持
• 另请参见
• 作者
• 修改历史
• 版权和许可

#名称

IO::Compress::Bzip2 - 编写 bzip2 文件/缓冲区

#SYNOPSIS

use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

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

my $z = IO::Compress::Bzip2->new( $output [,OPTS] )
    or die "bzip2 failed: $Bzip2Error\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->close() ;

$Bzip2Error ;

# IO::File mode

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

#DESCRIPTION

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

有关读取 bzip2 文件/缓冲区的信息，请参阅配套模块 IO::Uncompress::Bunzip2。

#Functional Interface

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

use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

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

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

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

bzip2 至少需要两个参数，$input_filename_or_reference 和 $output_filename_or_reference，以及零个或更多个可选参数（请参阅 "Optional Parameters"）

#The $input_filename_or_reference parameter

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

它可以采用以下形式之一

#A filename

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

#A filehandle

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

#A scalar reference

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

#An array reference

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

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

将遍历整个数组以确保它仅包含有效文件名，然后再压缩任何数据。

#An Input FileGlob string

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

有关更多详细信息，请参阅 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 是数组引用，则压缩数据将被推送到数组中。

#输出文件 Glob

如果 $output_filename_or_reference 是由字符 "<" 和 ">" 分隔的字符串，则 bzip2 将假定它是一个输出文件 Glob 字符串。输出是与文件 Glob 匹配的文件列表。

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

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

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

#注释

当 $input_filename_or_reference 映射到多个文件/缓冲区并且 $output_filename_or_reference 是单个文件/缓冲区时，输入文件/缓冲区将作为压缩数据流的串联系列存储在 $output_filename_or_reference 中。

#可选参数

一次性函数 bzip2 的可选参数（在大多数情况下）与 "构造函数选项" 部分中定义的 OO 接口中使用的参数相同。例外如下所列

#AutoClose => 0|1

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

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

此参数默认为 0。

#BinModeIn => 0|1

此选项现在是 no-op。所有文件都将以 binmode 读取。

#Append => 0|1

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

• 缓冲区

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

• 文件名

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

• 文件句柄

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

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

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

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

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

默认为 0。

#示例

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

#流式处理

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

$ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 \*STDIN => \*STDOUT' >output.bz2

特殊文件名“ - ”可用作 \*STDIN 和 \*STDOUT 的替身，因此上述内容可以改写为

$ echo hello world | perl -MIO::Compress::Bzip2=bzip2 -e 'bzip2 "-" => "-"' >output.bz2

#从文件系统压缩文件

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

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

my $input = "file1.txt";
bzip2 $input => "$input.bz2"
    or die "bzip2 failed: $Bzip2Error\n";

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

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

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
use IO::File ;

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

#压缩多个文件

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

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

bzip2 '</my/home/*.txt>' => '<*.bz2>'
    or die "bzip2 failed: $Bzip2Error\n";

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

use strict ;
use warnings ;
use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

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

#OO 接口

#构造函数

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

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

成功时返回 IO::Compress::Bzip2 对象，失败时返回 undef。失败时，变量 $Bzip2Error 将包含错误消息。

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

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

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

#文件名

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

#文件句柄

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

#标量引用

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

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

#构造函数选项

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

#AutoClose => 0|1

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

此参数默认为 0。

#Append => 0|1

在追加模式下打开 $output。

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

• 缓冲区

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

• 文件名

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

• 文件句柄

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

此参数默认为 0。

#BlockSize100K => number

指定 bzip2 在压缩过程中使用的 100K 块数。

有效值范围为 1 到 9，其中 9 是最佳压缩。

默认值为 1。

#WorkFactor => number

指定在采用较慢的后备压缩算法之前，bzip2 应付出多少努力。

有效值范围为 0 到 250，其中 0 表示使用默认值 30。

默认值为 0。

#Strict => 0|1

这是一个占位符选项。

#示例

TODO

#方法

#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;

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

TODO

如果成功，则返回 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::Bzip2 对象被销毁（显式或通过引用对象的变量超出范围），此方法将自动调用。例外是 Perl 版本 5.005 至 5.00504 和 5.8.0。在这些情况下，close 方法将自动调用，但直到程序终止时所有活动对象全局销毁时才会调用。

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

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

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

#newStream([OPTS])

用法为

$z->newStream( [OPTS] )

关闭当前压缩数据流并启动一个新的数据流。

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

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

#导入

目前，IO::Compress::Bzip2 不需要任何符号常量。

#:all

导入 bzip2 和 $Bzip2Error。与执行以下操作相同

use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;

#示例

#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::Compress::RawDeflate、IO::Uncompress::RawInflate、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

bzip2 程序的主要网站是 https://sourceware.org/bzip2/。

请参阅模块 Compress::Bzip2

#作者

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

#修改历史记录

请参阅 Changes 文件。

#版权和许可

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

此程序是免费软件；根据与 Perl 本身相同的条款，您可以重新分发或修改它。

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

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