目錄

• 名稱
• 語法
• 說明
• 功能介面
  • 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 是陣列參考，則陣列中的每個元素都必須是檔案名稱。

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

在解壓縮任何資料前，將會完整掃描陣列以確保它只包含有效的檔名。

#輸入檔案 Glob 字串

如果 $input_filename_or_reference 是由字元「<」和「>」分隔的字串，anyinflate 會假設它是一個輸入檔案 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 是由字元「<」和「>」分隔的字串，anyinflate 會假設它是一個輸出檔案 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 將包含來自每個輸入檔案/緩衝區所有未壓縮資料的串接。

#選用參數

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

#AutoClose => 0|1

此選項套用於任何 anyinflate 的輸入或輸出資料串流，這些串流是檔案句柄。

如果指定 AutoClose，且值為 true，則會在 anyinflate 完成後關閉所有輸入和/或輸出檔案句柄。

此參數預設為 0。

#BinModeOut => 0|1

此選項現在為無操作。所有檔案都將以二進位模式寫入。

#Append => 0|1

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

• 緩衝區

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

• 檔案名稱

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

• 檔案句柄

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

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

因此，當輸出為檔案句柄時，它會在寫入任何未壓縮資料之前執行 seek 到 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 物件，如果失敗，則傳回未定義。變數 $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 模組測試原始 deflate (RFC 1951) 內容。

這不是預設行為的原因是因為 RFC 1951 內容只能透過嘗試解壓縮來偵測。這個程序容易出錯，並且可能導致誤報。

預設為 0。

#ParseExtra => 0|1 如果存在 gzip FEXTRA 標頭欄位且設定了這個選項，它將強制模組檢查它是否符合 RFC 1952 中定義的子欄位結構。

如果 Strict 已開啟，它將自動啟用這個選項。

預設為 0。

#範例

待辦事項

#方法

#read

用法為

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

讀取一區塊壓縮資料（壓縮區塊的大小由建構函式中的 Buffer 選項決定），解壓縮它並將任何未壓縮的資料寫入 $buffer。如果在建構函式中設定了 Append 參數，未壓縮的資料將附加到 $buffer 參數。否則，將覆寫 $buffer。

傳回寫入 $buffer 的未壓縮位元組數，如果為 eof 則傳回 0，如果發生錯誤則傳回負數。

#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 則傳回 0，如果發生錯誤則傳回負數。

#getline

用法為

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

讀取單一行。

此方法完全支援變數 $/（或 $INPUT_RECORD_SEPARATOR 或 $RS，當使用 English 時）來決定什麼構成一行結束。段落模式、記錄模式和檔案 slurp 模式都受支援。

#getc

用法為

$char = $z->getc()

讀取單一字元。

#ungetc

用法為

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

#inflateSync

用法為

$status = $z->inflateSync()

待辦事項

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

#close

$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 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 Browser 由 Dan Book (DBOOK) 維護。如有任何關於網站本身、搜尋或文件呈現的問題，請透過 GitHub 問題追蹤器 或 電子郵件 與他聯繫。

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