內容

• 名稱
• 語法
• 說明
• 功能介面
  • deflate $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])
  • deflateParams
• 匯入
• 範例
  • Apache::GZip 回顧
  • 使用 Net::FTP
• 支援
• 另請參閱
• 作者
• 修改記錄
• 版權與授權

#名稱

IO::Compress::Deflate - 寫入 RFC 1950 檔案/緩衝區

#語法

use IO::Compress::Deflate qw(deflate $DeflateError) ;

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

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

$DeflateError ;

# 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 1950 中。

若要讀取 RFC 1950 檔案/緩衝區，請參閱配套模組 IO::Uncompress::Inflate。

#函式介面

提供一個頂層函式 deflate，用於在緩衝區和/或檔案之間執行「一次性」壓縮。若要更精細地控制壓縮程序，請參閱 「物件導向介面」 區段。

use IO::Compress::Deflate qw(deflate $DeflateError) ;

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

函式介面需要 Perl5.005 或更新版本。

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

deflate 至少需要兩個參數，$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 是陣列參考，陣列中的每個元素都必須是檔案名稱。

輸入資料將依序從每個檔案中讀取。

在壓縮任何資料之前，將會遍歷整個陣列以確保它只包含有效的檔案名稱。

#輸入檔案 Glob 字串

如果 $input_filename_or_reference 是以字元 "<" 和 ">" 為分隔的字串，deflate 會假設它是一個輸入檔案 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 是以字元 "<" 和 ">" 為分隔的字串，deflate 會假設它是一個輸出檔案 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 中，作為壓縮資料串流的串接系列。

#選用參數

一次性函式 deflate 的選用參數（大部分）與在 "建構函式選項" 區段中定義的 OO 介面中使用的參數相同。例外情況如下所列

#AutoClose => 0|1

此選項套用於任何輸入或輸出資料串流到 deflate 的檔案處理常式。

如果指定 AutoClose，且值為 true，將會導致所有輸入和/或輸出檔案處理常式在 deflate 完成後關閉。

此參數預設為 0。

#BinModeIn => 0|1

此選項現在為 no-op。所有檔案都將以二進位模式讀取。

#Append => 0|1

此選項的行為取決於輸出資料串流的類型。

• 緩衝區

  如果啟用 Append，所有壓縮資料都將附加到輸出緩衝區的結尾。否則，輸出緩衝區將在寫入任何壓縮資料之前清除。

• 檔案名稱

  如果啟用 Append，檔案將以附加模式開啟。否則，檔案的內容（如果有）將在寫入任何壓縮資料之前被截斷。

• 檔案處理常式

  如果啟用 Append，檔案處理常式將透過呼叫 seek 定位到檔案結尾，然後才寫入任何壓縮資料。否則，檔案指標將不會移動。

當指定 Append 並設定為 true 時，它會將所有壓縮資料附加到輸出資料串流。

因此，當輸出為檔案處理常式時，它會在寫入任何壓縮資料之前執行 seek 到 eof。如果輸出為檔案名稱，它將開啟以附加。如果輸出為緩衝區，所有壓縮資料都將附加到現有緩衝區。

相反地，當未指定 Append，或它存在且設定為 false 時，它將執行下列操作。

當輸出為檔案名稱時，它會在寫入任何壓縮資料之前截斷檔案內容。如果輸出為檔案處理常式，其位置不會改變。如果輸出為緩衝區，它將在輸出任何壓縮資料之前被清除。

預設為 0。

#範例

以下是幾個範例，說明此模組的功能。

#串流

這個非常簡單的命令列範例示範了此模組的串流功能。此程式碼會從 STDIN 讀取資料，將其壓縮，並將壓縮後的資料寫入 STDOUT。

$ echo hello world | perl -MIO::Compress::Deflate=deflate -e 'deflate \*STDIN => \*STDOUT' >output.1950

特殊檔案名稱「-」可以用作 \*STDIN 和 \*STDOUT 的替代，因此上述範例可以改寫成

$ echo hello world | perl -MIO::Compress::Deflate=deflate -e 'deflate "-" => "-"' >output.1950

#壓縮檔案系統中的檔案

要讀取檔案 file1.txt 的內容，並將壓縮後的資料寫入檔案 file1.txt.1950。

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;

my $input = "file1.txt";
deflate $input => "$input.1950"
    or die "deflate failed: $DeflateError\n";

#從檔案控制碼讀取並寫入記憶體中緩衝區

要從現有的 Perl 檔案控制碼 $input 讀取，並將壓縮後的資料寫入緩衝區 $buffer。

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;
use IO::File ;

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

#壓縮多個檔案

要壓縮目錄「/my/home」中所有符合「*.txt」的檔案，並將壓縮後的資料儲存在同一個目錄中

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;

deflate '</my/home/*.txt>' => '<*.1950>'
    or die "deflate failed: $DeflateError\n";

如果您想要一次壓縮一個檔案，可以使用這個方法

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;

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

#OO 介面

#建構函式

IO::Compress::Deflate 的建構函式格式如下所示

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

如果成功，它會傳回一個 IO::Compress::Deflate 物件，如果失敗，則會傳回 undef。變數 $DeflateError 會在失敗時包含錯誤訊息。

如果您執行的是 Perl 5.005 或更新版本，則從 IO::Compress::Deflate 傳回的物件 $z 可以像 IO::File 檔案控制碼一樣使用。這表示所有正常的輸出檔案操作都可以使用 $z 執行。例如，要寫入壓縮檔案/緩衝區，您可以使用下列任一種格式

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

強制參數 $output 用於控制壓縮資料的目的地。此參數可以採用下列格式之一。

#檔案名稱

如果 $output 參數是一個簡單的標量，則假設它是一個檔案名稱。這個檔案將會被開啟進行寫入，而壓縮資料將會被寫入其中。

#檔案句柄

如果 $output 參數是一個檔案句柄，壓縮資料將會被寫入其中。字串「-」可以用作標準輸出的別名。

#標量參考

如果 $output 是標量參考，壓縮資料將會儲存在 $$output 中。

如果 $output 參數是任何其他類型，IO::Compress::Deflate::new 將會傳回 undef。

#建構函數選項

OPTS 是下列選項中零個或多個選項的任意組合

#AutoClose => 0|1

這個選項僅在 $output 參數是檔案句柄時才有效。如果指定，且值為 true，則會導致在呼叫 close 方法或銷毀 IO::Compress::Deflate 物件後關閉 $output。

此參數預設為 0。

#Append => 0|1

以附加模式開啟 $output。

這個選項的行為取決於 $output 的類型。

• 緩衝區

  如果 $output 是緩衝區且啟用了 Append，則所有壓縮資料將會附加到 $output 的結尾。否則，在寫入任何資料到 $output 之前，將會清除 $output。

• 檔案名稱

  如果 $output 是檔案名稱且啟用了 Append，則檔案將會以附加模式開啟。否則，在寫入任何壓縮資料到檔案之前，將會截斷檔案的內容（如果有）。

• 檔案處理常式

  如果 $output 是檔案句柄，則在寫入任何壓縮資料到檔案之前，將會透過呼叫 seek 將檔案指標定位到檔案結尾。否則，檔案指標將不會移動。

此參數預設為 0。

#Merge => 0|1

這個選項用於壓縮輸入資料並將其附加到 $output 中現有的壓縮資料串流。最終結果是儲存在 $output 中的單一壓縮資料串流。

在 $output 不是 RFC 1950 資料串流時嘗試使用這個選項會導致致命錯誤。

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::Deflate 匯入。

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

#-Strategy

定義用於調整壓縮的策略。使用以下定義的符號常數之一。

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::Deflate 物件已毀損（明確地或透過變數，其中對物件的參照超出範圍），此方法會自動呼叫。例外為 Perl 版本 5.005 至 5.00504 和 5.8.0。在這些情況下，close 方法會自動呼叫，但直到程式終止時才對所有現存物件進行全域毀損。

因此，如果您希望腳本能夠在所有版本的 Perl 上執行，您應該明確呼叫 close，而不依賴自動關閉。

成功傳回 true，否則傳回 0。

如果在建立 IO::Compress::Deflate 物件時已啟用 AutoClose 選項，且物件與檔案相關聯，底層檔案也會關閉。

#newStream([OPTS])

用法為

$z->newStream( [OPTS] )

關閉目前的壓縮資料串流並開始一個新的串流。

OPTS 包含在建立 $z 物件時可用的任何選項。

請參閱 "建構函數選項" 區段以取得更多詳細資料。

#deflateParams

用法為

$z->deflateParams

待辦事項

#匯入

IO::Compress::Deflate 中的一些方法需要許多符號常數。預設情況下，沒有任何匯入。

#:all

匯入 deflate、$DeflateError 和 IO::Compress::Deflate 可使用的所有符號常數。與執行下列動作相同

use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;

#:constants

匯入所有符號常數。與執行下列動作相同

use IO::Compress::Deflate 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::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::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 gzip@prep.ai.mit.edu 和 Mark Adler madler@alumni.caltech.edu 編寫的。

zlib 壓縮函式庫的主要網站是 http://www.zlib.org。

zlib-ng 壓縮函式庫的主要網站是 https://github.com/zlib-ng/zlib-ng。

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

#作者

此模組是由 Paul Marquess 編寫的，pmqs@cpan.org。

#修改記錄

請參閱 Changes 檔案。

#版權和授權

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

此程式是免費軟體；您可以在與 Perl 相同的條款下重新散布或修改它。

Perldoc 瀏覽器由 Dan Book (DBOOK) 維護。如有任何關於網站本身、搜尋或文件呈現的問題，請透過 GitHub 問題追蹤器 或 電子郵件 與他聯繫。

Perl 文件由 Perl 5 Porters 在 Perl 開發中維護。如有任何關於文件內容或格式的問題，請透過 Perl 問題追蹤器、郵件列表 或 IRC 與他們聯繫。