內容

• 名稱
• 語法
• 說明
• 函式介面
  • anyuncompress $input_filename_or_reference => $output_filename_or_reference [, OPTS]
    • $input_filename_or_reference 參數
    • $output_filename_or_reference 參數
  • 註解
  • 選用參數
  • 範例
• 物件導向介面
  • 建構函式
  • 建構函式選項
  • 範例
• 方法
  • read
  • read
  • getline
  • getc
  • ungetc
  • getHeaderInfo
  • tell
  • eof
  • seek
  • binmode
  • opened
  • autoflush
  • input_line_number
  • fileno
  • close
  • nextStream
  • trailingData
• 匯入
• 範例
• 支援
• 另請參閱
• 作者
• 修改記錄
• 版權和授權

#名稱

IO::Uncompress::AnyUncompress - 解壓縮 gzip、zip、bzip2、zstd、xz、lzma、lzip、lzf 或 lzop 檔案/緩衝區

#語法

use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

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

my $z = IO::Uncompress::AnyUncompress->new( $input [OPTS] )
    or die "anyuncompress failed: $AnyUncompressError\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()

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

$AnyUncompressError ;

# 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 介面，允許讀取已使用各種壓縮函式庫壓縮的檔案/緩衝區。

支援的格式為

#RFC 1950

#RFC 1951 (選用)

#gzip (RFC 1952)

#zip

#zstd (Zstandard)

#bzip2

#lzop

#lzf

#lzma

#lzip

#xz

模組會自動偵測所支援的壓縮格式中，哪一種格式（如果有）正在使用中。

#功能介面

提供頂層函式 `anyuncompress` 來執行緩衝區和/或檔案之間的「一次性」解壓縮。如要更精細地控制解壓縮程序，請參閱 「OO 介面」 區段。

use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

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

功能介面需要 Perl5.005 或更新版本。

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

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

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

會遍歷整個陣列，以確保它只包含有效的檔案名稱，然後才會解壓縮任何資料。

#輸入 FileGlob 字串

如果 $input_filename_or_reference 是以字元「<」和「>」為分隔符的字串，anyuncompress 會假設它是一個 輸入 FileGlob 字串。輸入是與 FileGlob 相符的檔案清單。

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

#選用參數

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

#AutoClose => 0|1

此選項適用於檔案處理的任何輸入或輸出資料串流至 anyuncompress。

如果指定 AutoClose，且值為 true，則在 anyuncompress 完成後，所有輸入和/或輸出檔案處理將關閉。

此參數預設為 0。

#BinModeOut => 0|1

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

#Append => 0|1

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

• 緩衝區

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

• 檔案名稱

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

• 檔案處理

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

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

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

相反，當未指定 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::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

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

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

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
use IO::File ;

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

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

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

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

如果您想要一次壓縮一個檔案，這會奏效

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

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

#物件導向介面

#建構函式

IO::Uncompress::AnyUncompress 建構函式的格式如下所示

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

傳回 IO::Uncompress::AnyUncompress 物件（成功時）或 undef（失敗時）。變數 $AnyUncompressError 會在失敗時包含錯誤訊息。

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

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

強制參數 $input 用於判斷壓縮資料的來源。這個參數可以採用下列三種格式之一。

#A filename

如果 $input 參數是純量，則假設它是一個檔案名稱。此檔案將開啟以供讀取，並從中讀取壓縮資料。

#A filehandle

如果 $input 參數是檔案處理代碼，則壓縮資料將從中讀取。字串 '-' 可用作標準輸入的別名。

#A scalar reference

如果 $input 是純量參考，則壓縮資料將從 $$input 讀取。

#建構函式選項

下面定義的選項名稱不區分大小寫，並且可以選擇性地加上前綴「-」。因此，以下所有選項都是有效的

-AutoClose
-autoclose
AUTOCLOSE
autoclose

OPTS 是以下選項的組合

#AutoClose => 0|1

此選項僅在 $input 參數是檔案處理代碼時才有效。如果指定，且值為 true，則在呼叫 close 方法或銷毀 IO::Uncompress::AnyUncompress 物件後，將導致檔案關閉。

此參數預設為 0。

#MultiStream => 0|1

允許多個串接的壓縮串流被視為單一壓縮串流。解壓縮將在下列情況之一發生時停止：檔案/緩衝區的結尾已達、遇到錯誤（過早的 eof、損毀的壓縮資料）或串流的結尾沒有緊接著另一個串流的開頭。

此參數預設為 0。

#Prime => $string

此選項將在處理輸入檔案/緩衝區之前解壓縮 $string 的內容。

當壓縮資料嵌入在另一個檔案/資料結構中，且無法在讀取前幾個位元組的情況下找出壓縮資料的開頭時，此選項會很有用。如果是這種情況，解壓縮可以使用此選項用這些位元組進行「啟動」。

#Transparent => 0|1

如果設定此選項，且輸入檔案/緩衝區不是壓縮資料，則模組仍允許讀取它。

此外，如果輸入檔案/緩衝區確實包含壓縮資料，且其後緊接著非壓縮資料，則設定此選項將使此模組將整個檔案/緩衝區視為單一資料串流。

此選項預設為 1。

#BlockSize => $num

讀取壓縮的輸入資料時，IO::Uncompress::AnyUncompress 會以 $num 位元組的區塊讀取。

此選項預設為 4096。

#InputLength => $size

存在此選項時，將限制從輸入檔案/緩衝區讀取的壓縮位元組數目為 $size。此選項可用於壓縮資料串流後方有有用資料且您事先知道壓縮資料串流的精確長度的狀況。

此選項大多用於從檔案處理程式讀取時，此時檔案指標會停留在壓縮資料串流後方的第一個位元組。

此選項預設為關閉。

#Append => 0|1

此選項控制 read 方法對未壓縮資料的處理方式。

如果設為 1，所有未壓縮資料都會附加到 read 方法的輸出參數。

如果設為 0，read 方法的輸出參數內容會被未壓縮資料覆寫。

預設為 0。

#Strict => 0|1

此選項控制在執行解壓縮時是否使用下方定義的額外檢查。當 Strict 開啟時，會執行額外測試；當 Strict 關閉時，則不會執行。

此選項的預設值為關閉。

#RawInflate => 0|1

自動偵測壓縮格式時，嘗試使用 IO::Uncompress::RawInflate 模組測試 raw-deflate (RFC 1951) 內容。

此選項並非預設行為的原因是，RFC 1951 內容只能透過嘗試解壓縮來偵測。此程序容易出錯，而且可能會導致誤判。

預設為 0。

#UnLzma => 0|1

自動偵測壓縮格式時，嘗試使用 IO::Uncompress::UnLzma 模組測試 lzma_alone 內容。

此選項並非預設行為的原因是，lzma_alone 內容只能透過嘗試解壓縮來偵測。此程序容易出錯，而且可能會導致誤判。

預設為 0。

#範例

待辦

#方法

#read

用法為

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

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

傳回寫入 $buffer 的解壓縮位元組數目，如果為檔案結尾則為零，如果發生錯誤則為負數。

#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 的解壓縮位元組數目，如果為檔案結尾則為零，如果發生錯誤則為負數。

#getline

用法為

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

讀取單一行。

此方法完全支援使用變數 $/（或在使用 English 時為 $INPUT_RECORD_SEPARATOR 或 $RS）來決定什麼構成一行的結尾。段落模式、記錄模式和檔案吸入模式皆受支援。

#getc

用法為

$char = $z->getc()

讀取單一字元。

#ungetc

用法為

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

#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::AnyUncompress 物件遭摧毀（明確地或透過參考物件的變數超出範圍），此方法會自動呼叫。例外為 Perl 版本 5.005 至 5.00504 和 5.8.0。在這些情況下，close 方法會自動呼叫，但直到程式終止時所有執行中物件的整體摧毀為止。

因此，如果您希望您的指令碼可以在所有版本的 Perl 上執行，您應該明確呼叫 close，而不是依賴自動關閉。

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

如果在建立 IO::Uncompress::AnyUncompress 物件時已啟用 AutoClose 選項，且物件與檔案相關聯，基礎檔案也會關閉。

#nextStream

用法為

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

跳到輸入檔案/緩衝區中的下一個壓縮資料串流。如果找到新的壓縮資料串流，eof 標記會清除，且 $. 會重設為 0。

如果找到新的串流，傳回 1；如果未找到，傳回 0；如果遇到錯誤，傳回 -1。

#trailingData

用法為

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

在解壓縮完成後，傳回壓縮資料串流之後立即存在的資料（如果有）。只有在遇到壓縮資料串流的結尾後，呼叫此方法才有意義。

當在壓縮資料串流後緊接在後有有用的資訊，且您不知道壓縮資料串流的長度時，可以使用這個選項。

如果輸入是緩衝區，trailingData 會傳回從壓縮資料串流的末尾到緩衝區末尾的所有內容。

如果輸入是檔案控制代碼，trailingData 會傳回在到達壓縮資料串流末尾後，檔案控制代碼輸入緩衝區中剩下的資料。您接著可以使用檔案控制代碼來讀取輸入檔案的其餘部分。

如果輸入是檔案名稱，請不要費心使用 trailingData。

如果您在開始解壓縮前知道壓縮資料串流的長度，您可以透過在建構函式中設定 InputLength 選項，避免使用 trailingData。

#Importing

目前 IO::Uncompress::AnyUncompress 不需要任何符號常數。

#:all

匯入 anyuncompress 和 $AnyUncompressError。與執行下列動作相同

use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

#範例

#支援

一般回饋/問題/錯誤回報應傳送至 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::AnyInflate

IO::Compress::FAQ

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

#作者

此模組由 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 與他們聯繫。